Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add clarifications for default and clientOptional #1920

Merged
merged 1 commit into from
Aug 14, 2023
+14 −5
Merged

Add clarifications for default and clientOptional #1920

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions docs/source-2.0/spec/type-refinement-traits.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,9 @@ value requirement of a targeted shape.
* The ``@default`` trait on root-level shapes has no impact when targeted by
any other shape than a structure member.
* The ``@default`` trait on root-level shapes cannot be set to ``null``.
* The :ref:`clientOptional-trait` applied to a member marked with the
``default`` trait causes non-authoritative generators to ignore the
``default`` trait.


Default value constraints
Expand Down Expand Up @@ -142,12 +145,18 @@ of a member because they are using different versions of the same model.
Default value serialization
---------------------------

1. All default values SHOULD be serialized. This ensures that messages are
unambiguous so that messages do not change during deserialization if the
1. Implementations that ignore ``default`` traits do not assume a default
value for a member. For example, non-authoritative implementations
will ignore the ``default`` trait when a member is marked with the
:ref:`clientOptional-trait`. These implementations would serialize any
explicitly given value, even if it happens to be the default value.
2. All effective default values SHOULD be serialized. This ensures that
messages are unambiguous and do not change during deserialization if the
default value for a member changes after the message was serialized.
2. To avoid information disclosure, implementations MAY choose to not serialize
a default values if the member is marked with the :ref:`internal-trait`.
3. A member that is both ``@default`` and ``@required`` MUST be serialized.
3. To avoid information disclosure, implementations MAY choose to not serialize
a default value if the member is marked with the :ref:`internal-trait`.
4. A member marked ``@required`` MUST be serialized, including members that
have a default.


.. smithy-trait:: smithy.api#addedDefault
Expand Down