Add inline collection declarations for Smithy IDL 2.1#3134
Open
sugmanue wants to merge 31 commits into
Open
Conversation
Add a SerializationMode enum to the Trait interface with three modes: ALL (default), AST_ONLY, and NONE. This replaces the binary isSynthetic check in serializers with a more granular control that allows traits to be serialized in the JSON AST but not in the IDL. Update ModelSerializer and SmithyIdlModelSerializer to use the new serializationMode() method. Existing behavior is preserved: traits with isSynthetic()=true default to NONE, all others default to ALL.
Add SyntheticShapeTrait in the smithy.synthetic namespace that marks assembler-generated shapes from inline collection syntax. It uses the new AST_ONLY serialization mode so it appears in JSON AST but not IDL. Add SyntheticShapeNaming utility that generates deterministic names for inline list and map shapes using the _Synthetic prefix convention.
Validates that synthetic shapes have no user-applied traits (ERROR) and warns if user-defined shapes use the reserved _Synthetic name prefix. Registered as a critical validator so it runs early and blocks further validation on failure.
Parse [Target] as inline list and {Key: Value} as inline map in member
target positions. The parser creates synthetic list/map shapes with the
@Synthetic trait and deterministic names. Nesting is supported up to 3
levels deep. Version-gated to Smithy IDL 2.1+.
smithy-syntax: Add MEMBER_TARGET, INLINE_LIST_TARGET, and
INLINE_MAP_TARGET tree types. Update formatter to render inline syntax.
smithy-model: Add parseMemberTarget dispatch in IdlModelLoader that
handles LBRACKET/LBRACE tokens and creates synthetic shapes.
Track emitted synthetic shape IDs to avoid registering duplicate definitions when multiple members use the same inline collection type (e.g., two members both using [String]).
Fix target resolution for synthetic shape members to correctly resolve prelude shapes (String, Integer, etc.) and use statements. Add TraitService provider for SyntheticShapeTrait to support JSON AST deserialization. Add valid model test (inline-collections.smithy/.json) verifying list, map, and nested inline collections produce correct synthetic shapes. Add error test verifying version gating rejects inline syntax in 2.0.
Synthetic shapes are excluded from top-level serialization. When a
member targets a synthetic shape, the serializer emits inline syntax
([Target] or {Key: Value}) instead of the shape ID. Handles nested
inline collections recursively.
Synthetic shapes are filtered separately from inline IO shapes since
they are unrelated concepts with different serialization contexts.
Add IDL round-trip test for inline collections.
Synthetic shapes are assembler-generated implementation details, not API surface. Filter them from AddedShape and RemovedShape diff evaluators to avoid noisy events when inline collections are added or removed.
…ff tests Prevent the ModifiedTrait evaluator from producing events about the smithy.synthetic#generated trait, keeping diff output clean of implementation details. Add diff test cases covering: adding/removing inline collections, no-change scenarios, inline-to-explicit migration, explicit-to-inline migration, and inline-to-explicit with constraint traits.
Update the migrate command to produce version 2.1 instead of 2.0. Update the skip pattern to match any 2.x version so already-migrated files are not re-processed. Update all test expected output files.
Test that structurally equivalent inline collections share one synthetic shape, that inline collections work in union members, that use statements are resolved correctly, and that nesting beyond 3 levels produces an error.
Add MemberTarget, InlineListTarget, and InlineMapTarget productions.
ExplicitShapeMember now targets MemberTarget instead of ShapeId
directly, allowing [Target] and {Key: Value} syntax in member
target positions.
Document the [Target] and {Key: Value} syntax, nesting, synthetic
shape naming, grouping, and limitations.
Update quickstart to use inline collection syntax directly, bump version to 2.1, and add a note explaining the new syntax.
Suppress IgnoredDuplicateDefinition NOTE for synthetic shapes in LoaderShapeMap so cross-file deduplication is silent. Add SyntheticShapeNamingTest with 6 unit tests covering name generation edge cases. Add error test for user shapes using the reserved _Synthetic prefix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces inline collection syntax for Smithy IDL 2.1, allowing list and map shapes to be declared directly in member target positions:
This is syntactic sugar: the assembler generates synthetic shapes (
_SyntheticListOfString,_SyntheticMapOfStringToString, etc.) that are shared across structurally equivalent usages.Changes
Core model (
smithy-model)Version.java: Refactored to use a bitmask for feature flags. AddedINLINE_COLLECTIONSflag for 2.1.Trait.java: AddedSerializationModeenum (ALL,AST_ONLY,NONE) andserializationMode()method to control where traits are serialized.SyntheticShapeTrait: New trait insmithy.synthetic#generatednamespace. UsesAST_ONLYserialization, persists in JSON AST but not IDL. Registered via TraitService SPI.SyntheticShapeNaming: Utility for generating deterministic synthetic shape names from target types.SyntheticShapeValidator: Critical validator that errors if traits are applied to synthetic shapes, and warns if user shapes use the_Syntheticprefix.IdlModelLoader: Parses[Target]and{Key: Value}in member target positions. Creates synthetic shapes with deduplication. Version-gated to 2.1+. Nesting capped at 3 levels.SmithyIdlModelSerializer: Emits inline syntax for members targeting synthetic shapes. Excludes synthetic shapes from top-level serialization.ModelSerializer: UsesserializationMode()instead ofisSynthetic()for trait filtering.Syntax tree (
smithy-syntax)TreeType.java: AddedMEMBER_TARGET,INLINE_LIST_TARGET,INLINE_MAP_TARGETtree types.FormatVisitor.java: Formats inline collections as[Target]and{Key: Value}.Diff tool (
smithy-diff)AddedShape/RemovedShape: Suppress events for synthetic shapes.ModifiedTrait: AddedSyntheticShapeTraittoIGNORED_TRAITS.CLI (
smithy-cli)MigrateCommand: Updated to emit version"2.1"and skip any 2.x files.Documentation
spec/idl.rst: ABNF grammar update, new "Inline collection declarations" section, version statement note, examples in List/Map/Structure/Union sections.spec/aggregate-types.rst: Inline syntax notes in List and Map sections.spec/model.rst: Member shapes note, Shape ID_Syntheticprefix reservation, trait restriction note.spec/json-ast.rst: New "Synthetic shapes in the JSON AST" section.spec/type-refinement-traits.rst: Note that@sparsecannot apply to synthetics.spec/selectors.rst: Example for selecting synthetic shapes.guides/style-guide.rst: Recommendation to prefer inline for single-use collections.guides/evolving-models.rst: Migration guidance for inline vs explicit.guides/building-codegen/mapping-shapes-to-languages.rst: Synthetic shape naming guidance.guides/building-codegen/using-the-semantic-model.rst: ShapeVisitor note.guides/model-validation-examples.rst: Selector note for excluding synthetics.guides/smithy-build-json.rst: Tip for selecting synthetics in projections.quickstart.rst: Forward-looking tip about inline syntax.designs/inline-collections.md: Design document.Testing
Limitations
@sparse,@uniqueItems,@lengthon the collection). Use explicit shape definitions for these.applystatements cannot target synthetic shapes.