Update documentation

smithy-lang · Dec 7, 2023 · b6f9796 · b6f9796
1 parent e841d48
commit b6f9796
Show file tree

Hide file tree

Showing 1,577 changed files with 395,600 additions and 28,021 deletions.
diff --git a/1.0/guides/building-models/build-config.html b/1.0/guides/building-models/build-config.html
diff --git a/1.0/guides/building-models/gradle-plugin.html b/1.0/guides/building-models/gradle-plugin.html
diff --git a/1.0/guides/building-models/index.html b/1.0/guides/building-models/index.html
diff --git a/1.0/guides/converting-to-openapi.html b/1.0/guides/converting-to-openapi.html
diff --git a/1.0/guides/evolving-models.html b/1.0/guides/evolving-models.html
diff --git a/1.0/guides/generating-cloudformation-resources.html b/1.0/guides/generating-cloudformation-resources.html
diff --git a/1.0/guides/index.html b/1.0/guides/index.html
diff --git a/1.0/guides/model-linters.html b/1.0/guides/model-linters.html
diff --git a/1.0/guides/style-guide.html b/1.0/guides/style-guide.html
diff --git a/1.0/spec/aws/amazon-apigateway.html b/1.0/spec/aws/amazon-apigateway.html
diff --git a/1.0/spec/aws/aws-auth.html b/1.0/spec/aws/aws-auth.html
diff --git a/1.0/spec/aws/aws-cloudformation.html b/1.0/spec/aws/aws-cloudformation.html
diff --git a/1.0/spec/aws/aws-core.html b/1.0/spec/aws/aws-core.html
diff --git a/1.0/spec/aws/aws-ec2-query-protocol.html b/1.0/spec/aws/aws-ec2-query-protocol.html
diff --git a/1.0/spec/aws/aws-iam.html b/1.0/spec/aws/aws-iam.html
diff --git a/1.0/spec/aws/aws-json-1_0-protocol.html b/1.0/spec/aws/aws-json-1_0-protocol.html
diff --git a/1.0/spec/aws/aws-json-1_1-protocol.html b/1.0/spec/aws/aws-json-1_1-protocol.html
diff --git a/1.0/spec/aws/aws-query-protocol.html b/1.0/spec/aws/aws-query-protocol.html
diff --git a/1.0/spec/aws/aws-restjson1-protocol.html b/1.0/spec/aws/aws-restjson1-protocol.html
diff --git a/1.0/spec/aws/aws-restxml-protocol.html b/1.0/spec/aws/aws-restxml-protocol.html
diff --git a/1.0/spec/aws/customizations/apigateway-customizations.html b/1.0/spec/aws/customizations/apigateway-customizations.html
diff --git a/1.0/spec/aws/customizations/glacier-customizations.html b/1.0/spec/aws/customizations/glacier-customizations.html
diff --git a/1.0/spec/aws/customizations/index.html b/1.0/spec/aws/customizations/index.html
diff --git a/1.0/spec/aws/customizations/machinelearning-customizations.html b/1.0/spec/aws/customizations/machinelearning-customizations.html
diff --git a/1.0/spec/aws/customizations/s3-customizations.html b/1.0/spec/aws/customizations/s3-customizations.html
diff --git a/1.0/spec/aws/index.html b/1.0/spec/aws/index.html
diff --git a/1.0/spec/core/auth-traits.html b/1.0/spec/core/auth-traits.html
diff --git a/1.0/spec/core/behavior-traits.html b/1.0/spec/core/behavior-traits.html
diff --git a/1.0/spec/core/constraint-traits.html b/1.0/spec/core/constraint-traits.html
diff --git a/1.0/spec/core/documentation-traits.html b/1.0/spec/core/documentation-traits.html
diff --git a/1.0/spec/core/endpoint-traits.html b/1.0/spec/core/endpoint-traits.html
diff --git a/1.0/spec/core/http-traits.html b/1.0/spec/core/http-traits.html
diff --git a/1.0/spec/core/idl.html b/1.0/spec/core/idl.html
diff --git a/1.0/spec/core/index.html b/1.0/spec/core/index.html
diff --git a/1.0/spec/core/json-ast.html b/1.0/spec/core/json-ast.html
diff --git a/1.0/spec/core/model-validation.html b/1.0/spec/core/model-validation.html
diff --git a/1.0/spec/core/model.html b/1.0/spec/core/model.html
diff --git a/1.0/spec/core/prelude-model.html b/1.0/spec/core/prelude-model.html
diff --git a/1.0/spec/core/protocol-traits.html b/1.0/spec/core/protocol-traits.html
diff --git a/1.0/spec/core/resource-traits.html b/1.0/spec/core/resource-traits.html
diff --git a/1.0/spec/core/selectors.html b/1.0/spec/core/selectors.html
diff --git a/1.0/spec/core/stream-traits.html b/1.0/spec/core/stream-traits.html
diff --git a/1.0/spec/core/type-refinement-traits.html b/1.0/spec/core/type-refinement-traits.html
diff --git a/1.0/spec/core/xml-traits.html b/1.0/spec/core/xml-traits.html
diff --git a/1.0/spec/http-protocol-compliance-tests.html b/1.0/spec/http-protocol-compliance-tests.html
diff --git a/1.0/spec/index.html b/1.0/spec/index.html
diff --git a/1.0/spec/mqtt.html b/1.0/spec/mqtt.html
diff --git a/1.0/spec/waiters.html b/1.0/spec/waiters.html
diff --git a/_sources/1.0/guides/building-models/gradle-plugin.rst.txt b/_sources/1.0/guides/building-models/gradle-plugin.rst.txt
@@ -109,7 +109,7 @@ This extension supports the following properties:
       - ``FileCollection``
       - Sets a custom collection of smithy-build.json files to use when
         building the model.
