Add mixin documentation

smithy-lang · JordonPhillips · Jan 20, 2022 · Jan 13, 2022 · Jan 13, 2022 · Jan 14, 2022
commit 9da850dc119ef81fb16d45ed402845f3a34eeb60
diff --git a/designs/mixins.md b/designs/mixins.md
@@ -348,7 +348,7 @@ The members and traits applied to members of a mixin are copied onto the target
 shape. It is sometimes necessary to provide a more specific trait value for a
 copied member or to add traits only to a specific copy of a member. Traits can
 be added on to these members like any other member. Additionally, Traits can be
-applied to  these members in the JSON AST using the `apply` type and in the
+applied to these members in the JSON AST using the `apply` type and in the
 Smithy IDL using `apply` statements.
 
 > Note: Traits applied to shapes supersede any traits inherited from mixins.

diff --git a/docs/source/1.0/spec/core/idl.rst b/docs/source/1.0/spec/core/idl.rst
@@ -180,7 +180,8 @@ The Smithy IDL is defined by the following ABNF:
                                  :/ `service_statement`
                                  :/ `operation_statement`
                                  :/ `resource_statement`
-    simple_shape_statement :`simple_type_name` `ws` `identifier`
+    mixins                 :`sp` "with" `ws` "[" 1*(`ws` `shape_id`) `ws` "]"
+    simple_shape_statement :`simple_type_name` `ws` `identifier` [`mixins`]
     simple_type_name       :"blob" / "boolean" / "document" / "string"
                            :/ "byte" / "short" / "integer" / "long"
                            :/ "float" / "double" / "bigInteger"
@@ -191,14 +192,14 @@ The Smithy IDL is defined by the following ABNF:
     inlineable_property    :`node_object_kvp` / `inline_structure`
     inline_structure       :`node_object_key` `ws` ":=" `ws` `inline_structure_value`
     inline_structure_value :`trait_statements` [`mixins` ws] shape_members
-    list_statement :"list" `ws` `identifier` `ws` `shape_members`
-    set_statement :"set" `ws` `identifier` `ws` `shape_members`
-    map_statement :"map" `ws` `identifier` `ws` `shape_members`
-    structure_statement     :"structure" `ws` `identifier` `ws` `shape_members`
-    union_statement :"union" `ws` `identifier` `ws` `shape_members`
-    service_statement :"service" `ws` `identifier` `ws` `node_object`
-    operation_statement :"operation" `ws` `identifier` `ws` `inlineable_properties`
-    resource_statement :"resource" `ws` `identifier` `ws` `node_object`
+    list_statement :"list" `ws` `identifier` [`mixins`] `ws` `shape_members`
+    set_statement :"set" `ws` `identifier` [`mixins`] `ws` `shape_members`
+    map_statement :"map" `ws` `identifier` [`mixins`] `ws` `shape_members`
+    structure_statement     :"structure" `ws` `identifier` [`mixins`] `ws` `shape_members`
+    union_statement :"union" `ws` `identifier` [`mixins`] `ws` `shape_members`
+    service_statement :"service" `ws` `identifier` [`mixins`] `ws` `node_object`
+    operation_statement :"operation" `ws` `identifier` [`mixins`] `ws` `inlineable_properties`
+    resource_statement :"resource" `ws` `identifier` [`mixins`] `ws` `node_object`
 
 .. rubric:: Traits
 
@@ -1298,6 +1299,34 @@ and defines a :ref:`read <read-lifecycle>` operation:
         }
 
 
+.. _idl-mixins:
+
+Mixins
+------
+
+:ref:`Mixins <mixins>` can be added to a shape using the optional
+:token:`smithy:mixins` statement as part of the shape type's statement.
+For example:
+
+.. code-block:: smithy
+
+    @mixin
+    structure BaseUser {
+        userId: String
+    }
+
+    structure UserDetails with [BaseUser] {
+        username: String
+    }
+
+    @mixin
+    @sensitive
+    string SensitiveString
+
+    @pattern("[a-zA-Z\.]*")
+    string SensitiveText with SensitiveString
+
+
 .. _documentation-comment:
 
 Documentation comment

diff --git a/docs/source/1.0/spec/core/json-ast.rst b/docs/source/1.0/spec/core/json-ast.rst
@@ -638,6 +638,50 @@ The following example defines an operation, its input, output, and errors:
     }
 
 
+.. ast-mixins:
+
+------
+Mixins
+------
+
+All shapes in the ``shapes`` map can contain a ``mixins`` property that
+defines the :ref:`mixins` that are added to the shape. ``mixins`` is an
+array of :ref:`shape references <ast-shape-reference>` that target shapes
+with the :ref:`mixin trait <mixin-trait>`.
+
+.. code-block:: json
+
+    {
+        "smithy": "2.0",
+        "shapes": {
+            "smithy.example#BaseUser": {
+                "type": "structure",
+                "members": {
+                    "userId": {
+                        "target": "smithy.api#String"
+                    }
+                },
+                "traits": {
+                    "smithy.api#mixin": {}
+                }
+            },
+            "smithy.example#UserDetails": {
+                "type": "structure",
+                "members": {
+                    "username": {
+                        "target": "smithy.api#String"
+                    }
+                },
+                "mixins": [
+                    {
+                        "target": "smithy.example#BaseUser"
+                    }
+                ]
+            }
+        }
+    }
+
+
 .. _ast-apply:
 
 --------------