Crate aws_smithy_schema

Expand description

Runtime schema types for Smithy shapes.

This crate provides the core types for representing Smithy schemas at runtime, enabling protocol-agnostic serialization and deserialization. The two central types are Schema (a runtime descriptor of a Smithy shape) and ShapeId (a Smithy shape identifier). Both are parameterized over a lifetime 'a that names the data their string fields and member references borrow from.

§API stability

Items marked #[doc(hidden)] are not part of the public API. They exist for generated code and the shape_id! macro to call, and may change or disappear in any release.

§Construction patterns

§`Schema<'static>` — the codegen-emitted form

Generated SDK code emits every schema as a static of type Schema<'static>, built at compile time via const fn constructors and with_* setters. The Smithy prelude entries in this crate (prelude::STRING, prelude::INTEGER, etc.) follow the same pattern. Because the entire schema graph lives in the binary’s data segment, there is no startup cost and no heap allocation on the hot serde path.

use aws_smithy_schema::{shape_id, Schema, ShapeId, ShapeType};

const SHAPE_ID: ShapeId<'static> = shape_id!("ns", "MyShape");
static MY_SHAPE_SCHEMA: Schema<'static> = Schema::new(SHAPE_ID, ShapeType::String);
assert_eq!(MY_SHAPE_SCHEMA.shape_id().as_str(), "ns#MyShape");

Declare schemas as statics, not consts. A const is copied at every use, so each use gets its own empty extension cache, and the work cached on it is repeated.

§`Schema<'a>` — runtime construction

Hand-written code may construct schemas at any lifetime; this is the path used by test fixtures and (in the future) by dynamic clients that load a Smithy model at runtime. Every value referenced by the schema must outlive the schema itself; the borrow checker enforces this. See Schema::new_struct for a worked example.

Wire-format trait values follow the same rule and may borrow from storage the caller owns, such as an arena holding the parsed model text — with one exception. Schema::with_http_header requires &'static str, because the HTTP binder passes header names to an API that needs Cow<'static, str>. Use intern_header_name to obtain a suitable &'static str from a runtime string; it deduplicates, so the cost is bounded by the number of distinct header names in the model.

§Trait maps and the `LazyLock` discipline

The serde traits a schema cares about (@jsonName, HTTP bindings, etc.) are stored as inline typed Option fields on the schema and accessed via direct field reads. Unknown or custom traits go through a fallback TraitMap reachable from Schema::with_traits.

Schema::with_traits accepts an &'a std::sync::LazyLock<TraitMap>, so the LazyLock must outlive any schema that references it. Codegen places both in statics (the LazyLock is 'static, the schema is Schema<'static>); runtime-constructed schemas must arrange the lifetimes manually using standard borrow-check discipline.

§Schema extensions

Codecs and protocols often need data derived from a schema, such as a pre-encoded wire name or a member lookup table, that is the same on every request. Schema::extension computes such data once per schema and caches it on the schema, keyed by a SchemaExtensionKey that any crate can declare. Every schema carries the cache, whether it was generated, written by hand, or built from a model at runtime. See the extension module.

Because of that cache, Schema has interior mutability and drop glue. The constructors and with_* setters remain const fns, so schemas can still be initialized at compile time as statics, and a const can still refer to one (const S: &Schema<'static> = &MY_STATIC;). Two constant-evaluation patterns are not possible: a const item cannot call a method that reads a schema static, and a const or static cannot borrow a temporary Schema (&Schema::new(..)). Declare the schema as a static and borrow that instead.

§Variance

Schema<'a>, ShapeId<'a>, and the typed trait wrappers are covariant in 'a. Covariance is what lets a &'static Schema<'static> (the codegen form) coerce implicitly into a &Schema<'_> argument at any call site, with no annotation needed at the call site. Compile-time assertion functions in this crate enforce covariance; if a future field change would break it, the build fails before any downstream code is affected.

Modules§

codec: Format codecs that pair a shape serializer with a matching deserializer.
document: Document shape serde and the discriminated-document conversion extension.
error_envelope: Shared helpers for parsing AWS protocol error envelopes (error-code sanitization and the awsQueryCompatible header), used by the JSON and CBOR codecs.
extension: Derived data that runtime components compute once per schema and cache on it.
header_omit_settings: Settings controlling which HTTP headers are omitted during serialization.
http_protocol: HTTP client-protocol building blocks: HTTP bindings and RPC payloads.
prelude: Schemas for the Smithy prelude shapes (smithy.api#String, smithy.api#Integer, and so on).
protocol: Client protocol abstraction for serializing requests and deserializing responses.
registry: Runtime type and error registries for resolving shapes by ShapeId.
serde: Shape serialization and deserialization traits and their error type.
traits: Runtime representations of the Smithy serialization traits carried on a schema.

Macros§

shape_id: Creates a ShapeId from a namespace and shape name at compile time.

Structs§

AnnotationTrait: An annotation trait (no value), e.g. @sensitive, @sparse, @httpPayload.
DocumentTrait: A trait with a Document value, used for unknown/custom traits.
Schema: A Smithy schema — a lightweight runtime representation of a Smithy shape.
ShapeId: A Smithy Shape ID, parameterized over the lifetime of its component strings.
StringTrait: A trait with a string value, e.g. @jsonName("foo"), @xmlName("bar").
TraitMap: A map of traits keyed by their Shape ID.

Enums§

PayloadHint: Whether a structure has an @httpPayload member that supplies its own body framing, ex: a member carrying @httpPayload whose target is a structure or a union.
ShapeType: Enumeration of Smithy shape types.

Traits§

Trait: Trait representing a Smithy trait at runtime.

Functions§

intern_header_name: Interns a header name so it can be attached to a runtime-materialized schema.