Clarify various aspects of xmlNamespace traits

* The xmlNamespace trait can only be applied to simple types, list, map, set, structure, union, member, and service shapes. We previously allowed "*", but that includes resource and operation shapes where the trait isn't actually used. * aws.protocols#awsQuery and aws.protocols#ec2Query protocol traits both now require that an xmlNamespace is set on the top-level service shape they are applied to so that the namespace is guaranteed to be known. * Added various examples for how the xmlNamespace trait interacts with flattened lists and maps. * Add a protocol test suite named "restXmlWithNamespace" to test that implementations add an xmlns to restXml services when necessary, closing #616
smithy-lang · Nov 28, 2020 · 930ac23 · 930ac23
1 parent 705efff
commit 930ac23
Show file tree

Hide file tree

Showing 14 changed files with 342 additions and 8 deletions.
diff --git a/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst b/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst
@@ -23,7 +23,9 @@ Summary
     OR in a ``x-form-url-encoded`` body and responses in XML documents. This
     protocol is an Amazon EC2-specific extension of the ``awsQuery`` protocol.
 Trait selector
-    ``service``
+    ``service [trait|xmlNamespace]``
+
+    *Service shapes with the xmlNamespace trait*
 Value type
     Annotation trait.
 

diff --git a/docs/source/1.0/spec/aws/aws-query-protocol.rst b/docs/source/1.0/spec/aws/aws-query-protocol.rst
@@ -22,7 +22,9 @@ Summary
     Adds support for an HTTP protocol that sends requests in the query
     string and responses in XML documents.
 Trait selector
-    ``service``
+    ``service [trait|xmlNamespace]``
+
+    *Service shapes with the xmlNamespace trait*
 Value type
     Annotation trait.
 See

diff --git a/docs/source/1.0/spec/core/xml-traits.rst b/docs/source/1.0/spec/core/xml-traits.rst
@@ -937,7 +937,9 @@ The XML serialization is:
 Summary
     Adds an `XML namespace`_ to an XML element.
 Trait selector
-    ``*``
+    ``:is(service, member, simpleType, collection, map, structure, union)``
+
+    *Service, simple types, list, map, set, structure, or union*
 Value type
     ``structure``
 Conflicts with