-    * - allowUnknownTraits
+    * - allowsUnknownTraits
       - ``boolean``
       - Sets whether or not unknown traits in the model should be ignored. By
         default, the build will fail if unknown traits are encountered.

diff --git a/_sources/1.0/spec/aws/aws-core.rst.txt b/_sources/1.0/spec/aws/aws-core.rst.txt
@@ -622,15 +622,15 @@ previous example:
 Summary
     Indicates that the target contains data of the specified classification.
 Trait selector
-    ``:test(simpleType, list, structure, union, member)``
+    ``:test(simpleType, collection, structure, union, member)``
 Value type
     ``string`` that is one of: ``content``, ``account``, ``usage``,
     ``tagging``, or ``permissions``. See :ref:`data-classifications` for more
     information.
 
 Data classifications are resolved hierarchically: the data classification
 of a member inherits the effective data classification applied to a parent
-structure, union, or list unless overridden.
+structure, union, or collection unless overridden.
 
 .. tabs::
 

diff --git a/_sources/1.0/spec/core/constraint-traits.rst.txt b/_sources/1.0/spec/core/constraint-traits.rst.txt
@@ -1,5 +1,3 @@
-.. _constraint-traits:
-
 =================
 Constraint traits
 =================
@@ -600,72 +598,61 @@ in a response.
 
 
 .. smithy-trait:: smithy.api#uniqueItems
-.. _uniqueItems-trait:
+.. _uniqueItems:
 
 ---------------------
 ``uniqueItems`` trait
 ---------------------
 
+.. warning::
+
+    This trait has been deprecated. It will be removed in future versions
+    of Smithy. Set shapes should be used instead.
+
 Summary
-    Indicates that the items in a :ref:`list <list>` MUST be unique
-    based on :ref:`value-equality`.
+    Indicates that the items in a :ref:`list` MUST be unique.
 Trait selector
-    ``list :not(> member ~> :is(float, double, document))``
+    ``:test(list > member > simpleType)``
 
-    *A list that does not transitively contain floats, doubles, or documents*
-Conflicts with
-    * :ref:`sparse-trait`
+    *A list that targets any simple type.*
 Value type
     Annotation trait.
 
+.. tabs::
 
-.. code-block:: smithy
-
-    @uniqueItems
-    list MyList {
-        member: String
-    }
-
-
-.. _value-equality:
-
-Value equality
-==============
-
-Two values are considered equal if:
-
-* They are the same type.
-* Both are strings and are the same codepoint-for-codepoint.
-* Both are blobs and are the same byte-for-byte.
-* Both are booleans and are both true or are both false.
-* Both are timestamps and refer to the same instant in time.
-* Both are lists and have an equal value item-for-item. Note that
-  sets, a deprecated data type, are treated exactly like lists.
-* Both are maps, have the same number of entries, and each key value
-  pair in one map has an equal key value pair in the other map. The
-  order of entries does not matter.
-* Both are numbers of the same type and have the same mathematical value.
-* Both are structures of the same type and have the same members with
-  equal values.
-* Both are unions of the same type, are set to the same member, and the
-  set members have the same value.
+    .. code-tab:: smithy
 
