Type Mapping

Skill: Smithy to .NET Type Mapping

Type Mapping Table

Nullability Rules

The AWS SDK for .NET V4 convention:

1. All value types are nullable — bool?, int?, DateTime?, etc. regardless of @required or @default traits
2. Reference types (string, MemoryStream) — nullable by nature, no ? suffix needed in the type declaration
3. Collections — V4 default: null; see Collection Defaults section
4. The @default trait does NOT change nullability — this matches current SDK behavior
5. The @required trait does NOT change nullability — it only affects the [AWSProperty(Required=true)] attribute

Opt-in Strict Nullability (Non-AWS Use)

The generator will support an opt-in mode that respects Smithy's nullability traits (@required, @default, @clientOptional) for non-AWS Smithy models. When disabled (the default for AWS), all value types are nullable regardless of traits.

Collection Defaults

Collections use AWSConfigs.InitializeCollections for SDK V4 backwards compatibility. The generator emits an auto-property initialized to AWSConfigs.InitializeCollections ? new List<T>() : null, plus an internal IsSet{Property}() method that the AWS SDK runtime (and marshallers) call — exact emitted shape in sdk-conventions "Collection Properties".

When AWSConfigs.InitializeCollections is false (V4 default), collections start as null, and an empty list still counts as "set" (the caller cleared the value). When true (V3 compat), collections start empty and an empty list counts as "not set". The IsSet method encodes that rule so callers — including the public reflection API AWSSDKUtils.IsPropertySet — see the correct answer in both modes.

Enums in Collections

An enum surfaces as its ConstantClass only as a structure member's own type. As a list element, a map key, or a map value it is plain string:

This matches C2J: Member.DetermineType passes treatEnumsAsString: true when it recurses into a list member or a map key/value, and only the member's own call passes false. Typing an element as its ConstantClass would be a public-API divergence (Amazon.Lambda.Model.CreateFunctionRequest.Architectures and friends are List<string> in the shipped SDK).

TypeMapper.CollectionElementTarget is the single place the collapse happens. It feeds the .NET type name (MapType via ElementTarget), the element TypeDescriptor (ResolveType with isCollectionValue: true), and PaginationResolver's items element type — so the descriptor's IsEnum is never set on an element, the writers see a plain string leaf, and a paginator's flattened enumerable agrees with the List<string> property it reads from. It takes an already-resolved Shape rather than a ShapeId precisely so PaginationResolver can call it: that runs off a ServiceIndex and has no GenerationContext. Resolves_EnumItemsElement_AsString pins the paginator's side.

A paginator's items element type is a collection element, so it follows the same nullability rule — PaginationResolver derives it via TypeMapper.MapScalarElement (non-nullable, nullable when the list is @sparse), the same call the property type goes through.

An intEnum element maps to a plain non-nullable int (like IntegerShape), so list<intEnum> is List<int> — it does not fail loud. A non-streaming blob element maps to MemoryStream and base64-encodes exactly like a blob body member (list<blob> → List<MemoryStream>). A document element is supported and passes the check. The only leaf RejectUnsupportedCollectionElement still rejects is a @streaming blob: it maps to Stream, is @httpPayload-only, and StringUtils.WriteBase64StringValue takes a MemoryStream, so it can't ride the element path.

C2J's Customizations.OverrideTreatEnumsAsString can flip this per shape. That hook is not implemented (the loader rejects it), so the default (true, i.e. string) is the only behavior. The one enum customization that is implemented is emitPropertyName (keyed by wire value): TypeMapper.EnumMemberName returns it over the derived constant name.

Constrained Shapes

Smithy allows constrained shapes (e.g. a string shape named Uuid with @length or @pattern). These do NOT get wrapper classes — they map to their underlying .NET type:

The constraints flow through to [AWSProperty] attributes on the member that references the shape. When resolving [AWSProperty], check traits on both the member and its target shape:

• @required is on the member
• @length / @range are typically on the target shape (e.g. AuditEvents list has @length(min:1, max:100), so PutAuditEventsRequest.AuditEvents gets [AWSProperty(Required=true, Min=1, Max=100)])

Error Shape Naming

Smithy error shapes often omit the Exception suffix. The naming rules (matching the existing generator's ExceptionShape.Name logic):

• Ends with Exception → keep as-is (e.g. UnsupportedOperationException)
• Ends with Fault → replace Fault with Exception
• Otherwise → append Exception (e.g. ChannelNotFound → ChannelNotFoundException)

Error Shape Members

Error shapes have a message member in the Smithy model, but the generated exception class does not expose it as a property. The message is passed to System.Exception via the constructor and inherited as Exception.Message. The generator filters message out everywhere — the property set, the serialization block, and the unmarshaller alike — since Exception.Message already covers it.

Two base-class adjustments follow (matching ExceptionShape.Members, Member.cs, and StructureGenerator.tt):

• A member named errorType is renamed to the property RequestErrorType — property name only; the wire name stays errorType — so it doesn't hide AmazonServiceException.ErrorType, whose type is the ErrorType enum rather than the member's own type.
• A member named Retryable (on an exception) is emitted with the new modifier, hiding AmazonServiceException.Retryable — CloudHSM's exception models it with a different return type.

Independently of the exception-only rules, a member named Equals on any structure is emitted with new to hide object.Equals(object) (matches StructureGenerator.tt's unconditional Equals check). This is set in TypeMapper.ResolveMembers and flows through every writer.

A response member named ContentLength is not shadowed but omitted from the response class entirely — AmazonWebServiceResponse already declares it and the unmarshaller assigns the inherited property. That rule is writer-level (OperationWriter.WriteResponse, not TypeMapper); see sdk-conventions.

RequestId and ErrorCode get a narrower treatment than message. AmazonServiceException already declares them, so the generator emits no property (one would shadow the base; C2J's StructureGenerator.tt skips them in its property loop). But unlike message they are not filtered from serialization or unmarshalling — C2J's ExceptionSerialization.t4 and JsonRPCExceptionUnmarshaller.tt loop ExceptionShape.Members, which drops only message — so the inherited property is still serialized and read from the error body. Hence ExceptionWriter.ResolveSerializedMembers (serialization block + unmarshaller) keeps them, while the property set is that same set with RequestId/ErrorCode filtered out inline in WriteException. Every other member — including one whose name collides with a non-omitted inherited property (e.g. StatusCode, InnerException) — is emitted as-is as a plain shadowing property and also read from the error body, exactly as C2J does.

Resolving Member Types

To get the .NET type for a structure member:

1. Get the member's Target shape ID
2. GenerationContext.Resolve(target) returns the shape. Prelude shapes (smithy.api#String, etc.) are not in the model's shape map, but Resolve falls back to PreludeShapes, so callers never special-case them — a prelude String comes back as a StringShape like any other. Map the resolved shape's type from the table:
   • Simple/scalar shape → map its type from the table
   • Structure/union → use the generated class name
   • List → List<{resolve member.Target}>
   • Map → Dictionary<string, {resolve value.Target}> (an enum key is string, never its ConstantClass)
   • Enum → its ConstantClass subclass as a member's own type, string inside a collection (see Enums in Collections)
   • Constrained string shapes (e.g. Uuid) resolve to a StringShape → string (no wrapper)

Prelude Shape Mapping

These shapes are implicit (not in the model JSON) and map directly. See the Type Mapping Table above for the positions each one is supported in — Blob (non-streaming) and Document map here and are accepted as body members and collection elements, but not everywhere (e.g. a header/query blob throws):