From dc07fe1ec6473606eacefc2c92d0a1a6efadc10f Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 21 Jan 2022 16:05:31 +0100 Subject: [PATCH 1/5] Add default trait docs --- docs/source/1.0/guides/evolving-models.rst | 11 +- .../1.0/spec/core/constraint-traits.rst | 1 + .../1.0/spec/core/type-refinement-traits.rst | 144 ++++++++++++++++++ 3 files changed, 153 insertions(+), 3 deletions(-) diff --git a/docs/source/1.0/guides/evolving-models.rst b/docs/source/1.0/guides/evolving-models.rst index bae73a12802..a4a54abeb99 100644 --- a/docs/source/1.0/guides/evolving-models.rst +++ b/docs/source/1.0/guides/evolving-models.rst @@ -57,15 +57,20 @@ Updating structures The following changes to structure shapes are backward-compatible: #. Adding new optional members to a structure. -#. Removing the :ref:`required-trait` from a structure member marked with - the :ref:`input-trait`. +#. Removing the :ref:`required-trait` from a structure member when the + structure is marked with the :ref:`input-trait`. +#. Removing the :ref:`required-trait` from a structure member and replacing + it with the :ref:`default-trait`. The following changes to a structure are not backward-compatible: #. Renaming a member. #. Removing a member. #. Changing the shape targeted by a member. -#. Adding the required trait to a member. +#. Adding the :ref:`required-trait` to a member. +#. Removing the :ref:`default-trait` from a member. +#. Adding the :ref:`default-trait` to a member that was not previously marked + with the :ref:`required-trait`. Booleans and API evolution diff --git a/docs/source/1.0/spec/core/constraint-traits.rst b/docs/source/1.0/spec/core/constraint-traits.rst index 7e54d085d0a..c6c153eb643 100644 --- a/docs/source/1.0/spec/core/constraint-traits.rst +++ b/docs/source/1.0/spec/core/constraint-traits.rst @@ -589,6 +589,7 @@ in a response. .. seealso:: :ref:`recommended-trait` + :ref:`default-trait` .. smithy-trait:: smithy.api#uniqueItems diff --git a/docs/source/1.0/spec/core/type-refinement-traits.rst b/docs/source/1.0/spec/core/type-refinement-traits.rst index 3e946cb86b2..12f96bdd02d 100644 --- a/docs/source/1.0/spec/core/type-refinement-traits.rst +++ b/docs/source/1.0/spec/core/type-refinement-traits.rst @@ -67,6 +67,150 @@ The :ref:`prelude ` contains predefined simple shapes that can be used in all Smithy models, including boxed and unboxed shapes. +.. smithy-trait:: smithy.api#default + +.. _default-trait: + +----------------- +``default`` trait +----------------- + +Summary + Marks a structure member as having a default, zero value. +Trait selector + ``structure > member :not(> :test(union, structure > :test([trait|required])))`` + + A member of a structure that does not target a union or structure. +Value type + Annotation trait. + +The default trait can be applied to structure members to indicate that the targeted +shape has a default, zero value. + +The following example defines a structure with a `@default` "title" member that +has a default zero value: + +.. code-block:: smithy + + structure Message { + @default + title: String // defaults to "" + } + +Default zero values +=================== + +The following table describes the default zero value of each kind of shape. +Programming languages and code generators that cannot initialize structure +members with the following default values SHOULD continue to represent those +members as nullable as this is semantically equivalent to the default zero +value. + +.. list-table:: + :header-rows: 1 + :widths: 10 10 80 + + * - Shape Type + - Zero Value + - Description + * - boolean + - ``false`` + - Boolean false. + * - numbers + - ``0`` + - Numeric zero. + * - string + - empty string + - Strings with the enum trait also have the same default value. + * - blob + - empty blob + - This includes blob shapes marked with the :ref:streaming-trait`. + * - timestamp + - Unix epoch + - Zero seconds since the epoch (for example, ``0`` or + ``1970-01-01T00:00:00Z``). + * - document + - ``null`` + - A null document value. + * - list + - empty list + - + * - set + - empty set + - + * - map + - empty map + - + * - structure + - empty structure + - Structures only have a default zero value if none of the members of + the structure are marked with the :ref:`required-trait`. + * - union + - N/A + - Unions have no default value. A union MUST be set to one of its + variants for it to be valid, and unions have no default variant. + + +Constraint validation +===================== + +Constraint traits are not evaluated on structure members marked with the +default trait when the value of the member is the default value. + + +Guidance on code generation +=========================== + +Code generated types for structures SHOULD use the default and +:ref:`required ` traits to provide member accessors that always +return non-null values. + +- When the default trait is present on a member, the corresponding accessor + SHOULD always return a non-null value by defaulting missing members with + their zero values. +- When the :ref:`required-trait` is present on a member, the corresponding + accessor SHOULD always return a non-null value. +- Smithy implementations in languages like TypeScript that do not provide a kind + of constructor or builder to create structures may not be able to set default + values, precluding them from being able to treat required and default + members as non-null. +- Because the :ref:`required-trait` can be backward-compatibly removed from + members of structures marked with the :ref:`input-trait` (that is, the input + of an operation), code generators MUST generate code that does not break if + the required trait is removed from these members. For example, this could + mean generating these shapes as a kind of builder pattern or using all + optional members. + + +Guidance on protocol design +=========================== + +Protocols MAY choose if and how the default trait impacts serialization and +deserialization. However, protocol designers should consider the following +best-practices: + +1. Serializing the default zero value of a member marked with the default + trait can lead to unintended information disclosure. For example, consider + a newly introduced structure member marked with the default trait that is + only exposed to customers of a service that are allowlisted into a private + beta. Serializing the zero values of these members could expose the feature + to customers that are not part of the private beta because they would see + the member serialized in messages they receive from the service. +2. Protocol deserialization implementations SHOULD tolerate receiving a + serialized default zero value. This also accounts for older clients that + think a structure member is required, but the service has since transitioned + the member to use the default trait. +3. Client implementations SHOULD tolerate structure members marked as + :ref:`required ` that have no serialized value. For example, + if a service migrates a member from required to default, then older clients + SHOULD gracefully handle the zero value of the member being omitted on the + wire. In this case, rather than failing, a client SHOULD set the member + value to its default zero value. Failing to deserialize the structure is a + bad outcome because what the service perceived as a backward compatible + change (i.e., replacing the :ref:`required-trait` with the default trait) + could break previously generated clients. + + .. smithy-trait:: smithy.api#error .. _error-trait: From 2a470f24da3e12fcc2863ca635823df3b23ceefc Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 21 Jan 2022 16:11:24 +0100 Subject: [PATCH 2/5] Remove box trait --- docs/source/1.0/guides/evolving-models.rst | 9 --- .../source/1.0/spec/aws/aws-json.rst.template | 4 +- .../1.0/spec/aws/aws-restjson1-protocol.rst | 4 +- docs/source/1.0/spec/core/model.rst | 10 +--- .../1.0/spec/core/type-refinement-traits.rst | 56 ------------------- 5 files changed, 5 insertions(+), 78 deletions(-) diff --git a/docs/source/1.0/guides/evolving-models.rst b/docs/source/1.0/guides/evolving-models.rst index a4a54abeb99..66a4afeaf25 100644 --- a/docs/source/1.0/guides/evolving-models.rst +++ b/docs/source/1.0/guides/evolving-models.rst @@ -100,15 +100,6 @@ The following changes are backward-incompatible: #. Changing the shape targeted by a union member. -Boxed shapes -============ - -The :ref:`box-trait` is used to influence code generation in various -programming languages. It is a backward-incompatible change for the ``box`` -trait to be added or removed from a shape because it will affect types -generated by tooling that uses Smithy models. - - Sparse lists and maps ===================== diff --git a/docs/source/1.0/spec/aws/aws-json.rst.template b/docs/source/1.0/spec/aws/aws-json.rst.template index bd8ae5c5a90..089ccf0b9cb 100644 --- a/docs/source/1.0/spec/aws/aws-json.rst.template +++ b/docs/source/1.0/spec/aws/aws-json.rst.template @@ -121,9 +121,7 @@ to convert each shape type: - JSON object. Each member value provided for the structure is serialized as a JSON property where the property name is the same as the member name. The :ref:`jsonName-trait` can be used to serialize - a property using a custom name. A null value MAY be provided or - omitted for a :ref:`boxed ` member with no observable - difference. + a property using a custom name. * - ``union`` - JSON object. A union is serialized identically as a ``structure`` shape, but only a single member can be set to a non-null value. diff --git a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst index 9805b1cfbe0..f268b0c25eb 100644 --- a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst @@ -282,9 +282,7 @@ JSON shape serialization - JSON object. Each member value provided for the structure is serialized as a JSON property where the property name is the same as the member name. The :ref:`jsonName-trait` can be used to serialize - a property using a custom name. A null value MAY be provided or - omitted for a :ref:`boxed ` member with no observable - difference. + a property using a custom name. * - ``union`` - JSON object. A union is serialized identically as a ``structure`` shape, but only a single member can be set to a non-null value. diff --git a/docs/source/1.0/spec/core/model.rst b/docs/source/1.0/spec/core/model.rst index 3bc51b5c898..123dd9b9b41 100644 --- a/docs/source/1.0/spec/core/model.rst +++ b/docs/source/1.0/spec/core/model.rst @@ -517,10 +517,8 @@ The following example defines a list with a string member from the .. rubric:: List member nullability Lists are considered *dense* by default, meaning they MAY NOT contain ``null`` -values. A list MAY be made *sparse* by applying the :ref:`sparse-trait`. -The :ref:`box-trait` is not used to determine if a list is dense or sparse; -a list with no ``@sparse`` trait is always considered dense. The following -example defines a sparse list: +values. A list MAY be made *sparse* by applying the :ref:`sparse-trait`. The +following example defines a sparse list: .. tabs:: @@ -675,9 +673,7 @@ across programming languages often do not allow ``null`` keys in maps. Maps values are considered *dense* by default, meaning they MAY NOT contain ``null`` values. A map MAY be made *sparse* by applying the -:ref:`sparse-trait`. The :ref:`box-trait` is not used to determine if a map -is dense or sparse; a map with no ``@sparse`` trait is always considered -dense. The following example defines a sparse map: +:ref:`sparse-trait`. The following example defines a sparse map: .. tabs:: diff --git a/docs/source/1.0/spec/core/type-refinement-traits.rst b/docs/source/1.0/spec/core/type-refinement-traits.rst index 12f96bdd02d..9202d79e410 100644 --- a/docs/source/1.0/spec/core/type-refinement-traits.rst +++ b/docs/source/1.0/spec/core/type-refinement-traits.rst @@ -11,62 +11,6 @@ the type of a shape. :backlinks: none -.. smithy-trait:: smithy.api#box -.. _box-trait: - -------------- -``box`` trait -------------- - -Summary - Indicates that a shape is boxed. When a structure :ref:`member ` is - marked with this trait or the shape targeted by a structure member is marked - with the ``box`` trait, the member may or may not contain a value, and the - member has no :ref:`default value `. - - Boolean, byte, short, integer, long, float, and double shapes are only - considered boxed if they are marked with the ``box`` trait. All other - shapes are always considered boxed. -Trait selector - .. code-block:: none - - :test(boolean, byte, short, integer, long, float, double, - member > :test(boolean, byte, short, integer, long, float, double)) - - *A boolean, byte, short, integer, long, float, double shape or a member that targets one of these shapes* -Value type - Annotation trait. - -The ``box`` trait is primarily used to influence code generation. For example, -in Java, this might mean the value provided as the member of an aggregate -shape can be set to null. In a language like Rust, this might mean the value -is wrapped in an `Option type`_. - -.. tabs:: - - .. code-tab:: smithy - - @box - integer BoxedInteger - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#BoxedInteger": { - "type": "integer", - "traits": { - "smithy.api#box": {} - } - } - } - } - -The :ref:`prelude ` contains predefined simple shapes that can be -used in all Smithy models, including boxed and unboxed shapes. - - .. smithy-trait:: smithy.api#default .. _default-trait: From 9f31a2c0a4d4764febbf3acee5fe5a8e8f75d481 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 21 Jan 2022 16:24:43 +0100 Subject: [PATCH 3/5] Move optionality section to model --- docs/source/1.0/spec/core/model.rst | 44 ++++++++++++------- .../1.0/spec/core/type-refinement-traits.rst | 26 +---------- 2 files changed, 30 insertions(+), 40 deletions(-) diff --git a/docs/source/1.0/spec/core/model.rst b/docs/source/1.0/spec/core/model.rst index 123dd9b9b41..83464ab1df7 100644 --- a/docs/source/1.0/spec/core/model.rst +++ b/docs/source/1.0/spec/core/model.rst @@ -786,22 +786,34 @@ by ``$``, followed by the member name. For example, the shape ID of the ``foo`` member in the above example is ``smithy.example#MyStructure$foo``. -.. _default-values: - -Default structure member values -------------------------------- - -The values provided for structure members are either always present and set to -a default value when necessary or *boxed*, meaning a value is optionally present -with no default value. Members are considered boxed if the member is marked with -the :ref:`box-trait` or the shape targeted by the member is marked with the box -trait. Members that target strings, timestamps, and aggregate shapes are always -considered boxed and have no default values. - -- The default value of a ``byte``, ``short``, ``integer``, ``long``, - ``float``, and ``double`` shape that is not boxed is zero. -- The default value of a ``boolean`` shape that is not boxed is ``false``. -- All other shapes are always considered boxed and have no default value. +.. optionality: + +Structure member optionality +---------------------------- + +Structure members can use the :ref:`required-trait` and :ref:`default-trait` +to influence the member's optionality, which can have an impact on the code +generated from the model. + +Code generated types for structures SHOULD use the +:ref:`default ` and :ref:`required ` traits to +provide member accessors that always return non-null values. + +- When the :ref:`default-trait` is present on a member, the corresponding + accessor SHOULD always return a non-null value by defaulting missing members + with their :ref:`zero values `. +- When the :ref:`required-trait` is present on a member, the corresponding + accessor SHOULD always return a non-null value. +- Smithy implementations in languages like TypeScript that do not provide a kind + of constructor or builder to create structures may not be able to set default + values, precluding them from being able to treat required and default + members as non-null. +- Because the :ref:`required-trait` can be backward-compatibly removed from + members of structures marked with the :ref:`input-trait` (that is, the input + of an operation), code generators MUST generate code that does not break if + the required trait is removed from these members. For example, this could + mean generating these shapes as a kind of builder pattern or using all + optional members. .. _union: diff --git a/docs/source/1.0/spec/core/type-refinement-traits.rst b/docs/source/1.0/spec/core/type-refinement-traits.rst index 9202d79e410..f8737647519 100644 --- a/docs/source/1.0/spec/core/type-refinement-traits.rst +++ b/docs/source/1.0/spec/core/type-refinement-traits.rst @@ -41,6 +41,8 @@ has a default zero value: title: String // defaults to "" } +.. _default-values: + Default zero values =================== @@ -102,30 +104,6 @@ Constraint traits are not evaluated on structure members marked with the default trait when the value of the member is the default value. -Guidance on code generation -=========================== - -Code generated types for structures SHOULD use the default and -:ref:`required ` traits to provide member accessors that always -return non-null values. - -- When the default trait is present on a member, the corresponding accessor - SHOULD always return a non-null value by defaulting missing members with - their zero values. -- When the :ref:`required-trait` is present on a member, the corresponding - accessor SHOULD always return a non-null value. -- Smithy implementations in languages like TypeScript that do not provide a kind - of constructor or builder to create structures may not be able to set default - values, precluding them from being able to treat required and default - members as non-null. -- Because the :ref:`required-trait` can be backward-compatibly removed from - members of structures marked with the :ref:`input-trait` (that is, the input - of an operation), code generators MUST generate code that does not break if - the required trait is removed from these members. For example, this could - mean generating these shapes as a kind of builder pattern or using all - optional members. - - Guidance on protocol design =========================== From 6a80baca4aa13d84e627ed3185f6d838cb4ded1d Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 21 Jan 2022 16:35:36 +0100 Subject: [PATCH 4/5] Add clientOptional docs --- docs/source/1.0/spec/aws/aws-core.rst | 45 +++++++++++++++++++ .../aws/aws-default-zero-value.rst.template | 9 ++++ .../source/1.0/spec/aws/aws-json.rst.template | 7 +++ .../aws/aws-query-serialization.rst.template | 7 +++ .../1.0/spec/aws/aws-restjson1-protocol.rst | 7 +++ .../1.0/spec/aws/aws-restxml-protocol.rst | 7 +++ docs/source/1.0/spec/core/model.rst | 2 +- 7 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 docs/source/1.0/spec/aws/aws-default-zero-value.rst.template diff --git a/docs/source/1.0/spec/aws/aws-core.rst b/docs/source/1.0/spec/aws/aws-core.rst index 955d8dffa8e..4716b52182a 100644 --- a/docs/source/1.0/spec/aws/aws-core.rst +++ b/docs/source/1.0/spec/aws/aws-core.rst @@ -1095,6 +1095,51 @@ Clients SHOULD use an LRU cache implementation with an initial cache limit of Clients SHOULD scope the cache globally or to a specific client instance. +.. smithy-trait:: aws.protocols#clientOptional + +.. _client-optional-trait: + +-------------------------------------- +``aws.protocols#clientOptional`` trait +-------------------------------------- + +Summary + Indicates that a structure member SHOULD be unconditionally generated as + optional, regardless of other traits. +Trait selector + ``structure > member`` + + A member of a structure. +Value type + Annotation trait. + +When a member is marked with this trait, it SHOULD always be generated as +optional even if the member also has the :ref:`required-trait` or +:ref:`default-trait`. This allows documentation generators to indicate that a +member is required, even if it is not reflected in the generated code. For +example: + +.. code-block:: smithy + + $version: "2.0" + namespace smithy.example + + use aws.api#clientOptional + + structure ProductData { + @clientOptional + @required + description: String + } + +When generating an AWS SDK client for this shape, the +``ProductData$description`` member SHOULD be generated as an optional member +rather than required. + +.. seealso:: + + :ref:`optionality` + .. smithy-trait:: aws.protocols#httpChecksum .. _aws.protocols#httpChecksum-trait: diff --git a/docs/source/1.0/spec/aws/aws-default-zero-value.rst.template b/docs/source/1.0/spec/aws/aws-default-zero-value.rst.template new file mode 100644 index 00000000000..8e57e6b4137 --- /dev/null +++ b/docs/source/1.0/spec/aws/aws-default-zero-value.rst.template @@ -0,0 +1,9 @@ +#. To avoid information disclosure, serializers SHOULD omit the default zero + value of structure members marked with the :ref:`default-trait`. +#. Deserializers MUST tolerate receiving the default zero value of a structure + member marked with the :ref:`default-trait`. +#. Client deserializers MUST fill in a default zero value for structure members + marked with the :ref:`required-trait` that have no serialized value, and the + targeted shape supports zero values. This prevents older clients from + failing to deserialize structures at runtime when the :ref:`required-trait` + is replaced with the :ref:`default-trait`. diff --git a/docs/source/1.0/spec/aws/aws-json.rst.template b/docs/source/1.0/spec/aws/aws-json.rst.template index 089ccf0b9cb..6c94f8d42d8 100644 --- a/docs/source/1.0/spec/aws/aws-json.rst.template +++ b/docs/source/1.0/spec/aws/aws-json.rst.template @@ -59,6 +59,13 @@ The |quoted shape name| protocol uses the following headers: service ``ns.example#MyService`` is ``MyService.MyOp``. +--------------------------- +Default value serialization +--------------------------- + +.. include:: aws-default-zero-value.rst.template + + ------------------- Shape serialization ------------------- diff --git a/docs/source/1.0/spec/aws/aws-query-serialization.rst.template b/docs/source/1.0/spec/aws/aws-query-serialization.rst.template index 18cee396aac..149939a0489 100644 --- a/docs/source/1.0/spec/aws/aws-query-serialization.rst.template +++ b/docs/source/1.0/spec/aws/aws-query-serialization.rst.template @@ -1,3 +1,10 @@ +--------------------------- +Default value serialization +--------------------------- + +.. include:: aws-default-zero-value.rst.template + + --------------------- Request serialization --------------------- diff --git a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst index f268b0c25eb..a39aee9835e 100644 --- a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst @@ -224,6 +224,13 @@ with the ``httpPayload`` trait: - ``application/json`` +--------------------------- +Default value serialization +--------------------------- + +.. include:: aws-default-zero-value.rst.template + + ------------------------ JSON shape serialization ------------------------ diff --git a/docs/source/1.0/spec/aws/aws-restxml-protocol.rst b/docs/source/1.0/spec/aws/aws-restxml-protocol.rst index 29adb77337c..65fc5ecbb60 100644 --- a/docs/source/1.0/spec/aws/aws-restxml-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-restxml-protocol.rst @@ -233,6 +233,13 @@ with the ``httpPayload`` trait: - ``application/xml`` +--------------------------- +Default value serialization +--------------------------- + +.. include:: aws-default-zero-value.rst.template + + ----------------------- XML shape serialization ----------------------- diff --git a/docs/source/1.0/spec/core/model.rst b/docs/source/1.0/spec/core/model.rst index 83464ab1df7..379159eb9ec 100644 --- a/docs/source/1.0/spec/core/model.rst +++ b/docs/source/1.0/spec/core/model.rst @@ -786,7 +786,7 @@ by ``$``, followed by the member name. For example, the shape ID of the ``foo`` member in the above example is ``smithy.example#MyStructure$foo``. -.. optionality: +.. _optionality: Structure member optionality ---------------------------- From e1d542feb143f58e6944a66378fc1466ce8234dc Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Thu, 27 Jan 2022 12:32:31 +0100 Subject: [PATCH 5/5] Tweak default zero value doc wording --- docs/source/1.0/spec/aws/aws-core.rst | 10 +++++----- docs/source/1.0/spec/core/model.rst | 6 ++---- docs/source/1.0/spec/core/type-refinement-traits.rst | 12 ++++++------ 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/source/1.0/spec/aws/aws-core.rst b/docs/source/1.0/spec/aws/aws-core.rst index 4716b52182a..8919e0f34d3 100644 --- a/docs/source/1.0/spec/aws/aws-core.rst +++ b/docs/source/1.0/spec/aws/aws-core.rst @@ -1113,11 +1113,11 @@ Trait selector Value type Annotation trait. -When a member is marked with this trait, it SHOULD always be generated as -optional even if the member also has the :ref:`required-trait` or -:ref:`default-trait`. This allows documentation generators to indicate that a -member is required, even if it is not reflected in the generated code. For -example: +When a member is marked with this trait, non-authoritative tooling like clients +SHOULD treat the member as optional even if the member also has the +:ref:`required-trait` or :ref:`default-trait`. This allows documentation +generators to indicate that a member is required, even if it is not reflected +in the generated code. For example: .. code-block:: smithy diff --git a/docs/source/1.0/spec/core/model.rst b/docs/source/1.0/spec/core/model.rst index 379159eb9ec..423f1b48fb0 100644 --- a/docs/source/1.0/spec/core/model.rst +++ b/docs/source/1.0/spec/core/model.rst @@ -804,10 +804,8 @@ provide member accessors that always return non-null values. with their :ref:`zero values `. - When the :ref:`required-trait` is present on a member, the corresponding accessor SHOULD always return a non-null value. -- Smithy implementations in languages like TypeScript that do not provide a kind - of constructor or builder to create structures may not be able to set default - values, precluding them from being able to treat required and default - members as non-null. +- An explicitly provided default zero value and a member that defaults to the + zero value are indistinguishable. - Because the :ref:`required-trait` can be backward-compatibly removed from members of structures marked with the :ref:`input-trait` (that is, the input of an operation), code generators MUST generate code that does not break if diff --git a/docs/source/1.0/spec/core/type-refinement-traits.rst b/docs/source/1.0/spec/core/type-refinement-traits.rst index f8737647519..d80890b0ab8 100644 --- a/docs/source/1.0/spec/core/type-refinement-traits.rst +++ b/docs/source/1.0/spec/core/type-refinement-traits.rst @@ -24,7 +24,8 @@ Summary Trait selector ``structure > member :not(> :test(union, structure > :test([trait|required])))`` - A member of a structure that does not target a union or structure. + A member of a structure that does not target a union or a structure with + required members. Value type Annotation trait. @@ -48,9 +49,8 @@ Default zero values The following table describes the default zero value of each kind of shape. Programming languages and code generators that cannot initialize structure -members with the following default values SHOULD continue to represent those -members as nullable as this is semantically equivalent to the default zero -value. +members with the following default values SHOULD represent those members as +nullable as this is semantically equivalent to the default zero value. .. list-table:: :header-rows: 1 @@ -67,10 +67,10 @@ value. - Numeric zero. * - string - empty string - - Strings with the enum trait also have the same default value. + - Strings with the :ref:`enum-trait` also have an empty string zero value. * - blob - empty blob - - This includes blob shapes marked with the :ref:streaming-trait`. + - This includes blob shapes marked with the :ref:`streaming-trait`. * - timestamp - Unix epoch - Zero seconds since the epoch (for example, ``0`` or