-.. note::
+        @uniqueItems
+        list MyList {
+            member: String,
+        }
 
-    Floats, doubles, and documents are not allowed in ``@uniqueItems`` lists
-    because they only allow for partial equivalence and require special care
-    to determine if two values are considered equal.
+    .. code-tab:: json
 
+        {
+            "smithy": "1.0",
+            "shapes": {
+                "smithy.example#MyList": {
+                    "type": "list",
+                    "member": {
+                        "target": "smithy.api#String"
+                    },
+                    "traits": {
+                        "smithy.api#uniqueItems": {}
+                    }
+                }
+            }
+        }
 
 .. _precedence:
 
 ----------------
 Trait precedence
 ----------------
 
-Some constraint traits can be applied to shapes as well as members.
-Constraint traits applied to members take precedence over constraint
-traits applied to the shape targeted by members.
+Some constraints can be applied to shapes as well as structure members. If a
+constraint of the same type is applied to a structure member and the shape
+that the member targets, the trait applied to the member takes precedence.
 
 In the below example, the ``range`` trait applied to ``numberOfItems``
 takes precedence over the one applied to ``PositiveInteger``. The resolved
@@ -716,4 +703,3 @@ minimum will be ``7``, and the maximum ``12``.
 .. _ECMA 262 regular expression dialect: https://www.ecma-international.org/ecma-262/8.0/index.html#sec-patterns
 .. _CommonMark: https://spec.commonmark.org/
 .. _OWASP Regular expression Denial of Service: https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
-.. _JSON Schema "Instance Equality": https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.4.2.2
diff --git a/_sources/1.0/spec/core/documentation-traits.rst.txt b/_sources/1.0/spec/core/documentation-traits.rst.txt
@@ -245,12 +245,12 @@ These values use the same semantics and format as
             {
                 title: "Error example for MyOperation",
                 input: {
-                    foo: "!",
+                    foo: 1,
                 },
                 error: {
                     shapeId: MyOperationError,
                     content: {
-                        message: "Invalid 'foo'. Special character not allowed.",
+                        message: "Invalid 'foo'",
                     }
                 }
             },
@@ -395,12 +395,12 @@ Conflicts with
 -------------------
 
 Summary
-    Indicates that the data stored in the shape is sensitive and MUST be
-    handled with care.
+    Indicates that the data stored in the shape or member is sensitive
+    and MUST be handled with care.
 Trait selector
-    ``:not(:is(service, operation, resource, member))``
+    ``:not(:is(service, operation, resource))``
 
-    *Any shape that is not a service, operation, resource, or member.*
+    *Any shape that is not a service, operation, or resource.*
 Value type
     Annotation trait
 

diff --git a/_sources/1.0/spec/core/http-traits.rst.txt b/_sources/1.0/spec/core/http-traits.rst.txt
@@ -12,13 +12,10 @@ multiple HTTP message locations (e.g., a member cannot be bound to both a URI
 label and to a header). Only top-level members of an operation's input, output,
 and error structures are considered when serializing HTTP messages.
 
-.. important::
-
-    Violating `HTTP specifications`_ or relying on poorly-supported HTTP
-    functionality when defining HTTP bindings will limit interoperability
-    and likely lead to undefined behavior across Smithy implementations. For
-    example, avoid defining GET/DELETE requests with payloads, defining
-    response payloads for operations with a 204/205 status, etc.
+.. contents:: Table of contents
+    :depth: 1
+    :local:
+    :backlinks: none
 
 
 .. smithy-trait:: smithy.api#http
@@ -54,9 +51,7 @@ The ``http`` trait is a structure that supports the following members:
       - ``integer``
       - The HTTP status code of a successful response. Defaults to ``200`` if
         not provided. The provided value SHOULD be between 100 and 599, and
