Document awsJson1_0 protocol

docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst

@@ -19,7 +19,7 @@ This specification defines the ``aws.protocols#awsJson1_0`` protocol.
 ----------------------------------
 
 Summary
-    Adds support for an HTTP protocol that sends POST requests and
+    Adds support for an HTTP protocol that sends "POST" requests and
     responses with JSON documents.
 Trait selector
     ``service``
@@ -56,9 +56,209 @@ See
             }
         }
 
-.. important::
 
-    This protocol only permits the :ref:`httpPayload-trait` to be applied to
-    members that target structures, documents, strings, blobs, or unions.
+----------------
+Supported traits
+----------------
 
-*TODO: Add specifications, protocol examples, etc.*
+The ``awsJson1_0`` protocol supports the following traits
+that affect serialization:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 80
+
+    * - Trait
+      - Description
+    * - :ref:`cors <cors-trait>`
+      - Indicates that the service supports CORS.
+    * - :ref:`jsonName <jsonName-trait>`
+          - By default, the JSON property names used in serialized structures are
+            the same as a structure member name. The ``jsonName`` trait changes
+            the JSON property name to a custom value.
+    * - :ref:`timestampFormat <timestampFormat-trait>`
+      - Defines a custom timestamp serialization format.
+
+
+------------------
+Protocol Behaviors
+------------------
+
+Every request for the ``awsJson1_0`` protocol MUST be sent to the
+root URL (``/``) using the HTTP "POST" method.
+
+The ``awsJson1_0`` protocol does not support custom HTTP bindings.
+:ref:`HTTP binding traits <http-traits>` MUST be ignored if they are present.
+
+The ``awsJson1_0`` protocol uses the following headers:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 20 80
+
+    * - Header
+      - Required
+      - Description
+    * - ``Content-Type``
+      - true
+      - This header has a static value of ``application/x-amz-json-1.0``.
+    * - ``Content-Length``
+      - true
+      - The standard ``Content-Length`` header defined by
+        `RFC 7230 Section 3.3.2`_.
+    * - ``X-Amz-Target``
+      - true for requests
+      - The value of this header is the :token:`shape name <identifier>` of the
+        service's :ref:`shape-id` joined to the
+        :token:`shape name <identifier>` of the operation's :ref:`shape-id`,
+        separated by a single period (``.``) character.
+
+        For example, the value for the operation ``ns.example#MyOp`` of the
+        service ``ns.example#MyService`` is ``MyService.MyOp``.
+
+
+-------------------
+Shape serialization
+-------------------
+
+The ``awsJson1_0`` protocol serializes all shapes into a JSON
+document body with no HTTP bindings supported. The following table shows how
+to convert each shape type:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 75
+
+    * - Smithy type
+      - JSON type
+    * - ``blob``
+      - JSON ``string`` value that is base64 encoded.
+    * - ``boolean``
+      - JSON boolean
+    * - ``byte``
+      - JSON number
+    * - ``short``
+      - JSON number
+    * - ``integer``
+      - JSON number
+    * - ``long``
+      - JSON number
+    * - ``float``
+      - JSON number
+    * - ``double``
+      - JSON number
+    * - ``bigDecimal``
+      - JSON number. Unfortunately, this protocol serializes bigDecimal
+        shapes as a normal JSON number. Many JSON parsers will either
+        truncate the value or be unable to parse numbers that exceed the
+        size of a double.
+    * - ``bigInteger``
+      - JSON number. Unfortunately, this protocol serializes bigInteger
+        shapes as a normal JSON number. Many JSON parsers will either
+        truncate the value or be unable to parse numbers that exceed the
+        size of a double.
+    * - ``string``
+      - JSON string
+    * - ``timestamp``
+      - JSON number (default). This protocol uses ``epoch-seconds``, also
+        known as Unix timestamps, in JSON payloads represented as a double.
+        However, the :ref:`timestampFormat <timestampFormat-trait>` MAY be
+        used to customize timestamp serialization.
+    * - ``document``
+      - Any JSON value
+    * - ``list``
+      - JSON array
+    * - ``set``
+      - JSON array. A set is serialized identically as a ``list`` shape,
+        but only contains unique values.
+    * - ``map``
+      - JSON object
+    * - ``structure``
+      - 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 <box-trait>` member with no observable
+        difference.
+    * - ``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.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~
+Empty body serialization
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When an operation has no modeled input or if no input parameters are provided,
+a client MUST send an empty JSON object (``{}``) as the request body. Server
+implementations MUST also accept empty request bodies.
+
+When an operation has no modeled output or no output parameters are provided,
+server implementations SHOULD send an empty response body. The server MUST
+still send the protocol's ``Content-Type`` header in this case. Clients MUST
+also accept an empty JSON object as the response body.
+
+
+.. awsJson1_0-errors:
+
+-----------------------------
+Operation error serialization
+-----------------------------
+
+Error responses in the ``awsJson1_0`` protocol are serialized identically to
+standard responses with one additional component to distinguish which error
+is contained. New server-side protocol implementations SHOULD use a body field
+named ``__type``. The component MUST be one of the following: an additional
+header with the name ``X-Amzn-Errortype``, a body field with the name ``code``,
+or a body field named ``__type``.  The value of this component SHOULD contain
+the error's :ref:`shape-id`.
+
+Legacy server-side protocol implementations sometimes include different
+information in this value. All client-side implementations SHOULD support
+sanitizing the value to retrieve the disambiguated error type using the
+following steps:
+
+1. If a ``:`` character is present, then take only the contents **before** the
+   first ``:`` character in the value.
+2. If a ``#`` character is present, then take only the contents **after** the
+   first ``#`` character in the value.
+
+All of the following error values resolve to ``FooError``:
+
+* ``FooError``
+* ``FooError:http://internal.amazon.com/coral/com.amazon.coral.validate/``
+* ``aws.protocoltests.restjson#FooError``
+* ``aws.protocoltests.restjson#FooError:http://internal.amazon.com/coral/com.amazon.coral.validate/``
+
+
+-----------------------------------------------------
+Differences between ``awsJson1_0`` and ``awsJson1_1``
+-----------------------------------------------------
+
+There are two difference between ``awsJson1_0`` and
+:ref:`aws.protocols#awsJson1_1-trait`. First, the static value of the
+``Content-Type`` header is different. In ``awsJson1_0`` it MUST be
+``application/x-amz-json-1.0`` and in ``awsJson1_1`` it MUST be
+``application/x-amz-json-1.1``.
+
+Second, error type serialization is different. In ``awsJson1_0``, servers SHOULD
+send the error shape's full :ref:`shape-id` in the ``__type`` field of the body.
+In ``awsJson1_1``, servers SHOULD only send the error's
+:token:`shape name <identifier>`. However, clients MUST accept either behavior
+for both protocols. See :ref:`awsJson1_0-errors` for full details on how to
+deserialize errors for ``awsJson1_0``.
+
+
+-------------------------
+Protocol compliance tests
+-------------------------
+
+A full compliance test suite is provided and SHALL be considered a normative
+reference: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_0
+
+These compliance tests define a model that is used to define test cases and
+the expected serialized HTTP requests and responses for each case.
+
+*TODO: Add event stream handling specifications.*
+
+.. _`RFC 7230 Section 3.3.2`: https://tools.ietf.org/html/rfc7230#section-3.3.2

