Add clientOptional docs

Author: JordonPhillips

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:
 

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`.

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
 -------------------

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
 ---------------------

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
 ------------------------

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
 -----------------------

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
 ----------------------------