-        it MUST be between 100 and 999. Status codes that do not allow a body
-        like 204 and 205 SHOULD bind all output members to locations other than
-        the body of the response.
+        it MUST be between 100 and 999.
 
 The following example defines an operation that uses HTTP bindings:
 
@@ -518,11 +513,11 @@ Trait selector
     .. code-block:: none
 
         structure > :test(member > :test(boolean, number, string, timestamp,
-                list > member > :test(boolean, number, string, timestamp)))
+                collection > member > :test(boolean, number, string, timestamp)))
 
     The ``httpHeader`` trait can be applied to ``structure`` members that
     target a ``boolean``, ``number``, ``string``, or ``timestamp``; or a
-    ``structure`` member that targets a list of these types.
+    ``structure`` member that targets a list/set of these types.
 Value type
     ``string`` value defining a valid HTTP header field name according to
     :rfc:`section 3.2 of RFC7230 <7230#section-3.2>`. The value MUST NOT be
@@ -794,11 +789,10 @@ Trait selector
     .. code-block:: none
 
         structure > member
-        :test(> map :not([trait|sparse]) > member[id|member=value] > string)
+        :test(> map > member[id|member=value] > string)
 
     The ``httpPrefixHeaders`` trait can be applied to ``structure`` members
-    that target a ``map`` of ``string``. The targeted map MUST NOT be marked
-    with the :ref:`sparse-trait`.
+    that target a ``map`` of ``string``.
 Value type
     ``string`` value that defines the prefix to prepend to each header field
     name stored in the targeted map member. For example, given a prefix value
@@ -875,7 +869,7 @@ Trait selector
 
         structure > member
         :test(> :test(string, number, boolean, timestamp),
-              > list > member > :test(string, number, boolean, timestamp))
+              > collection > member > :test(string, number, boolean, timestamp))
 
     The ``httpQuery`` trait can be applied to ``structure`` members that
     target a ``string``, ``number``, ``boolean``, or ``timestamp``; or a
@@ -932,7 +926,7 @@ request:
   with a value of ``["a", "b"]``, the value is serialized in the query string
   as ``foo=a&foo=b``.
 * When deserializing, server implementations SHOULD use the first encountered
-  value in the query string for non-list members. For example, given a
+  value in the query string for non-collection members. For example, given a
   member bound to ``foo`` that targets a string and a query string of
   ``foo=a&foo=b``, the deserialized value of ``foo`` should be ``a``.
 
@@ -975,10 +969,10 @@ Trait selector
     .. code-block:: none
 
         structure > member
-        :test(> map > member[id|member=value] > :test(string, list > member > string))
+        :test(> map > member[id|member=value] > :test(string, collection > member > string))
 
     The ``httpQueryParams`` trait can be applied to ``structure`` members
-    that target a ``map`` of ``string``, or a ``map`` of ``list`` of
+    that target a ``map`` of ``string``, or a ``map`` of ``list``/``set`` of
     ``string``.
 
 Value type
@@ -1338,4 +1332,3 @@ marked with the ``httpPayload`` trait:
 
 .. _percent-encoded: https://tools.ietf.org/html/rfc3986#section-2.1
 .. _HTTP request line: https://tools.ietf.org/html/rfc7230.html#section-3.1.1
-.. _HTTP specifications: https://datatracker.ietf.org/doc/html/rfc7230
diff --git a/_sources/1.0/spec/core/idl.rst.txt b/_sources/1.0/spec/core/idl.rst.txt
@@ -1256,7 +1256,7 @@ is equivalent to the following JSON AST model:
                 "type": "structure",
                 "traits": {
                     "smithy.api#trait": {},
-                    "smithy.api#documentation": "This is documentation about a trait shape.\n  More docs here."
+                    "smithy.api#documentation": "This is documentation about a trait shapes.\n  More docs here."
                 }
             }
         }
@@ -1877,7 +1877,7 @@ is removed from a text block. The following example uses "." to denote spaces:
 
     """
     ..<div>
-    ....<p>Hi\n....bar</p>
+    ....<p>Hi\\n....bar</p>
     ..</div>
     .."""
 