diff --git a/smithy-aws-protocol-tests/model/awsQuery/main.smithy b/smithy-aws-protocol-tests/model/awsQuery/main.smithy
@@ -35,6 +35,7 @@ service AwsQuery {
         XmlMapsXmlName,
         FlattenedXmlMap,
         FlattenedXmlMapWithXmlName,
+        FlattenedXmlMapWithXmlNamespace,
         XmlEmptyMaps,
 
         // Output XML list tests

diff --git a/smithy-aws-protocol-tests/model/awsQuery/xml-lists.smithy b/smithy-aws-protocol-tests/model/awsQuery/xml-lists.smithy
@@ -79,6 +79,10 @@ apply XmlLists @httpResponseTests([
                       <flattenedList>bye</flattenedList>
                       <customName>yep</customName>
                       <customName>nope</customName>
+                      <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">a</flattenedListWithMemberNamespace>
+                      <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">b</flattenedListWithMemberNamespace>
+                      <flattenedListWithNamespace>a</flattenedListWithNamespace>
+                      <flattenedListWithNamespace>b</flattenedListWithNamespace>
                       <myStructureList>
                           <item>
                               <value>1</value>
@@ -107,6 +111,8 @@ apply XmlLists @httpResponseTests([
             renamedListMembers: ["foo", "bar"],
             flattenedList: ["hi", "bye"],
             flattenedList2: ["yep", "nope"],
+            flattenedListWithMemberNamespace: ["a", "b"],
+            flattenedListWithNamespace: ["a", "b"],
             structureList: [
                 {
                     a: "1",
@@ -180,6 +186,17 @@ structure XmlListsOutput {
     // serializing flattened lists in structures.
     flattenedList2: RenamedListMembers,
 
+    // The XML namespace of the flattened list's member is used, and
+    // list's XML namespace is disregarded.
+    @xmlFlattened
+    flattenedListWithMemberNamespace: ListWithMemberNamespace,
+
+    // Again, the XML namespace of the flattened list is ignored.
+    // The namespace of the member is used, which is empty, so
+    // no xmlns attribute appears on the serialized XML.
+    @xmlFlattened
+    flattenedListWithNamespace: ListWithNamespace,
+
     @xmlName("myStructureList")
     structureList: StructureList
 }
@@ -201,3 +218,14 @@ structure StructureListMember {
     @xmlName("other")
     b: String,
 }
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithMemberNamespace {
+    @xmlNamespace(uri: "https://xml-member.example.com")
+    member: String,
+}
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithNamespace {
+    member: String,
+}
diff --git a/smithy-aws-protocol-tests/model/awsQuery/xml-maps.smithy b/smithy-aws-protocol-tests/model/awsQuery/xml-maps.smithy
@@ -269,3 +269,57 @@ map FlattenedXmlMapWithXmlNameOutputMap {
     @xmlName("V")
     value: String,
 }
+
+/// Flattened maps with @xmlNamespace and @xmlName
+operation FlattenedXmlMapWithXmlNamespace {
+    output: FlattenedXmlMapWithXmlNamespaceOutput
+}
+
+apply FlattenedXmlMapWithXmlNamespace @httpResponseTests([
+    {
+        id: "QueryQueryFlattenedXmlMapWithXmlNamespace",
+        documentation: "Serializes flattened XML maps in responses that have xmlNamespace and xmlName on members",
+        protocol: awsQuery,
+        code: 200,
+        body: """
+              <FlattenedXmlMapWithXmlNamespaceResponse xmlns="https://example.com/">
+                  <FlattenedXmlMapWithXmlNamespaceResult>
+                      <KVP xmlns="https://the-member.example.com">
+                          <K xmlns="https://the-key.example.com">a</K>
+                          <V xmlns="https://the-value.example.com">A</V>
+                      </KVP>
+                      <KVP xmlns="https://the-member.example.com">
+                          <K xmlns="https://the-key.example.com">b</K>
+                          <V xmlns="https://the-value.example.com">B</V>
+                      </KVP>
+                  </FlattenedXmlMapWithXmlNamespaceResult>
+              </FlattenedXmlMapWithXmlNamespaceResponse>""",
+        bodyMediaType: "application/xml",
+        headers: {
+            "Content-Type": "text/xml"
+        },
+        params: {
+            myMap: {
+                a: "A",
+                b: "B",
+            }
+        }
+    }
+])
+
+structure FlattenedXmlMapWithXmlNamespaceOutput {
+    @xmlFlattened
+    @xmlName("KVP")
+    @xmlNamespace(uri: "https://the-member.example.com")
+    myMap: FlattenedXmlMapWithXmlNamespaceOutputMap,
+}
+
+map FlattenedXmlMapWithXmlNamespaceOutputMap {
+    @xmlName("K")
+    @xmlNamespace(uri: "https://the-key.example.com")
+    key: String,
+
+    @xmlName("V")
+    @xmlNamespace(uri: "https://the-value.example.com")
+    value: String,
+}
diff --git a/smithy-aws-protocol-tests/model/ec2Query/xml-lists.smithy b/smithy-aws-protocol-tests/model/ec2Query/xml-lists.smithy
@@ -23,7 +23,8 @@ use smithy.test#httpResponseTests
 /// 4. XML lists with @xmlName on its members
 /// 5. Flattened XML lists.
 /// 6. Flattened XML lists with @xmlName.
-/// 7. Lists of structures.
+/// 7. Flattened XML lists with @xmlNamespace.
+/// 8. Lists of structures.
 operation XmlLists {
     output: XmlListsOutput
 }
@@ -78,6 +79,10 @@ apply XmlLists @httpResponseTests([
                   <flattenedList>bye</flattenedList>
                   <customName>yep</customName>
                   <customName>nope</customName>
+                  <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">a</flattenedListWithMemberNamespace>
+                  <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">b</flattenedListWithMemberNamespace>
+                  <flattenedListWithNamespace>a</flattenedListWithNamespace>
+                  <flattenedListWithNamespace>b</flattenedListWithNamespace>
                   <myStructureList>
                       <item>
                           <value>1</value>
@@ -106,6 +111,8 @@ apply XmlLists @httpResponseTests([
             renamedListMembers: ["foo", "bar"],
             flattenedList: ["hi", "bye"],
             flattenedList2: ["yep", "nope"],
+            flattenedListWithMemberNamespace: ["a", "b"],
+            flattenedListWithNamespace: ["a", "b"],
             structureList: [
                 {
                     a: "1",
@@ -177,6 +184,17 @@ structure XmlListsOutput {
     // serializing flattened lists in structures.
     flattenedList2: RenamedListMembers,
 
+    // The XML namespace of the flattened list's member is used, and
+    // list's XML namespace is disregarded.
+    @xmlFlattened
+    flattenedListWithMemberNamespace: ListWithMemberNamespace,
+
+    // Again, the XML namespace of the flattened list is ignored.
+    // The namespace of the member is used, which is empty, so
+    // no xmlns attribute appears on the serialized XML.
+    @xmlFlattened
+    flattenedListWithNamespace: ListWithNamespace,
+
     @xmlName("myStructureList")
     structureList: StructureList
 }
@@ -198,3 +216,14 @@ structure StructureListMember {
     @xmlName("other")
     b: String,
 }
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithMemberNamespace {
+    @xmlNamespace(uri: "https://xml-member.example.com")
+    member: String,
+}
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithNamespace {
+    member: String,
+}
diff --git a/smithy-aws-protocol-tests/model/restXml/document-lists.smithy b/smithy-aws-protocol-tests/model/restXml/document-lists.smithy
@@ -26,7 +26,8 @@ use smithy.test#httpResponseTests
 /// 4. XML lists with @xmlName on its members
 /// 5. Flattened XML lists.
 /// 6. Flattened XML lists with @xmlName.
-/// 7. Lists of structures.
+/// 7. Flattened XML lists with @xmlNamespace.
+/// 8. Lists of structures.
 @idempotent
 @http(uri: "/XmlLists", method: "PUT")
 operation XmlLists {
@@ -176,6 +177,10 @@ apply XmlLists @httpResponseTests([
                   <flattenedList>bye</flattenedList>
                   <customName>yep</customName>
                   <customName>nope</customName>
+                  <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">a</flattenedListWithMemberNamespace>
+                  <flattenedListWithMemberNamespace xmlns="https://xml-member.example.com">b</flattenedListWithMemberNamespace>
+                  <flattenedListWithNamespace>a</flattenedListWithNamespace>
+                  <flattenedListWithNamespace>b</flattenedListWithNamespace>
                   <myStructureList>
                       <item>
                           <value>1</value>
@@ -203,6 +208,8 @@ apply XmlLists @httpResponseTests([
             renamedListMembers: ["foo", "bar"],
             flattenedList: ["hi", "bye"],
             flattenedList2: ["yep", "nope"],
+            flattenedListWithMemberNamespace: ["a", "b"],
+            flattenedListWithNamespace: ["a", "b"],
             structureList: [
                 {
                     a: "1",
@@ -300,6 +307,17 @@ structure XmlListsInputOutput {
     // serializing flattened lists in structures.
     flattenedList2: RenamedListMembers,
 
+    // The XML namespace of the flattened list's member is used, and
+    // list's XML namespace is disregarded.
+    @xmlFlattened
+    flattenedListWithMemberNamespace: ListWithMemberNamespace,
+
+    // Again, the XML namespace of the flattened list is ignored.
+    // The namespace of the member is used, which is empty, so
+    // no xmlns attribute appears on the serialized XML.
+    @xmlFlattened
+    flattenedListWithNamespace: ListWithNamespace,
+
     @xmlName("myStructureList")
     structureList: StructureList
 }
@@ -321,3 +339,14 @@ structure StructureListMember {
     @xmlName("other")
     b: String,
 }
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithMemberNamespace {
+    @xmlNamespace(uri: "https://xml-member.example.com")
+    member: String,
+}
+
+@xmlNamespace(uri: "https://xml-list.example.com")
+list ListWithNamespace {
+    member: String,
+}
diff --git a/smithy-aws-protocol-tests/model/restXml/document-maps.smithy b/smithy-aws-protocol-tests/model/restXml/document-maps.smithy
@@ -433,3 +433,56 @@ map FlattenedXmlMapWithXmlNameInputOutputMap {
     @xmlName("V")
     value: String,
 }
+
+/// Flattened maps with @xmlNamespace and @xmlName
+@http(uri: "/FlattenedXmlMapWithXmlNamespace", method: "POST")
+operation FlattenedXmlMapWithXmlNamespace {
+    output: FlattenedXmlMapWithXmlNamespaceOutput
+}
+
+apply FlattenedXmlMapWithXmlNamespace @httpResponseTests([
+    {
+        id: "RestXmlFlattenedXmlMapWithXmlNamespace",
+        documentation: "Serializes flattened XML maps in responses that have xmlNamespace and xmlName on members",
+        protocol: restXml,
+        code: 200,
+        body: """
+              <FlattenedXmlMapWithXmlNamespaceOutput>
+                  <KVP xmlns="https://the-member.example.com">
+                      <K xmlns="https://the-key.example.com">a</K>
+                      <V xmlns="https://the-value.example.com">A</V>
+                  </KVP>
+                  <KVP xmlns="https://the-member.example.com">
+                      <K xmlns="https://the-key.example.com">b</K>
+                      <V xmlns="https://the-value.example.com">B</V>
+                  </KVP>
+              </FlattenedXmlMapWithXmlNamespaceOutput>""",
+        bodyMediaType: "application/xml",
+        headers: {
+            "Content-Type": "application/xml"
+        },
+        params: {
+            myMap: {
+                a: "A",
+                b: "B",
+            }
+        }
+    }
+])
+
+structure FlattenedXmlMapWithXmlNamespaceOutput {
+    @xmlFlattened
+    @xmlName("KVP")
+    @xmlNamespace(uri: "https://the-member.example.com")
+    myMap: FlattenedXmlMapWithXmlNamespaceOutputMap,
+}
+
+map FlattenedXmlMapWithXmlNamespaceOutputMap {
+    @xmlName("K")
+    @xmlNamespace(uri: "https://the-key.example.com")
+    key: String,
+
+    @xmlName("V")
+    @xmlNamespace(uri: "https://the-value.example.com")
+    value: String,
+}
diff --git a/smithy-aws-protocol-tests/model/restXml/main.smithy b/smithy-aws-protocol-tests/model/restXml/main.smithy
@@ -71,6 +71,7 @@ service RestXml {
         XmlMapsXmlName,
         FlattenedXmlMap,
         FlattenedXmlMapWithXmlName,
+        FlattenedXmlMapWithXmlNamespace,
 
         // @xmlAttribute tests
         XmlAttributes,