Marshalling

Skill: Marshalling

This skill states the emitted output. Where a rule exists only for parity with the legacy C2J generator, it says so; everything else follows from the Smithy spec.

File Layout

Under Generated/Model/Internal/MarshallTransformations/, all partial:

An operation output already named {Operation}Response that a member also targets is typed with the {Operation}Response class itself (no separate model class); its structure unmarshaller is {Shape}StructureUnmarshaller, since {Shape}Unmarshaller is the operation's response unmarshaller. No C2J service has this shape, so there is no parity target.

Structure (un)marshaller class names come only from GenerationContext.StructureMarshallerName / StructureUnmarshallerName. TypeDescriptor.MarshallerName / UnmarshallerName carry them for a structure target; writers read those (or the context, when declaring the class or naming the file) and never compose {Shape}Marshaller / {Shape}Unmarshaller themselves, so a naming rule needs no per-protocol code.

Structure marshallers expose public readonly static {Shape}Marshaller Instance = new {Shape}Marshaller();. Operation marshallers/unmarshallers expose a private static instance behind a public Instance property.

Request Marshaller Scaffolding

Every request marshaller emits, in this order:

1. new DefaultRequest(publicRequest, "Amazon.{ServiceName}"), then @requestCompression (below).
2. Content-Type (protocol-dependent, or the overrideContentType customization when set — below), omitted for GET/DELETE and for operations with no body.
3. HeaderKeys.XAmzApiVersion (the service shape's version) and HttpMethod.
4. @httpQuery members, then @httpQueryParams; @httpPrefixHeaders, then @httpHeader members.
5. @httpLabel members as AddPathResource calls, then request.ResourcePath set to the @http uri template (labels left as {name} for the runtime to substitute).
6. The body (below), @httpChecksumRequired, @unsignedPayload, UseQueryString, @endpoint host prefix, return request.

An operation that requires HTTP/2 pins request.HttpProtocolVersion = System.Net.HttpVersion.Version20 (under #if NET8_0_OR_GREATER) right after the DefaultRequest. Which operations require it comes from the protocol trait's version lists, where eventStreamHttp defaults to http when absent or empty:

overrideContentType customization

The service-level overrideContentType customization (a top-level string in *.customizations.json, read into GenerationContext.Customizations.OverrideContentType) hard-codes the request Content-Type: request.Headers["Content-Type"] = "{value}";. On restJson1 it replaces the per-operation value (including the blob-payload default) but is still skipped for input event streams and GET/DELETE; it's emitted even for body-less operations. On awsJson it replaces only the versioned Content-Type; X-Amz-Target is unchanged. A handful of restJson1 services use it to send application/x-amz-json-1.1 instead of the default application/json (finspace, finspace-data, lex.v2), matching C2J.

Member Placement

Every query/header/label member is IsSet-guarded. A @required query member (an idempotency token excepted) first throws Amazon{BaseName}Exception("Request object does not have required field {Prop} set") when unset: string.IsNullOrEmpty for a string/enum, == null for anything else. Body members get no required check.

List query/header bindings accept list<string>/list<enum> (an enum element is a plain string, see type-mapping) and value-type element lists (int, long, bool, double, float, timestamp, intEnum), matching C2J. A non-scalar element (blob, structure, nested list/map) fails loud in both positions, as does a @sparse value-type list (a sparse string/enum list is accepted). A header list<timestamp> is only supported with the default/http-date format (the runtime helper always emits RFC822).

A single member may carry @httpQueryParams: a map<string, string> or map<string, list<string>> whose entries each become query params under the @httpQuery rules (a list<string> value repeats the key via request.ParameterCollection; a map<string, string> adds StringUtils.FromString(kvp.Value) via request.Parameters). It's emitted after the explicit @httpQuery members, each entry guarded by a ContainsKey check that skips keys already set, so an explicit @httpQuery wins the collision per the Smithy precedence rule. The guard intentionally does NOT cover query literals in the @http uri (those live in request.SubResources), matching C2J so migration doesn't change wire behavior. The map is request-only and never enters the body; its presence sets request.UseQueryString = true.

A single member may carry @httpPrefixHeaders: a map<string, string> whose entries each become a header {prefix}{key} (an IsSet guard, then a foreach assigning request.Headers[$"{prefix}{kvp.Key}"] = kvp.Value;). It's emitted before the explicit @httpHeader members, so a colliding name (only possible with an empty prefix) is overwritten by the later @httpHeader assignment, per the Smithy precedence rule. Valid on request, response and error structures. The map value must be a string (anything else fails loud).

Wire Name Resolution

@jsonName if present, else the Smithy member name verbatim. awsJson1.x ignores @jsonName (see below).

Request Body Serialization

JSON (restJson1, awsJson1.x)

When any member is body-bound, or the @httpPayload is a structure or document, the marshaller writes a Utf8JsonWriter body over a PooledContentStream (#if NETFRAMEWORK: a MemoryStream copied to request.Content). Each body member is IsSet-guarded, then written per Type → Marshal/Unmarshal under its wire name.

• Structures dispatch to {Shape}Marshaller.Instance; lists/maps loop and recurse to any depth. Map keys are always strings.
• Collection leaves: string, value-type scalar, structure, document, or non-streaming blob. Non-sparse value-type leaves are non-nullable (see type-mapping), so they write bare: no .Value unwrap and no float/double NaN guard (both are member-only). @timestampFormat is honored on leaves.
• @sparse leaves are nullable and JSON nulls are written, matching C2J. A sparse list null-guards its value-type and blob elements (a null string/structure/document already serializes as null); a sparse map null-guards every value kind.
• Float/double members branch through StringUtils.IsSpecial{Float,Double}Value so NaN/±Infinity serialize as strings.

Structure marshallers loop the structure's own members with the same rules. A request event-stream event is the one exception: the publisher marshaller calls {Event}Marshaller with the JSON object already open, then reads context.Request.EventHeaders and context.Request.Content. Event members route by trait:

• @eventHeader → IsSet-guarded EventStreamHeader("{memberName}") (never @jsonName) with the typed setter for the target shape (SetString string/enum, SetBool/SetInt32/SetInt64/SetTimestamp with .Value, SetByteBuf(….ToArray()) blob), added to EventHeaders. Any other target fails loud.
• @eventPayload → IsSet-guarded: blob Request.Content = ….ToArray(), string/enum Encoding.UTF8.GetBytes(…) (publisher sends octet-stream / text/plain, C2J parity); structure/union {Type}Marshaller.Instance.Marshall(…, context) into the open object (the protocol tests expect the bare structure as the payload, not one wrapped under the member name). List/map fail loud.
• Everything else is an ordinary body member (the implicit payload).

@httpPayload (request)

A @httpPayload member IS the entire body: no wrapping object/property name, no other member in the body (Smithy: all others are header/query/label). No IsSet guard (matches C2J), except string/enum.

• String (enum too) → text/plain (or the target's @mediaType value when present), no writer scaffold: if (publicRequest.IsSet{Prop}()) { request.Content = System.Text.Encoding.UTF8.GetBytes(publicRequest.{Prop}); }. The guard diverges from C2J, whose unguarded GetBytes throws on an unset optional payload (DOTNET-8852).

• Structure (a union too) → application/json; the scaffold, then the target's marshaller as the body object (WriteStartObject → {Type}Marshaller.Instance.Marshall(publicRequest.{Prop}, context) → WriteEndObject).

• Document → application/json; the scaffold, then Amazon.Runtime.Documents.Internal.Transform.DocumentMarshaller.Instance.Write(writer, publicRequest.{Prop}); with NO WriteStartObject/WriteEndObject wrapping (the document is the whole JSON value). No C2J precedent.

• Blob (MemoryStream, or Stream when @streaming) → application/octet-stream (or the target's @mediaType value; overrides the top application/json). Always assigns request.ContentStream = publicRequest.{Prop} ?? new MemoryStream(); first and ends with the Content-Type override, except when the input also has an @httpHeader("Content-Type") member: that header is emitted before the blob block and must win, so the blob's type moves to the top Content-Type line and the trailing override is dropped (restJson1 TestPayloadBlob). The Content-Length handling in between branches on the operation's aws.auth#unsignedPayload and the blob's @requiresLength (C2J parity):

  • @streaming + @unsignedPayload, no @requiresLength → seek to start and set Content-Length when the stream is seekable, else Transfer-Encoding: chunked.
  • @streaming + @requiresLength → the stream MUST be seekable (throws InvalidOperationException otherwise), then always sets Content-Length. @requiresLength wins over the unsigned chunked path.
  • otherwise → seek when seekable, always set Content-Length (no chunked).

  Separately, aws.auth#unsignedPayload on the operation emits request.DisablePayloadSigning = true; after the body block, for any body kind.

List and map payloads fail loud.

@requestCompression and @httpChecksumRequired (request)

Both are one emitted call to a runtime helper in Amazon.Runtime.Internal.Util, at opposite ends of the body.

• @requestCompression → CompressionAlgorithmUtils.SetCompressionAlgorithm(request, CompressionEncodingAlgorithm.{encoding}); right after new DefaultRequest(...). encodings is a preference list: the first supported entry wins and unsupported ones are skipped (["br", "gzip"] emits gzip); gzip is the whole supported set (CompressionEncodingAlgorithm has only NONE and gzip). When nothing in the list is supported we throw, where C2J warns and emits no call: silently dropping compression changes wire behavior with no signal. A @streaming @requiresLength payload is rejected (Smithy forbids it; the compressed length isn't known until the stream has been read).
• @httpChecksumRequired → ChecksumUtils.SetChecksumData(request); after body serialization (the checksum covers the body), before the DisablePayloadSigning line. This is the legacy MD5-only trait. C2J also treats the flexible aws.protocols#httpChecksum as MD5-required; we deliberately don't (that trait is rejected as unsupported), so flexible-checksum operations stay off the MD5 path.

@endpoint host prefix (request)

An operation's @endpoint trait sets request.HostPrefix (the resolver prepends it to the endpoint host). Emitted last, after UseQueryString, before return.

• Static (no labels) → request.HostPrefix = $"data.";
• Labeled → each @hostLabel member is captured into an anonymous hostPrefixLabels object (field = modeled member name, value = StringUtils.FromString(publicRequest.{Prop})), validated with HostPrefixUtils.IsValidLabelValue (throws Amazon{Service}Exception naming the label and the 1–63 alphanumeric/dash rule), then interpolated into the prefix ({name} → {hostPrefixLabels.name}).

Response Unmarshaller Body

The body loop is while (context.ReadAtDepth(targetDepth, ref reader)) with a context.TestExpression("{wireName}", targetDepth, ref reader) guard per member assigning unmarshalledObject.{Prop} = {Unmarshaller}.Instance.Unmarshall(context, ref reader) then continue. A response whose members are all headers (or empty) emits no reader loop at all.

• Lists: new JsonListUnmarshaller<T, TUnmarshaller>(TUnmarshaller.Instance)
• Maps: new JsonDictionaryUnmarshaller<string, V, StringUnmarshaller, VU>(StringUnmarshaller.Instance, VU.Instance) (key is always string/StringUnmarshaller).
• Scalars per Type → Marshal/Unmarshal. Body timestamps are read format-agnostically, so epoch and date-time collections unmarshal identically.
• Nested collections compose recursively: a map-of-list is JsonDictionaryUnmarshaller<string, List<T>, StringUnmarshaller, JsonListUnmarshaller<T, TU>>(...). An enum leaf (and an enum key) is string/StringUnmarshaller, never a ConstantClass generic argument; a non-streaming blob leaf is MemoryStream/MemoryStreamUnmarshaller.

@httpPayload (response)

A @httpPayload output member IS the whole body (replaces the named-field loop; other members are header-bound), into unmarshalledObject:

• String → using (var sr = new StreamReader(context.Stream)) { unmarshalledObject.Body = sr.ReadToEnd(); }
• Structure → reader + if (reader.Reader.IsFinalBlock) return unmarshalledObject; + {Type}Unmarshaller.Instance.Unmarshall(context, ref reader).
• Document → the structure scaffold with Amazon.Runtime.Documents.Internal.Transform.DocumentUnmarshaller.Instance. C2J models a document as a structure flagged document: true, so its output takes the structure-payload branch; we emit the same (bedrock-agentcore GetAgentCardResponse).
• Blob (non-streaming, MemoryStream) → Amazon.Util.AWSSDKUtils.CopyStream(context.Stream, ms) into a new MemoryStream; assigned only when ms.Length > 0, so an empty body leaves the property null (matches C2J).
• Streaming blob (@streaming, Stream) → assigns the raw context.Stream unbuffered and the unmarshaller class overrides public override bool HasStreamingProperty => true (matches C2J, see Polly SynthesizeSpeech).

@httpHeader members read from context.ResponseData after. An @httpPayload error member fails loud: C2J never bound an error body to a payload, and emitting a never-populated property would be worse.

@httpResponseCode (response)

An @httpResponseCode output member (an integer) is populated from the HTTP status code itself, unmarshalledObject.{Prop} = (int)context.ResponseData.StatusCode;, not read from the body or a header. Matches C2J. On an error the trait "is simply ignored" (Smithy spec) and the member falls through to the body like any ordinary member.