Document awsQuery protocol

docs/source/1.0/guides/converting-to-openapi.rst

@@ -111,7 +111,7 @@ specification from a Smithy model using a buildscript dependency:
 
 .. code-block:: kotlin
     :caption: build.gradle.kts
-    :name: smithy-build-gradle
+    :name: openapi-smithy-build-gradle
 
     plugins {
         java
@@ -1237,7 +1237,7 @@ shows how to install ``software.amazon.smithy:smithy-openapi`` through Gradle:
 
 .. code-block:: kotlin
     :caption: build.gradle.kts
-    :name: code-build-gradle
+    :name: openapi-code-build-gradle
 
     buildscript {
         dependencies {

docs/source/1.0/guides/generating-cloudformation-resources.rst

@@ -56,7 +56,7 @@ Resource Schemas from a Smithy model :ref:`using a buildscript dependency
 
 .. code-block:: kotlin
     :caption: build.gradle.kts
-    :name: smithy-build-gradle
+    :name: cfn-smithy-build-gradle
 
     plugins {
         java
@@ -437,7 +437,7 @@ Gradle:
 
 .. code-block:: kotlin
     :caption: build.gradle.kts
-    :name: code-build-gradle
+    :name: cfn-code-build-gradle
 
     buildscript {
         dependencies {

docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst

@@ -131,4 +131,263 @@ protocol is:
     MyStruct.foo=baz
 
 
+.. _aws.protocols#ec2QueryName-query-key-naming:
+
+Query key resolution
+--------------------
+
+The key component used to serialize a member in a request in ``ec2Query`` is
+resolved using the following process:
+
+1. Use the value of the :ref:`aws.protocols#ec2QueryName-trait` applied to the
+   member, if present.
+2. Use the value of the :ref:`xmlName trait <xmlName-trait>` applied to the
+   member with the first letter capitalized, if present.
+3. Use the default value for the member:
+
+   .. list-table::
+       :header-rows: 1
+       :widths: 50 50
+
+       * - Member location
+         - Default value
+       * - ``list`` member
+         - The string literal "member"
+       * - ``set`` member
+         - The string literal "member"
+       * - ``map`` key
+         - The string literal "key"
+       * - ``map`` value
+         - The string literal "value"
+       * - ``structure`` member
+         - The :token:`member name <shape_id_member>`
+       * - ``union`` member
+         - The :token:`member name <shape_id_member>`
+
+
+----------------
+Supported traits
+----------------
+
+The ``aws.protocols#ec2Query`` 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:`ec2QueryName <xmlName-trait>`
+      - By default, the form-urlencoded key segments used in serialized
+        structures are the same as a structure member name. The ``ec2QueryName``
+        changes the key segment name to a custom value. See
+        :ref:`aws.protocols#ec2QueryName-query-key-naming` for more information.
+    * - :ref:`xmlAttrubute <xmlAttribute-trait>`
+      - Serializes an object property as an XML attribute rather than a nested
+        XML element.
+    * - :ref:`xmlFlattened <xmlFlattened-trait>`
+      - By default, entries in lists, sets, and maps have values serialized in
+        nested elements specific to their type. The ``xmlFlattened`` trait
+        unwraps these elements into the containing structure.
+    * - :ref:`xmlName <xmlName-trait>`
+      - By default, the XML element names and form-urlencoded key segments used
+        in serialized structures are the same as a structure member name. The
+        ``xmlName`` trait changes the these names to a custom value. See
+        :ref:`aws.protocols#ec2QueryName-query-key-naming` for more information.
+    * - :ref:`xmlNamespace <xmlNamespace-trait>`
+      - Adds an xmlns namespace definition URI to XML element(s) generated
+        for the targeted shape.
+    * - :ref:`timestampFormat <timestampFormat-trait>`
+      - Defines a custom timestamp serialization format.
+
+.. important::
+
+    This protocol does not support document types.
+
+
+.. |quoted shape name| replace:: ``ec2Query``
+.. |name resolution text| replace:: See :ref:`aws.protocols#ec2QueryName-query-key-naming`
+   for how to serialize a property using a custom name
+.. include:: aws-query-serialization.rst.template
+
+
+Examples
+--------
+
+.. important::
+
+    These examples are non-exhaustive. See the :ref:`ec2Query-compliance-tests`
+    for a suite of compliance tests for the ``ec2Query`` protocol.
+
+
+Structures and Unions
+=====================
+
+|query aggregate text|
+
+For example, given the following:
+
+.. code-block:: smithy
+
+    structure Ec2QueryStructuresInput {
+        foo: String,
+
+        @ec2QueryName("A")
+        HasQueryName: String,
+
+        @ec2QueryName("B")
+        @xmlName("IgnoreMe")
+        HasQueryAndXmlName: String,
+
+        @xmlName("c")
+        UsesXmlName: String,
+
+        baz: MyStructure,
+    }
+
+    structure MyStructure {
+        temp: String,
+    }
+
+The ``x-www-form-urlencoded`` serialization is:
+
+.. code-block:: text
+
+    Action=Ec2QueryStructures
+    &Version=2020-07-02
+    &foo=bar
+    &A=example0
+    &B=example1
+    &C=example2
+    &baz.temp=example3
+
+
+Collections
+===========
+
+|query collection text|
+
+For example, given the following:
+
+.. code-block:: smithy
+
+    structure Ec2QueryListsInput {
+        ListArg: StringList,
+
+        @xmlFlattened
+        ComplexListArg: GreetingList,
+
+        // Notice that the xmlName on the targeted list member is ignored.
+        ListArgWithXmlNameMember: ListWithXmlName,
+
+        @ec2QueryName("Hi")
+        @xmlName("IgnoreMe")
+        ListArgWithXmlName: ListWithXmlName,
+    }
+
+    list ListWithXmlName {
+        @xmlName("item")
+        member: String
+    }
+
+    list StringList {
+        member: String
+    }
+
+    list GreetingList {
+        member: GreetingStruct
+    }
+
+    structure GreetingStruct {
+        hi: String,
+    }
+
+The ``x-www-form-urlencoded`` serialization is:
+
+.. code-block:: text
+
+    Action=Ec2QueryLists
+    &Version=2020-07-02
+    &ListArg.member.1=foo
+    &ListArg.member.2=bar
+    &ListArg.member.3=baz
+    &ComplexListArg.1.hi=hello
+    &ComplexListArg.2.hi=hola
+    &ListArgWithXmlNameMember.1=A
+    &ListArgWithXmlNameMember.2=B
+    &Hi.1=A
+    &Hi.2=B
+
+
+----------------------
+Response serialization
+----------------------
+
+The ``ec2Query`` protocol serializes XML responses within an XML root node with
+the name of the operation's output suffixed with "Response". A nested element,
+with the name of the operation's output suffixed with "Result", contains the
+contents of the successful response.
+
+The value of the ``uri`` member of the :ref:`xmlNamespace trait <xmlNamespace-trait>`
+is serialized in an ``xmlns`` attribute on the response's XML root node. The
+following is a sample response to an operation named ``XmlTest``.
+
+.. code-block:: xml
+
+    <XmlTestResponse xmlns="https://example.com/">
+        <XmlTestResult>
+            <testValue>Hello!</testValue>
+        </XmlTestResult>
+    </XmlTestResponse>
+
+XML shape serialization
+-----------------------
+
+.. include:: aws-xml-serialization.rst.template
+
+
+.. _ec2Query-errors:
+
+-----------------------------
+Operation error serialization
+-----------------------------
+
+Error responses in the ``ec2Query`` protocol are wrapped within an XML root
+node named ``Errors``. A nested element, named ``Error``, contains the
+serialized error structure members.
+
+Serialized error shapes MUST also contain an additional child element ``Code``
+that contains only the :token:`shape name <identifier>` of the error's
+:ref:`shape-id`. This can be used to distinguish which specific error has been
+serialized in the response.
+
+.. code-block:: xml
+
+    <Errors>
+        <Error>
+            <Type>Sender</Type>
+            <Code>InvalidGreeting</Code>
+            <Message>Hi</Message>
+            <AnotherSetting>setting</AnotherSetting>
+        </Error>
+        <RequestId>foo-id</RequestId>
+    </Errors>
+
+
+.. _ec2Query-compliance-tests:
+
+-------------------------
+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/ec2Query
+
+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 specifications, protocol examples, etc.*