Clarify streaming trait values and semantics

docs/source-1.0/spec/core/stream-traits.rst

@@ -36,12 +36,12 @@ Validation
     * The ``streaming`` trait is *structurally exclusive by target*, meaning
       only a single member of a structure can target a shape marked as
       ``streaming``.
-    * If a service supports a protocol that supports the :ref:`httpPayload-trait`,
-      any member that targets a ``streaming`` ``blob`` must also be marked as
-      ``@httpPayload``.
+    * If a service supports the :ref:`httpPayload-trait`, any member that
+      targets a ``streaming`` shape must also be marked as ``@httpPayload``.
 
 .. code-block:: smithy
 
+    @http(method: "GET", uri: "/streaming-operation")
     operation StreamingOperation {
         input: StreamingOperationInput,
         output: StreamingOperationOutput,
@@ -60,6 +60,20 @@ Validation
     blob StreamingBlob
 
 
+Deserializing streaming blobs
+=============================
+
+It is often impossible for a server to know if a zero-length payload was sent
+by a client, or if no payload was explicitly sent by a client. As a result,
+required streaming members SHOULD be interpreted by deserializers as if they
+have a default zero-length value when not present.
+
+.. note::
+    In Smithy IDL version 2, members that target a streaming blob MUST be
+    marked as ``required`` or be given an explicit default value of
+    zero bytes.
+
+
 .. smithy-trait:: smithy.api#requiresLength
 .. _requiresLength-trait:
 
@@ -376,7 +390,7 @@ traits can be used to influence the serialization of an event stream event.
 Structure members that are sent as part of an event stream are serialized
 in either a header or the payload of an event.
 
-The :ref:`eventHeader-trait` is used to serialize a structure member as an
+The :ref:`eventheader-trait` is used to serialize a structure member as an
 event header. The payload of an event is defined by either marking a single
 member with the :ref:`eventpayload-trait`, or by combining all members that
 are not marked with the ``eventHeader`` or ``eventPayload`` trait into a

docs/source-2.0/spec/streaming.rst

@@ -20,19 +20,16 @@ by a single top-level operation input or output structure member. For example:
 
 .. code-block:: smithy
 
+    @http(method: "GET", uri: "/streaming-operation")
     operation StreamingOperation {
-        input: StreamingOperationInput
-        output: StreamingOperationOutput
-    }
-
-    @input
-    structure StreamingOperationInput {}
-
-    @output
-    structure StreamingOperationOutput {
-        @required
-        streamId: String
-        output: StreamingBlob
+        input := {}
+        output := {
+            @required
+            streamId: String
+
+            @httpPayload
+            output: StreamingBlob = ""
+        }
     }
 
     @streaming
@@ -483,24 +480,33 @@ Summary
     large and thus should not be stored in memory or that the size is unknown
     at the start of the request.
 
-    .. warning::
-        Members targeting streaming blobs MUST be marked with the
-        :ref:`required-trait` or :ref:`default-trait`.
-
     When applied to a union, it indicates that shape represents an
     :ref:`event stream <event-streams>`.
 Trait selector::
     ``:is(blob, union)``
 Value type
     Annotation trait
 Validation
+    * Members that target a streaming blob MUST be marked with the
+      :ref:`required-trait` or :ref:`default-trait`.
     * ``streaming`` shapes can only be referenced from top-level members
       of operation input or output structures.
     * Structures that contain a member that targets a ``streaming`` shape
       MUST NOT be targeted by other members.
     * The ``streaming`` trait is *structurally exclusive by target*, meaning
       only a single member of a structure can target a shape marked as
       ``streaming``.
+    * If a service supports the :ref:`httpPayload-trait`, any member that
+      targets a ``streaming`` shape must also be marked as ``@httpPayload``.
+
+
+Deserializing streaming blobs
+-----------------------------
+
+It is often impossible for a server to know if a zero-length payload was sent
+by a client, or if no payload was explicitly sent by a client. As a result,
+required streaming members SHOULD be interpreted by deserializers as if they
+have a default zero-length value when not present.
 
 
 .. smithy-trait:: smithy.api#requiresLength