Add clarifications for default and clientOptional

docs/source-2.0/spec/type-refinement-traits.rst

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