diff --git a/_sources/1.0/spec/core/model-validation.rst.txt b/_sources/1.0/spec/core/model-validation.rst.txt
@@ -337,7 +337,7 @@ following constraints:
     metadata validators = [{
         name: "EmitEachSelector",
         id: "MissingDocumentation",
-        message: "This shape is missing documentation",
+        message: "This shape is missing documentation"
         configuration: {
             selector: """
                 :not([trait|documentation])

diff --git a/_sources/1.0/spec/core/model.rst.txt b/_sources/1.0/spec/core/model.rst.txt
@@ -458,7 +458,7 @@ reference other shapes using :ref:`members <member>`.
     * - :ref:`list`
       - Ordered collection of homogeneous values
     * - :ref:`set`
-      - (Deprecated) Ordered collection of unique homogeneous values
+      - Ordered collection of unique homogeneous values
     * - :ref:`map`
       - Map data structure that maps string keys to homogeneous values
     * - :ref:`structure`
@@ -565,19 +565,10 @@ example is ``smithy.example#MyList$member``.
 Set
 ===
 
-.. danger::
-
-    Sets are deprecated. Use a list with the :ref:`uniqueItems-trait` instead.
-
 The :dfn:`set` type represents an ordered collection of unique values. A set
-shape requires a single member named ``member``. Sets are implicitly considered
-to be marked with the :ref:`uniqueItems-trait`, and as such MUST NOT transitively
-contain floats, doubles, or documents.
-
-.. important::
-
-    Sets are considered sub-type of lists; any place a list is accepted, a set
-    is accepted.
+shape requires a single member named ``member``, and the member MUST target
+either a string, blob, byte, short, integer, long, bigInteger, or bigDecimal
+shape. The targeted shape MUST NOT be marked with the :ref:`streaming-trait`.
 
 Sets are defined in the IDL using a :ref:`set_statement <idl-set>`. The
 following example defines a set of strings:
@@ -623,14 +614,11 @@ The shape ID of the member of a set is the set shape ID followed by
 ``$member``. For example, the shape ID of the set member in the above
 example is ``smithy.example#StringSet$member``.
 
-.. rubric:: Use insertion order
+.. rubric:: Language support for insertion ordered sets
 
-Implementations SHOULD use insertion ordered sets to ensure that clients and
-servers both agree on element ordering so that error messages about specific
-items in a set are actionable by clients. If a client and server don't agree
-on ordering, then pointing to where a validation error occurs becomes very
-challenging. Programming languages that do not support insertion ordered sets
-SHOULD store the values of a set in a list.
+Not all programming languages support an insertion ordered set data
+structure. Such languages SHOULD store the values of a set data
+structure in a list and rely on validation to ensure uniqueness.
 
 
 .. _map:
@@ -979,12 +967,8 @@ Smithy allows recursive shape definitions with the following limitations:
    that shapes that are typically impossible to define in various programming
    languages are not defined in Smithy models (for example, you can't define
    a recursive list in Java ``List<List<List....``).
-2. To ensure a value can be provided for a structure, recursive member
-   relationship from a structure back to itself MUST NOT be made up of all
-   :ref:`required <required-trait>` structure members.
-3. To ensure a value can be provided for a union, recursive unions MUST
-   contain at least one path through its members that is not recursive
-   or steps through a list, set, map, or optional structure member.
+2. A structure cannot contain a cyclical set of members marked with the
+   :ref:`required-trait` that refers back to itself.
 
 The following recursive shape definition is **valid**:
 

diff --git a/_sources/1.0/spec/core/selectors.rst.txt b/_sources/1.0/spec/core/selectors.rst.txt
@@ -78,8 +78,7 @@ Shapes can be matched by type using the following tokens:
     * - ``simpleType``
       - Matches all :ref:`simple types <simple-types>`
     * - ``collection``
-      - Deprecated: Matches both a ``list`` and ``set`` shape.
-        This is considered an alias for ``list``.
+      - Matches both a ``list`` and ``set`` shape
     * - ``blob``
       - Matches blob shapes
     * - ``boolean``
@@ -107,10 +106,9 @@ Shapes can be matched by type using the following tokens:
     * - ``timestamp``
       -  Matches timestamp shapes
     * - ``list``
-      - Matches list shapes. Note that set shapes also match ``list`` because
-        they are considered sub-types of list.
+      - Matches list shapes
     * - ``set``
-      - Deprecated: Matches set shapes. This is considered an alias for ``list``.
+      - Matches set shapes
     * - ``map``
       -  Matches map shapes
     * - ``structure``