docs/source/1.0/spec/aws/aws-restjson1-protocol.rst

@@ -332,7 +332,7 @@ Protocol compliance tests
 -------------------------
 
 A full compliance test suite is provided and SHALL be considered a normative
-reference: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_1
+reference: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/restJson1
 
 These compliance tests define a model that is used to define test cases and
 the expected serialized HTTP requests and responses for each case.

smithy-aws-traits/src/main/resources/META-INF/smithy/aws.protocols.json

@@ -92,7 +92,9 @@
                 },
                 "smithy.api#protocolDefinition": {
                     "traits": [
-                        "smithy.api#jsonName"
+                        "smithy.api#jsonName",
+                        "smithy.api#timestampFormat",
+                        "smithy.api#cors"
                     ]
                 },
                 "smithy.api#documentation": "An RPC-based protocol that sends JSON payloads. This protocol does not use HTTP binding traits."
@@ -114,7 +116,9 @@
                 },
                 "smithy.api#protocolDefinition": {
                     "traits": [
-                        "smithy.api#jsonName"
+                        "smithy.api#jsonName",
+                        "smithy.api#timestampFormat",
+                        "smithy.api#cors"
                     ]
                 },
                 "smithy.api#documentation": "An RPC-based protocol that sends JSON payloads. This protocol does not use HTTP binding traits."