From 2a922c71aa2b94004b318841726946aeb41ee907 Mon Sep 17 00:00:00 2001 From: Steven Yuan Date: Wed, 17 Aug 2022 15:29:01 -0700 Subject: [PATCH] Update Smithy IDL ABNF Docs - Smithy 1.0: Update all ABNF to match ABNF RFC - Smithy 2.0: Update IDL ABNF, XmlName ABNF, and minor doc fixes --- .../spec/aws/aws-ec2-query-protocol.rst | 8 +- .../spec/aws/aws-json-1_1-protocol.rst | 2 +- .../source-1.0/spec/aws/aws-json.rst.template | 6 +- .../spec/aws/aws-query-protocol.rst | 6 +- .../aws/aws-query-serialization.rst.template | 2 +- .../spec/aws/aws-restjson1-protocol.rst | 2 +- .../spec/aws/aws-restxml-protocol.rst | 4 +- docs/source-1.0/spec/core/behavior-traits.rst | 2 +- docs/source-1.0/spec/core/idl.rst | 334 ++++++++++-------- docs/source-1.0/spec/core/json-ast.rst | 4 +- .../source-1.0/spec/core/model-validation.rst | 2 +- docs/source-1.0/spec/core/model.rst | 30 +- docs/source-1.0/spec/core/selectors.rst | 122 +++---- docs/source-1.0/spec/core/xml-traits.rst | 8 +- .../spec/http-protocol-compliance-tests.rst | 6 +- docs/source-2.0/spec/idl.rst | 71 ++-- docs/source-2.0/spec/protocol-traits.rst | 8 +- docs/source-2.0/spec/selectors.rst | 6 +- 18 files changed, 331 insertions(+), 292 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 index 54e4d6b3296..0263e2e0e38 100644 --- a/docs/source-1.0/spec/aws/aws-ec2-query-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-ec2-query-protocol.rst @@ -147,9 +147,9 @@ resolved using the following process: * - Member location - Default value * - ``structure`` member - - The :token:`member name ` capitalized + - The :token:`member name ` capitalized * - ``union`` member - - The :token:`member name ` capitalized + - The :token:`member name ` capitalized ---------------- @@ -351,7 +351,7 @@ of the ``Errors`` tag is an ``Error`` tag which contains the serialized error structure members. Serialized error shapes MUST also contain an additional child element ``Code`` -that contains only the :token:`shape name ` of the error's +that contains only the :token:`shape name ` of the error's :ref:`shape-id`. This can be used to distinguish which specific error has been serialized in the response. @@ -368,7 +368,7 @@ serialized in the response. foo-id -* ``Code``: The :token:`shape name ` of the error's +* ``Code``: The :token:`shape name ` of the error's :ref:`shape-id`. * ``RequestId``: Contains a unique identifier for the associated request. diff --git a/docs/source-1.0/spec/aws/aws-json-1_1-protocol.rst b/docs/source-1.0/spec/aws/aws-json-1_1-protocol.rst index 93f7e8882d3..ceff770e895 100644 --- a/docs/source-1.0/spec/aws/aws-json-1_1-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-json-1_1-protocol.rst @@ -133,7 +133,7 @@ The following example defines a service that requires the use of .. |quoted shape name| replace:: ``awsJson1_1`` .. |protocol content type| replace:: ``application/x-amz-json-1.1`` -.. |protocol error type contents| replace:: :token:`shape name ` +.. |protocol error type contents| replace:: :token:`shape name ` .. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_1 .. include:: aws-json.rst.template diff --git a/docs/source-1.0/spec/aws/aws-json.rst.template b/docs/source-1.0/spec/aws/aws-json.rst.template index 345d5dc3e53..7d72f4abb17 100644 --- a/docs/source-1.0/spec/aws/aws-json.rst.template +++ b/docs/source-1.0/spec/aws/aws-json.rst.template @@ -50,9 +50,9 @@ The |quoted shape name| protocol uses the following headers: `RFC 7230 Section 3.3.2`_. * - ``X-Amz-Target`` - true for requests - - The value of this header is the :token:`shape name ` of the + - The value of this header is the :token:`shape name ` of the service's :ref:`shape-id` joined to the - :token:`shape name ` of the operation's :ref:`shape-id`, + :token:`shape name ` 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 @@ -188,7 +188,7 @@ There are two difference between :ref:`awsJson1_0 `. However, clients MUST accept either behavior +:token:`shape name `. However, clients MUST accept either behavior for both protocols. See `Operation error serialization`_ for full details on how to deserialize errors for |quoted shape name|. diff --git a/docs/source-1.0/spec/aws/aws-query-protocol.rst b/docs/source-1.0/spec/aws/aws-query-protocol.rst index fd8c904ec36..9ad50dc0367 100644 --- a/docs/source-1.0/spec/aws/aws-query-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-query-protocol.rst @@ -141,9 +141,9 @@ resolved using the following process: * - ``map`` value - The string literal "value" * - ``structure`` member - - The :token:`member name ` + - The :token:`member name ` * - ``union`` member - - The :token:`member name ` + - The :token:`member name ` Example requests @@ -436,7 +436,7 @@ following process: 1. Use the value of the ``code`` member of the :ref:`aws.protocols#awsQueryError-trait` applied to the error structure, if present. -2. The :token:`shape name ` of the error's :ref:`shape-id`. +2. The :token:`shape name ` of the error's :ref:`shape-id`. .. smithy-trait:: aws.protocols#awsQuery diff --git a/docs/source-1.0/spec/aws/aws-query-serialization.rst.template b/docs/source-1.0/spec/aws/aws-query-serialization.rst.template index 18cee396aac..4b11f1fbb8f 100644 --- a/docs/source-1.0/spec/aws/aws-query-serialization.rst.template +++ b/docs/source-1.0/spec/aws/aws-query-serialization.rst.template @@ -18,7 +18,7 @@ Requests MUST include the following key value pairs in the serialized body: * - Key - Value * - ``Action`` - - The :token:`shape name ` of the operation's :ref:`shape-id`. + - The :token:`shape name ` of the operation's :ref:`shape-id`. * - ``Version`` - The value of the :ref:`"version" property of the service `. diff --git a/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst b/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst index ca62571b740..298ad68a1a1 100644 --- a/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst @@ -316,7 +316,7 @@ is contained. New server-side protocol implementations MUST use a header field named ``X-Amzn-Errortype``. Clients MUST accept any one of the following: an additional header with the name ``X-Amzn-Errortype``, a body field with the name ``__type``, or a body field named ``code``. The value of this component -SHOULD contain only the :token:`shape name ` of the error's +SHOULD contain only the :token:`shape name ` of the error's :ref:`shape-id`. Legacy server-side protocol implementations sometimes include additional diff --git a/docs/source-1.0/spec/aws/aws-restxml-protocol.rst b/docs/source-1.0/spec/aws/aws-restxml-protocol.rst index b96e536adc9..736a0447bf3 100644 --- a/docs/source-1.0/spec/aws/aws-restxml-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-restxml-protocol.rst @@ -261,7 +261,7 @@ contains the serialized error structure members, unless bound to another location with HTTP protocol bindings. Serialized error shapes MUST also contain an additional child element ``Code`` -that contains only the :token:`shape name ` of the error's +that contains only the :token:`shape name ` of the error's :ref:`shape-id`. This can be used to distinguish which specific error has been serialized in the response. @@ -295,7 +295,7 @@ Error responses contain the following nested elements: * ``Error``: A container for the encountered error. * ``Type``: One of "Sender" or "Receiver"; whomever is at fault from the service perspective. -* ``Code``: The :token:`shape name ` of the error's +* ``Code``: The :token:`shape name ` of the error's :ref:`shape-id`. * ``RequestId``: Contains a unique identifier for the associated request. diff --git a/docs/source-1.0/spec/core/behavior-traits.rst b/docs/source-1.0/spec/core/behavior-traits.rst index dee948f30ed..348eea4a5ed 100644 --- a/docs/source-1.0/spec/core/behavior-traits.rst +++ b/docs/source-1.0/spec/core/behavior-traits.rst @@ -325,7 +325,7 @@ member in the previously referenced structure. Paths MUST adhere to the following ABNF. .. productionlist:: smithy - path :`identifier` *("." `identifier`) + path :`Identifier` *("." `Identifier`) The following example defines a paginated operation which uses a result wrapper where the output token and items are referenced by paths. diff --git a/docs/source-1.0/spec/core/idl.rst b/docs/source-1.0/spec/core/idl.rst index bf4670b060b..b0d01e25127 100644 --- a/docs/source-1.0/spec/core/idl.rst +++ b/docs/source-1.0/spec/core/idl.rst @@ -19,7 +19,7 @@ The Smithy IDL is made up of 3, ordered sections, each of which is optional: 2. **Metadata section**; applies metadata to the entire model. 3. **Shape section**; where shapes and traits are defined. A namespace MUST be defined before any shapes or traits can be defined. - :token:`smithy:use_statement`\s can be defined after a namespace and before shapes + :token:`smithy:UseStatement`\s can be defined after a namespace and before shapes or traits to refer to shapes in other namespaces using a shorter name. The following example defines a model file with each section: @@ -71,8 +71,9 @@ The following example defines a model file with each section: Lexical notes ------------- -Smithy models MUST be encoded using UTF-8 and SHOULD use Unix style -line endings (``\n``). The Smithy ABNF is whitespace sensitive. +* Smithy models MUST be encoded using UTF-8 and SHOULD use Unix style + line endings (``\n``). +* The Smithy ABNF is whitespace sensitive. .. _smithy-idl-abnf: @@ -81,135 +82,160 @@ line endings (``\n``). The Smithy ABNF is whitespace sensitive. Smithy IDL ABNF --------------- -The Smithy IDL is defined by the following ABNF: +The Smithy IDL is defined by the following ABNF which uses case-sensitive +string support defined in `RFC 5234 `_. .. productionlist:: smithy - idl:`ws` `control_section` `metadata_section` `shape_section` + idl:*`WS` `ControlSection` `MetadataSection` `ShapeSection` .. rubric:: Whitespace .. productionlist:: smithy - ws :*(`sp` / `newline` / `comment`) ; whitespace - sp :*(%x20 / %x09) ; " " and \t - br :`sp` (`comment` / `newline`) `sp` ; break - newline :%x0A / %x0D.0A ; \n and \r\n + WS :1*(`SP` / `NL` / `Comment`) ; whitespace + SP :1*(%x20 / %x09) ; one or more spaces or tabs + NL :%x0A / %x0D.0A ; Newline: \n and \r\n + NotNL :%x09 / %x20-10FFFF ; Any character except newline + BR :*`SP` 1*(`Comment` / `NL`) *`WS`; line break followed by whitespace .. rubric:: Comments .. productionlist:: smithy - comment: `documentation_comment` / `line_comment` - documentation_comment:"///" *`not_newline` `br` - line_comment: "//" *`not_newline` `newline` - not_newline: %x09 / %x20-10FFFF ; Any character except newline + Comment : `DocumentationComment` / `LineComment` + DocumentationComment :"///" *`NotNL` `NL` + LineComment : "//" *`NotNL` `NL` .. rubric:: Control .. productionlist:: smithy - control_section :*(`control_statement`) - control_statement :"$" `ws` `node_object_key` `ws` ":" `ws` `node_value` `br` + ControlSection :*(`ControlStatement`) + ControlStatement :"$" `NodeObjectKey` *`SP` ":" *`SP` `NodeValue` `BR` .. rubric:: Metadata .. productionlist:: smithy - metadata_section :*(`metadata_statement`) - metadata_statement :"metadata" `ws` `node_object_key` `ws` "=" `ws` `node_value` `br` + MetadataSection :*(`MetadataStatement`) + MetadataStatement :%s"metadata" `SP` `NodeObjectKey` *`SP` "=" *`SP` `NodeValue` `BR` .. rubric:: Node values .. productionlist:: smithy - node_value :`node_array` - :/ `node_object` - :/ `number` - :/ `node_keywords` - :/ `node_string_value` - node_array :`empty_node_array` / `populated_node_array` - empty_node_array :"[" `ws` "]" - populated_node_array:"[" `ws` `node_value` `ws` - : *(`comma` `node_value` `ws`) - : `trailing_comma` "]" - trailing_comma :[`comma`] - comma :"," `ws` - node_object :`empty_node_object` / `populated_node_object` - empty_node_object :"{" `ws` "}" - populated_node_object:"{" `ws` `node_object_kvp` `ws` - : *(`comma` `node_object_kvp` `ws`) - : `trailing_comma` "}" - node_object_kvp :`node_object_key` `ws` ":" `ws` `node_value` - node_object_key :`quoted_text` / `identifier` - number :[`minus`] `int` [`frac`] [`exp`] - decimal_point :%x2E ; . - digit1_9 :%x31-39 ; 1-9 - e :%x65 / %x45 ; e E - exp :`e` [`minus` / `plus`] 1*DIGIT - frac :`decimal_point` 1*DIGIT - int :`zero` / (`digit1_9` *DIGIT) - minus :%x2D ; - - plus :%x2B ; + - zero :%x30 ; 0 - node_keywords: "true" / "false" / "null" - node_string_value :`shape_id` / `text_block` / `quoted_text` - quoted_text :DQUOTE *`quoted_char` DQUOTE - quoted_char :%x20-21 ; space - "!" - :/ %x23-5B ; "#" - "[" - :/ %x5D-10FFFF ; "]"+ - :/ `escaped_char` - :/ `preserved_double` - escaped_char :`escape` (`escape` / "'" / DQUOTE / "b" - : / "f" / "n" / "r" / "t" / "/" / `unicode_escape`) - unicode_escape :"u" `hex` `hex` `hex` `hex` - hex : DIGIT / %x41-46 / %x61-66 - preserved_double :`escape` (%x20-21 / %x23-5B / %x5D-10FFFF) - escape :%x5C ; backslash - text_block :`three_dquotes` `br` *`quoted_char` `three_dquotes` - three_dquotes :DQUOTE DQUOTE DQUOTE + NodeValue :`NodeArray` + :/ `NodeObject` + :/ `Number` + :/ `NodeKeywords` + :/ `NodeStringValue` + NodeArray :"[" *`WS` + : [`NodeValue` *`WS` + : *(`Comma` `NodeValue` *`WS`) + : `TrailingComma`] + : "]" + Comma :"," *`WS` + TrailingComma :[`Comma`] + NodeObject :"{" *`WS` + : [`NodeObjectKvp` *`WS` + : *(`Comma` `NodeObjectKvp` *`WS`) + : `TrailingComma`] + : "}" + NodeObjectKvp :`NodeObjectKey` *`WS` ":" *`WS` `NodeValue` + NodeObjectKey :`QuotedText` / `Identifier` + Number :[`Minus`] `Int` [`Frac`] [`Exp`] + DecimalPoint :%x2E ; . + DigitOneToNine :%x31-39 ; 1-9 + E :%x65 / %x45 ; e E + Exp :`E` [`Minus` / `Plus`] 1*DIGIT + Frac :`DecimalPoint` 1*DIGIT + Int :`Zero` / (`DigitOneToNine` *DIGIT) + Minus :%x2D ; - + Plus :%x2B ; + + Zero :%x30 ; 0 + NodeKeywords :%s"true" / %s"false" / %s"null" + NodeStringValue :`ShapeId` / `TextBlock` / `QuotedText` + QuotedText :DQUOTE *`QuotedChar` DQUOTE + QuotedChar :%x20-21 ; space - "!" + :/ %x23-5B ; "#" - "[" + :/ %x5D-10FFFF ; "]"+ + :/ `EscapedChar` + :/ `PreservedDouble` + :/ `NL` + EscapedChar :`Escape` (`Escape` / "'" / DQUOTE / %s"b" + : / %s"f" / %s"n" / %s"r" / %s"t" + : / "/" / `UnicodeEscape`) + UnicodeEscape :%s"u" `Hex` `Hex` `Hex` `Hex` + Hex :DIGIT / %x41-46 / %x61-66 + PreservedDouble :`Escape` (%x20-21 / %x23-5B / %x5D-10FFFF) + Escape :%x5C ; backslash + TextBlock :`ThreeDquotes` *`SP` `NL` *`QuotedChar` `ThreeDquotes` + ThreeDquotes :DQUOTE DQUOTE DQUOTE .. rubric:: Shapes .. productionlist:: smithy - shape_section :[`namespace_statement` [`use_section`] [`shape_statements`]] - namespace_statement :"namespace" `ws` `namespace` `br` - use_section :*(`use_statement`) - use_statement :"use" `ws` `absolute_root_shape_id` `br` - shape_statements :*(`shape_statement` / `apply_statement`) - shape_statement :`trait_statements` `shape_body` `br` - shape_body :`simple_shape_statement` - :/ `list_statement` - :/ `set_statement` - :/ `map_statement` - :/ `structure_statement` - :/ `union_statement` - :/ `service_statement` - :/ `operation_statement` - :/ `resource_statement` - simple_shape_statement :`simple_type_name` `ws` `identifier` - simple_type_name :"blob" / "boolean" / "document" / "string" - :/ "byte" / "short" / "integer" / "long" - :/ "float" / "double" / "bigInteger" - :/ "bigDecimal" / "timestamp" - shape_members :`empty_shape_members` / `populated_shape_members` - empty_shape_members :"{" `ws` "}" - populated_shape_members :"{" `ws` `shape_member_kvp` - : *(`comma` `shape_member_kvp` `ws`) `trailing_comma` "}" - shape_member_kvp :`trait_statements` `identifier` `ws` ":" `ws` `shape_id` - 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` `node_object` - resource_statement :"resource" `ws` `identifier` `ws` `node_object` + ShapeSection :[`NamespaceStatement` `UseSection` `ShapeStatements`] + NamespaceStatement :%s"namespace" `SP` `Namespace` `BR` + UseSection :*(`UseStatement`) + UseStatement :%s"use" `SP` `AbsoluteRootShapeId` `BR` + ShapeStatements :*(`ShapeStatement` / `ApplyStatement`) + ShapeStatement :`TraitStatements` `ShapeBody` `BR` + ShapeBody :`SimpleShapeStatement` + :/ `ListStatement` + :/ `SetStatement` + :/ `MapStatement` + :/ `StructureStatement` + :/ `UnionStatement` + :/ `ServiceStatement` + :/ `OperationStatement` + :/ `ResourceStatement` + SimpleShapeStatement :`SimpleTypeName` `SP` `Identifier` + SimpleTypeName :%s"blob" / %s"boolean" / %s"document" / %s"string" + :/ %s"byte" / %s"short" / %s"integer" / %s"long" + :/ %s"float" / %s"double" / %s"bigInteger" + :/ %s"bigDecimal" / %s"timestamp" + ListStatement :%s"list" `SP` `Identifier` *`WS` `ListMembers` + ListMembers :"{" *`WS` `ListMember` *`WS` "}" + ListMember :`TraitStatements` `ExplicitListMember` + ExplicitListMember :%s"member" *`SP` ":" *`SP` `ShapeId` + SetStatement :%s"set" `SP` `Identifier` *`WS` `SetMembers` + SetMembers :"{" *`WS` `SetMember` *`WS` "}" + SetMember :`TraitStatements` `ExplicitSetMember` + ExplicitSetMember :%s"member" *`SP` ":" *`SP` `ShapeId` + MapStatement :%s"map" `SP` `Identifier` *`WS` `MapMembers` + MapMembers :"{" *`WS` `MapKey` `WS` `MapValue` *`WS` "}" + MapKey :`TraitStatements` `ExplicitMapKey` + ExplicitMapKey :%s"key" *`SP` ":" *`SP` `ShapeId` + MapValue :`TraitStatements` `ExplicitMapValue` + ExplicitMapValue :%s"value" *`SP` ":" *`SP` `ShapeId` + StructureStatement :%s"structure" `SP` `Identifier` *`WS` `StructureMembers` + StructureMembers :"{" *`WS` + : [`StructureMember` *`WS` + : *(`Comma` `StructureMember` *`WS`) + : `TrailingComma`] + : "}" + StructureMember :`TraitStatements` `ExplicitStructureMember` + ExplicitStructureMember :`Identifier` *`SP` ":" *`SP` `ShapeId` + UnionStatement :%s"union" `SP` `Identifier` *`WS` `UnionMembers` + UnionMembers :"{" *`WS` + : `UnionMember` *`WS` + : *(`Comma` `UnionMember` *`WS`) + : `TrailingComma` + : "}" + UnionMember :`TraitStatements` `ExplicitUnionMember` + ExplicitUnionMember :`Identifier` *`SP` ":" *`SP` `ShapeId` + ServiceStatement :%s"service" `SP` `Identifier` *`WS` `NodeObject` + ResourceStatement :%s"resource" `SP` `Identifier` *`WS` `NodeObject` + OperationStatement :%s"operation" `SP` `Identifier` *`WS` `NodeObject` .. rubric:: Traits .. productionlist:: smithy - trait_statements : *(`ws` `trait`) `ws` - trait :"@" `shape_id` [`trait_body`] - trait_body :"(" `ws` `trait_body_value` `ws` ")" - trait_body_value :`trait_structure` / `node_value` - trait_structure :`trait_structure_kvp` *(`ws` `comma` `trait_structure_kvp`) - trait_structure_kvp :`node_object_key` `ws` ":" `ws` `node_value` - apply_statement :"apply" `ws` `shape_id` `ws` `trait` `br` + TraitStatements :*(*`WS` `Trait`) *`WS` + Trait :"@" `ShapeId` [`TraitBody`] + TraitBody :"(" *`WS` [`TraitBodyValue`] *`WS` ")" + TraitBodyValue :`TraitStructure` / `NodeValue` + TraitStructure :`TraitStructureKvp` *`WS` + : *(`Comma` `TraitStructureKvp` *`WS`) + : `TrailingComma` + TraitStructureKvp :`NodeObjectKey` *`WS` ":" *`WS` `NodeValue` + ApplyStatement :%s"apply" `WS` `ShapeId` `WS` `Trait` `BR` .. rubric:: Shape ID @@ -224,8 +250,8 @@ The Smithy IDL is defined by the following ABNF: Comments -------- -A :token:`comment ` can appear at any place between tokens where -whitespace (:token:`smithy:ws`) can appear. Comments in Smithy are defined using two +A :token:`comment ` can appear at any place between tokens where +whitespace (:token:`smithy:WS`) can appear. Comments in Smithy are defined using two forward slashes followed by any character. A newline terminates a comment. .. code-block:: smithy @@ -248,15 +274,27 @@ forward slashes followed by any character. A newline terminates a comment. Control section --------------- -The :token:`control section ` of a model contains -:token:`control statements ` that apply parser directives +The :token:`control section ` of a model contains +:token:`control statements ` that apply parser directives to a *specific IDL file*. Because control statements influence parsing, they MUST appear at the beginning of a file before any other statements and have -no effect on the :ref:`semantic model ` +no effect on the :ref:`semantic model `. -The :ref:`version ` statement is currently the only control -statement defined in the Smithy IDL. Implementations MUST ignore unknown -control statements. +The following control statements are currently supported: + +.. list-table:: + :header-rows: 1 + :widths: 10 10 80 + + * - Name + - Type + - Description + * - version + - string + - Defines the :ref:`version ` of the Smithy IDL used in + the model file. + +Implementations MUST ignore unknown control statements. .. _smithy-version: @@ -323,10 +361,10 @@ supported by the tool loading the models. Metadata section ---------------- -The :token:`metadata section ` is used to apply untyped -:ref:`metadata ` to the entire model. A :token:`smithy:metadata_statement` +The :token:`metadata section ` is used to apply untyped +:ref:`metadata ` to the entire model. A :token:`smithy:MetadataStatement` consists of the metadata key to set, followed by ``=``, followed by the -:token:`node value ` to assign to the key. +:token:`node value ` to assign to the key. The following example defines metadata in the model: @@ -352,7 +390,7 @@ The following example defines metadata in the model: Shape section ------------- -The :token:`shape section ` of the IDL is used to define +The :token:`shape section ` of the IDL is used to define shapes and apply traits to shapes. @@ -362,7 +400,7 @@ Namespaces ========== Shapes can only be defined after a namespace is declared. A namespace is -declared using a :token:`namespace statement `. Only +declared using a :token:`namespace statement `. Only one namespace can appear per file. The following example defines a string shape named ``MyString`` in the @@ -393,9 +431,9 @@ The following example defines a string shape named ``MyString`` in the Referring to shapes =================== -The :token:`use section ` of the IDL is used to import shapes +The :token:`use section ` of the IDL is used to import shapes into the current namespace so that they can be referred to using a -:ref:`relative shape ID `. The :token:`use_statement `\s +:ref:`relative shape ID `. The :token:`UseStatement `\s that make up this section have no effect on the :ref:`semantic model `. The following example uses ``smithy.example#Foo`` and ``smithy.example#Baz`` @@ -443,7 +481,7 @@ Relative shape ID resolution Relative shape IDs are resolved using the following process: -#. If a :token:`smithy:use_statement` has imported a shape with the same name, +#. If a :token:`smithy:UseStatement` has imported a shape with the same name, the shape ID resolves to the imported shape ID. #. If a shape is defined in the same namespace as the shape with the same name, the namespace of the shape resolves to the *current namespace*. @@ -622,7 +660,7 @@ reference can be ignored. Defining shapes =============== -Shapes are defined using a :token:`smithy:shape_statement`. +Shapes are defined using a :token:`smithy:ShapeStatement`. .. _idl-simple: @@ -631,7 +669,7 @@ Simple shapes ------------- :ref:`Simple shapes ` are defined using a -:token:`smithy:simple_shape_statement`. +:token:`smithy:SimpleShapeStatement`. The following example defines a ``string`` shape: @@ -688,7 +726,7 @@ The following example defines an ``integer`` shape with a :ref:`range-trait`: List shapes ----------- -A :ref:`list ` shape is defined using a :token:`smithy:list_statement`. +A :ref:`list ` shape is defined using a :token:`smithy:ListStatement`. The following example defines a list with a string member from the :ref:`prelude `: @@ -763,7 +801,7 @@ Traits can be applied to the list shape and its member: Set shapes ---------- -A :ref:`set ` set shape is defined using a :token:`smithy:set_statement`. +A :ref:`set ` set shape is defined using a :token:`smithy:SetStatement`. The following example defines a set of strings: @@ -831,7 +869,7 @@ Traits can be applied to the set shape and its members: Map shapes ---------- -A :ref:`map ` shape is defined using a :token:`smithy:map_statement`. +A :ref:`map ` shape is defined using a :token:`smithy:MapStatement`. The following example defines a map of strings to integers: @@ -922,7 +960,7 @@ Structure shapes ---------------- A :ref:`structure ` shape is defined using a -:token:`smithy:structure_statement`. +:token:`smithy:StructureStatement`. The following example defines a structure with two members: @@ -1011,7 +1049,7 @@ Traits can be applied to structure members: Union shapes ------------ -A :ref:`union ` shape is defined using a :token:`smithy:union_statement`. +A :ref:`union ` shape is defined using a :token:`smithy:UnionStatement`. The following example defines a union shape with several members: @@ -1062,8 +1100,8 @@ The following example defines a union shape with several members: Service shape ------------- -A service shape is defined using a :token:`smithy:service_statement` and the provided -:token:`smithy:node_object` supports the same properties defined in the +A service shape is defined using a :token:`smithy:ServiceStatement` and the provided +:token:`smithy:NodeObject` supports the same properties defined in the :ref:`service specification `. The following example defines a service named ``ModelRepository`` that binds @@ -1108,8 +1146,8 @@ a resource named ``Model`` and an operation named ``PingService``: Operation shape --------------- -An operation shape is defined using an :token:`smithy:operation_statement` and the -provided :token:`smithy:node_object` supports the same properties defined in the +An operation shape is defined using an :token:`smithy:OperationStatement` and the +provided :token:`smithy:NodeObject` supports the same properties defined in the :ref:`operation specification `. The following example defines an operation shape that accepts an input @@ -1160,8 +1198,8 @@ can potentially return the ``Unavailable`` or ``BadRequest`` Resource shape -------------- -A resource shape is defined using a :token:`smithy:resource_statement` and the -provided :token:`smithy:node_object` supports the same properties defined in the +A resource shape is defined using a :token:`smithy:ResourceStatement` and the +provided :token:`smithy:NodeObject` supports the same properties defined in the :ref:`resource specification `. The following example defines a resource shape that has a single identifier, @@ -1205,8 +1243,8 @@ and defines a :ref:`read ` operation: Documentation comment ===================== -:token:`Documentation comments ` are a -special kind of :token:`smithy:comment` that provide +:token:`Documentation comments ` are a +special kind of :token:`smithy:Comment` that provide :ref:`documentation ` for shapes. A documentation comment is formed when three forward slashes (``"///"``) appear as the first non-whitespace characters on a line. @@ -1297,7 +1335,7 @@ Applying traits =============== Trait values immediately preceding a shape definition are applied to the -shape. The shape ID of a trait is *resolved* against :token:`smithy:use_statement`\s +shape. The shape ID of a trait is *resolved* against :token:`smithy:UseStatement`\s and the current namespace in exactly the same way as :ref:`other shape IDs `. @@ -1431,7 +1469,7 @@ List and set trait values ------------------------- Traits that are a ``list`` or ``set`` shape are defined inside -of brackets (``[``) and (``]``) using a :token:`smithy:node_array` production. +of brackets (``[``) and (``]``) using a :token:`smithy:NodeArray` production. .. code-block:: smithy @@ -1457,7 +1495,7 @@ Apply statement --------------- Traits can be applied to shapes outside of a shape's definition using an -:token:`smithy:apply_statement`. +:token:`smithy:ApplyStatement`. The following example applies the :ref:`documentation-trait` and :ref:`length-trait` to the ``smithy.example#MyString`` shape: @@ -1544,9 +1582,9 @@ node value: .. rubric:: Array node -An array node is defined like a JSON array. A :token:`smithy:node_array` contains -zero or more heterogeneous :token:`smithy:node_value`\s. A trailing comma is allowed -in a ``node_array``. +An array node is defined like a JSON array. A :token:`smithy:NodeArray` contains +zero or more heterogeneous :token:`smithy:NodeValue`\s. A trailing comma is allowed +in a ``NodeArray``. The following examples define arrays with zero, one, and two values: @@ -1556,10 +1594,10 @@ The following examples define arrays with zero, one, and two values: .. rubric:: Object node -An object node is defined like a JSON object. A :token:`smithy:node_object` contains -zero or more key value pairs of strings (a :token:`smithy:node_object_key`) that map -to heterogeneous :token:`smithy:node_value`\s. A trailing comma is allowed -in a ``node_object``. +An object node is defined like a JSON object. A :token:`smithy:NodeObject` contains +zero or more key value pairs of strings (a :token:`smithy:NodeObjectKey`) that map +to heterogeneous :token:`smithy:NodeValue`\s. A trailing comma is allowed +in a ``NodeObject``. The following examples define objects with zero, one, and two key value pairs: @@ -1569,8 +1607,8 @@ The following examples define objects with zero, one, and two key value pairs: .. rubric:: Number node -A node :token:`smithy:number` contains numeric data. It is defined like a JSON -number. The following examples define several ``number`` values: +A node :token:`smithy:Number` contains numeric data. It is defined like a JSON +Number. The following examples define several ``Number`` values: * ``0`` * ``0.0`` @@ -1581,7 +1619,7 @@ number. The following examples define several ``number`` values: .. rubric:: Node keywords -Several keywords are used when parsing :token:`smithy:node_value`. +Several keywords are used when parsing :token:`smithy:NodeValue`. * ``true``: The value is treated as a boolean ``true`` * ``false``: The value is treated as a boolean ``false`` @@ -1591,7 +1629,7 @@ Several keywords are used when parsing :token:`smithy:node_value`. String values ============= -A ``node_value`` can contain :token:`smithy:node_string_value` productions that all +A ``NodeValue`` can contain :token:`smithy:NodeStringValue` productions that all define strings. .. rubric:: New lines @@ -1603,7 +1641,7 @@ a string value using the Unicode escape ``\u000d``. .. rubric:: String equivalence -The ``node_string_value`` production defines several productions used to +The ``NodeStringValue`` production defines several productions used to define strings, and in order for these productions to work in concert with the :ref:`JSON AST format `, each of these production MUST be treated like equivalent string values when loaded into the diff --git a/docs/source-1.0/spec/core/json-ast.rst b/docs/source-1.0/spec/core/json-ast.rst index 5edc8ef162d..fd8e35259f5 100644 --- a/docs/source-1.0/spec/core/json-ast.rst +++ b/docs/source-1.0/spec/core/json-ast.rst @@ -312,7 +312,7 @@ one member, and a structure shape MAY omit the ``members`` property entirely if the structure contains no members. Structure and union member names MUST be case-insensitively unique across the -entire set of members. Each member name MUST adhere to the :token:`smithy:identifier` +entire set of members. Each member name MUST adhere to the :token:`smithy:Identifier` ABNF grammar. The following example defines a structure with one required and one optional @@ -403,7 +403,7 @@ shapes defined in JSON support the same properties as the Smithy IDL. - map of :ref:`shape ID ` to trait values - Traits to apply to the service * - rename - - map of :ref:`shape ID ` to ``string`` :token:`smithy:identifier` + - map of :ref:`shape ID ` to ``string`` :token:`smithy:Identifier` - Disambiguates shape name conflicts in the :ref:`service closure `. diff --git a/docs/source-1.0/spec/core/model-validation.rst b/docs/source-1.0/spec/core/model-validation.rst index adac2cd1e6e..71a35822806 100644 --- a/docs/source-1.0/spec/core/model-validation.rst +++ b/docs/source-1.0/spec/core/model-validation.rst @@ -445,7 +445,7 @@ Message templates ----------------- A ``messageTemplate`` is used to create more granular error messages. The -template consists of literal spans and :token:`selector context value ` +template consists of literal spans and :token:`selector context value ` templates (for example, ``@{id}``). A selector context value MAY be escaped by placing a ``@`` before a ``@`` character (for example, ``@@`` expands to ``@``). ``@`` characters in the message template that are not escaped MUST diff --git a/docs/source-1.0/spec/core/model.rst b/docs/source-1.0/spec/core/model.rst index ccd9f2ca6ae..d184f61da76 100644 --- a/docs/source-1.0/spec/core/model.rst +++ b/docs/source-1.0/spec/core/model.rst @@ -220,14 +220,14 @@ Namespace model file, while the JSON AST representation supports zero or more namespaces per model file. Absolute shape ID - An :dfn:`absolute shape ID` starts with a :token:`smithy:namespace` name, + An :dfn:`absolute shape ID` starts with a :token:`smithy:Namespace` name, followed by "``#``", followed by a *relative shape ID*. All shape IDs in the semantic model MUST be absolute. For example, ``smithy.example#Foo`` and ``smithy.example#Foo$bar`` are absolute shape IDs. Relative shape ID - A :dfn:`relative shape ID` contains a :token:`shape name ` - and an optional :token:`member name `. The shape name and + A :dfn:`relative shape ID` contains a :token:`shape name ` + and an optional :token:`member name `. The shape name and member name are separated by the "``$``" symbol if a member name is present. For example, ``Foo`` and ``Foo$bar`` are relative shape IDs. Root shape ID @@ -239,14 +239,14 @@ Root shape ID Shape IDs are formally defined by the following ABNF: .. productionlist:: smithy - shape_id :`root_shape_id` [`shape_id_member`] - root_shape_id :`absolute_root_shape_id` / `identifier` - absolute_root_shape_id :`namespace` "#" `identifier` - namespace :`identifier` *("." `identifier`) - identifier :identifier_start *identifier_chars - identifier_start :*"_" ALPHA - identifier_chars :ALPHA / DIGIT / "_" - shape_id_member :"$" `identifier` + ShapeId :`RootShapeId` [`ShapeIdMember`] + RootShapeId :`AbsoluteRootShapeId` / `Identifier` + AbsoluteRootShapeId :`Namespace` "#" `Identifier` + Namespace :`Identifier` *("." `Identifier`) + Identifier :`IdentifierStart` *`IdentifierChars` + IdentifierStart :*"_" ALPHA + IdentifierChars :ALPHA / DIGIT / "_" + ShapeIdMember :"$" `Identifier` .. rubric:: Best practices for defining shape names @@ -1134,7 +1134,7 @@ The service shape supports the following properties: contained in the service, and map values are the disambiguated shape names to use in the context of the service. Each given shape ID MUST reference a shape contained in the closure of the service. Each given - map value MUST match the :token:`smithy:identifier` production used for + map value MUST match the :token:`smithy:Identifier` production used for shape IDs. Renaming a shape *does not* give the shape a new shape ID. * No renamed shape name can case-insensitively match any other renamed @@ -2209,7 +2209,7 @@ An instance of a trait applied to a shape is called an *applied trait*. Only a single instance of a trait can be applied to a shape. The way in which a trait is applied to a shape depends on the model file representation. -Traits are applied to shapes in the IDL using :token:`smithy:trait_statements` that +Traits are applied to shapes in the IDL using :token:`smithy:TraitStatements` that immediately precede a shape. The following example applies the :ref:`length-trait` and :ref:`documentation-trait` to ``MyString``: @@ -2261,7 +2261,7 @@ Applying traits externally Both the IDL and JSON AST model representations allow traits to be applied to shapes outside of a shape's definition. This is done using an -:token:`apply ` statement in the IDL, or the +:token:`apply ` statement in the IDL, or the :ref:`apply ` type in the JSON AST. For example, this can be useful to allow different teams within the same organization to independently own different facets of a model; a service team could own the model that @@ -2370,7 +2370,7 @@ Trait node values The value provided for a trait MUST be compatible with the ``shape`` of the trait. The following table defines each shape type that is available to target from traits and how their values are defined in -:token:`node ` values. +:token:`node ` values. .. list-table:: :header-rows: 1 diff --git a/docs/source-1.0/spec/core/selectors.rst b/docs/source-1.0/spec/core/selectors.rst index f2b847cb00c..b3e21f523f7 100644 --- a/docs/source-1.0/spec/core/selectors.rst +++ b/docs/source-1.0/spec/core/selectors.rst @@ -172,7 +172,7 @@ contains a non-empty ``tags`` list. Attribute comparison -------------------- -An attribute selector with a :token:`comparator ` +An attribute selector with a :token:`comparator ` checks for the existence of an attribute and compares the resolved attribute value to a comma separated list of possible values. The resolved attribute value on the left hand side of the comparator MUST @@ -191,7 +191,7 @@ There are three kinds of comparators: String comparators ------------------ -:token:`String comparators ` are used to compare +:token:`String comparators ` are used to compare the string representation of values. Attributes that do not have a string representation are treated as an empty string when these comparisons are performed. @@ -288,7 +288,7 @@ Numeric comparators ------------------- Relative comparators only match if both values being compared contain valid -:token:`smithy:number` productions when converted to a string. +:token:`smithy:Number` productions when converted to a string. .. list-table:: :header-rows: 1 @@ -396,7 +396,7 @@ The ``id`` attribute can be used as an object, and it supports the following properties. ``namespace`` - Gets the :token:`smithy:namespace` part of a shape ID. + Gets the :token:`smithy:Namespace` part of a shape ID. The following selector matches shapes in the ``foo.baz`` namespace: @@ -548,7 +548,7 @@ to a shape. The ``trait`` attribute supports the following properties: [trait|deprecated] - Traits are converted to their serialized :token:`node ` form + Traits are converted to their serialized :token:`node ` form when matching against their values. Only string, boolean, and numeric values can be compared using a :ref:`string comparator `. Boolean values are converted to "true" or "false". Numeric values are @@ -874,7 +874,7 @@ the comparator are projections. Scoped attribute selectors ========================== -A :token:`scoped attribute selector ` is similar to an +A :token:`scoped attribute selector ` is similar to an attribute selector, but it allows multiple complex comparisons to be made against a scoped attribute. @@ -884,8 +884,8 @@ Context values The first part of a scoped attribute selector is the attribute that is scoped for the expression, followed by ``:``. The scoped attribute is accessed using -a :token:`context value ` in the form of -``@{`` :token:`smithy:identifier` ``}``. +a :token:`context value ` in the form of +``@{`` :token:`smithy:Identifier` ``}``. In the following selector, the ``trait|range`` attribute is used as the scoped attribute of the expression, and the selector matches shapes marked with @@ -997,7 +997,7 @@ a shape. Forward undirected neighbor ---------------------------- -A :token:`forward undirected neighbor ` +A :token:`forward undirected neighbor ` (``>``) yields every shape that is connected to the current shape. For example, the following selector matches the key and value members of every map: @@ -1026,7 +1026,7 @@ relationships of each operation: operation > * -A forward directed edge traversal is applied using :token:`selectors:selector_forward_directed_neighbor` +A forward directed edge traversal is applied using :token:`selectors:SelectorForwardDirectedNeighbor` (``-[X, Y, Z]->``). The following selector matches all structure shapes referenced as operation ``input`` or ``output``. @@ -1482,7 +1482,7 @@ results that are computed multiples times in a selector or for capturing information about the current shape that is referenced later in a selector after traversing neighbors. -A variable is set using a :token:`selectors:selector_variable_set` expression. +A variable is set using a :token:`selectors:SelectorVariableSet` expression. Variables can be reassigned without error. The following selector defines a variable named ``foo`` that sets the @@ -1492,7 +1492,7 @@ variable to the result of applying the ``*`` selector to the current shape. $foo(*) -A variable is retrieved by name using a :token:`selectors:selector_variable_get` +A variable is retrieved by name using a :token:`selectors:SelectorVariableGet` expression. Retrieving a variable yields the set of shapes stored in the variable. Attempting to get a variable that does not exist yields no shapes. @@ -1596,55 +1596,55 @@ Selectors are defined by the following ABNF_ grammar. changing the semantics of a selector. .. productionlist:: selectors - selector :`selector_expression` *(`selector_expression`) - selector_expression :`selector_shape_types` - :/ `selector_attr` - :/ `selector_scoped_attr` - :/ `selector_function` - :/ `selector_forward_undirected_neighbor` - :/ `selector_reverse_undirected_neighbor` - :/ `selector_forward_directed_neighbor` - :/ `selector_reverse_directed_neighbor` - :/ `selector_forward_recursive_neighbor` - :/ `selector_variable_set` - :/ `selector_variable_get` - selector_shape_types :"*" / `smithy:identifier` - selector_forward_undirected_neighbor :">" - selector_reverse_undirected_neighbor :"<" - selector_forward_directed_neighbor :"-[" `selector_directed_relationships` "]->" - selector_reverse_directed_neighbor :"<-[" selector_directed_relationships "]-" - selector_directed_relationships :`smithy:identifier` *("," `smithy:identifier`) - selector_forward_recursive_neighbor :"~>" - selector_attr :"[" `selector_key` [selector_attr_comparison] "]" - selector_attr_comparison :`selector_comparator` `selector_attr_values` ["i"] - selector_key :`smithy:identifier` ["|" `selector_path`] - selector_path :`selector_path_segment` *("|" `selector_path_segment`) - selector_path_segment :`selector_value` / `selector_function_property` - selector_value :`selector_text` / `smithy:number` / `smithy:root_shape_id` - selector_function_property :"(" `smithy:identifier` ")" - selector_attr_values :`selector_value` *("," `selector_value`) - selector_comparator :`selector_string_comparator` - :/ `selector_numeric_comparator` - :/ `selector_projection_comparator` - selector_string_comparator :"^=" / "$=" / "*=" / "!=" / "=" / "?=" - selector_numeric_comparator :">=" / ">" / "<=" / "<" - selector_projection_comparator :"{=}" / "{!=}" / "{<}" / "{<<}" - selector_absolute_root_shape_id :`smithy:namespace` "#" `smithy:identifier` - selector_scoped_attr :"[@" [`selector_key`] ":" `selector_scoped_assertions` "]" - selector_scoped_assertions :`selector_scoped_assertion` *("&&" `selector_scoped_assertion`) - selector_scoped_assertion :`selector_scoped_value` `selector_comparator` `selector_scoped_values` ["i"] - selector_scoped_value :`selector_value` / `selector_context_value` - selector_context_value :"@{" `selector_path` "}" - selector_scoped_values :`selector_scoped_value` *("," `selector_scoped_value`) - selector_function :":" `smithy:identifier` "(" `selector_function_args` ")" - selector_function_args :`selector` *("," `selector`) - selector_text :`selector_single_quoted_text` / `selector_double_quoted_text` - selector_single_quoted_text :"'" 1*`selector_single_quoted_char` "'" - selector_double_quoted_text :DQUOTE 1*`selector_double_quoted_char` DQUOTE - selector_single_quoted_char :%x20-26 / %x28-5B / %x5D-10FFFF ; Excludes (') - selector_double_quoted_char :%x20-21 / %x23-5B / %x5D-10FFFF ; Excludes (") - selector_variable_set :"$" `smithy:identifier` "(" selector ")" - selector_variable_get :"${" `smithy:identifier` "}" + Selector :`SelectorExpression` *(`SelectorExpression`) + SelectorExpression :`SelectorShapeTypes` + :/ `SelectorAttr` + :/ `SelectorScopedAttr` + :/ `SelectorFunction` + :/ `SelectorForwardUndirectedNeighbor` + :/ `SelectorReverseUndirectedNeighbor` + :/ `SelectorForwardDirectedNeighbor` + :/ `SelectorForwardRecursiveNeighbor` + :/ `SelectorReverseDirectedNeighbor` + :/ `SelectorVariableSet` + :/ `SelectorVariableGet` + SelectorShapeTypes :"*" / `smithy:Identifier` + SelectorForwardUndirectedNeighbor :">" + SelectorReverseUndirectedNeighbor :"<" + SelectorForwardDirectedNeighbor :"-[" `SelectorDirectedRelationships` "]->" + SelectorReverseDirectedNeighbor :"<-[" `SelectorDirectedRelationships` "]-" + SelectorDirectedRelationships :`smithy:Identifier` *("," `smithy:Identifier`) + SelectorForwardRecursiveNeighbor :"~>" + SelectorAttr :"[" `SelectorKey` [`SelectorAttrComparison`] "]" + SelectorAttrComparison :`SelectorComparator` `SelectorAttrValues` ["i"] + SelectorKey :`smithy:Identifier` ["|" `SelectorPath`] + SelectorPath :`SelectorPathSegment` *("|" `SelectorPathSegment`) + SelectorPathSegment :`SelectorValue` / `SelectorFunctionProperty` + SelectorValue :`SelectorText` / `smithy:Number` / `smithy:RootShapeId` + SelectorFunctionProperty :"(" `smithy:Identifier` ")" + SelectorAttrValues :`SelectorValue` *("," `SelectorValue`) + SelectorComparator :`SelectorStringComparator` + :/ `SelectorNumericComparator` + :/ `SelectorProjectionComparator` + SelectorStringComparator :"^=" / "$=" / "*=" / "!=" / "=" / "?=" + SelectorNumericComparator :">=" / ">" / "<=" / "<" + SelectorProjectionComparator :"{=}" / "{!=}" / "{<}" / "{<<}" + SelectorAbsoluteRootShapeId :`smithy:Namespace` "#" `smithy:Identifier` + SelectorScopedAttr :"[@" [`SelectorKey`] ":" `SelectorScopedAssertions` "]" + SelectorScopedAssertions :`SelectorScopedAssertion` *("&&" `SelectorScopedAssertion`) + SelectorScopedAssertion :`SelectorScopedValue` `SelectorComparator` `SelectorScopedValues` ["i"] + SelectorScopedValue :`SelectorValue` / `SelectorContextValue` + SelectorContextValue :"@{" `SelectorPath` "}" + SelectorScopedValues :`SelectorScopedValue` *("," `SelectorScopedValue`) + SelectorFunction :":" `smithy:Identifier` "(" `SelectorFunctionArgs` ")" + SelectorFunctionArgs :`Selector` *("," `Selector`) + SelectorText :`SelectorSingleQuotedText` / `SelectorDoubleQuotedText` + SelectorSingleQuotedText :"'" 1*`SelectorSingleQuotedChar` "'" + SelectorDoubleQuotedText :DQUOTE 1*`SelectorDoubleQuotedChar` DQUOTE + SelectorSingleQuotedChar :%x20-26 / %x28-5B / %x5D-10FFFF ; Excludes (') + SelectorDoubleQuotedChar :%x20-21 / %x23-5B / %x5D-10FFFF ; Excludes (") + SelectorVariableSet :"$" `smithy:Identifier` "(" `Selector` ")" + SelectorVariableGet :"${" `smithy:Identifier` "}" .. _ABNF: https://tools.ietf.org/html/rfc5234 .. _set: https://en.wikipedia.org/wiki/Set_(abstract_data_type) diff --git a/docs/source-1.0/spec/core/xml-traits.rst b/docs/source-1.0/spec/core/xml-traits.rst index 15e8aaf7476..b678f6fd6ba 100644 --- a/docs/source-1.0/spec/core/xml-traits.rst +++ b/docs/source-1.0/spec/core/xml-traits.rst @@ -862,11 +862,11 @@ Trait selector *A structure, union, or member* Value type - ``string`` value that MUST adhere to the :token:`smithy:xml_name` ABNF production: + ``string`` value that MUST adhere to the :token:`smithy:XmlName` ABNF production: .. productionlist:: smithy - xml_name :xml_identifier / (xml_identifier ":" xml_identifier) - xml_identifier :(ALPHA / "_") *(ALPHA / DIGIT / "-" / "_") + XmlName :`XmlIdentifier` / (`XmlIdentifier` ":" `XmlIdentifier`) + XmlIdentifier :(ALPHA / "_") *(ALPHA / DIGIT / "-" / "_") By default, structure properties are serialized in attributes or nested elements using the same name as the structure member name. Given the following: @@ -966,7 +966,7 @@ The ``xmlNamespace`` trait is a structure that contains the following members: - ``string`` value - The `namespace prefix`_ for elements from this namespace. Values provides for ``prefix`` property MUST adhere to the - :token:`smithy:xml_identifier` production. + :token:`smithy:XmlIdentifier` production. Given the following: diff --git a/docs/source-1.0/spec/http-protocol-compliance-tests.rst b/docs/source-1.0/spec/http-protocol-compliance-tests.rst index f74656c04ed..2f79dd968b7 100644 --- a/docs/source-1.0/spec/http-protocol-compliance-tests.rst +++ b/docs/source-1.0/spec/http-protocol-compliance-tests.rst @@ -90,7 +90,7 @@ that support the following members: - **Required**. The identifier of the test case. This identifier can be used by protocol test implementations to filter out unsupported test cases by ID, to generate test case names, etc. The provided - ``id`` MUST match Smithy's :token:`smithy:identifier` ABNF. No two + ``id`` MUST match Smithy's :token:`smithy:Identifier` ABNF. No two ``httpRequestTests`` test cases can share the same ID. * - protocol - shape ID @@ -344,7 +344,7 @@ structures that support the following members: - **Required**. The identifier of the test case. This identifier can be used by protocol test implementations to filter out unsupported test cases by ID, to generate test case names, etc. The provided - ``id`` MUST match Smithy's :token:`smithy:identifier` ABNF. No two + ``id`` MUST match Smithy's :token:`smithy:Identifier` ABNF. No two ``httpResponseTests`` test cases can share the same ID. * - protocol - ``string`` @@ -594,7 +594,7 @@ The ``httpMalformedRequestTests`` trait is a list of - **Required**. The identifier of the test case. This identifier can be used by protocol test implementations to filter out unsupported test cases by ID, to generate test case names, etc. The provided - ``id`` MUST match Smithy's :token:`smithy:identifier` ABNF. No two + ``id`` MUST match Smithy's :token:`smithy:Identifier` ABNF. No two ``httpMalformedRequestTests`` test cases can share the same ID. * - protocol - shape ID diff --git a/docs/source-2.0/spec/idl.rst b/docs/source-2.0/spec/idl.rst index 998ae66371a..b9d042c3ee2 100644 --- a/docs/source-2.0/spec/idl.rst +++ b/docs/source-2.0/spec/idl.rst @@ -50,7 +50,7 @@ The following example defines a model file with each section: .. code-block:: smithy { - "smithy": "2.0", + "smithy": "2", "metadata": { "foo": "bar" }, @@ -193,13 +193,13 @@ string support defined in `RFC 5234 `_. ValueAssignment :*`SP` "=" *`SP` `NodeValue` `BR` ListStatement :%s"list" `SP` `Identifier` [`Mixins`] *`WS` `ListMembers` ListMembers :"{" *`WS` `ListMember` *`WS` "}" - ListMember :[TraitStatements] (`ElidedListMember` / `ExplicitListMember`) + ListMember :`TraitStatements` (`ElidedListMember` / `ExplicitListMember`) ElidedListMember :%s"$member" ExplicitListMember :%s"member" *`SP` ":" *`SP` `ShapeId` MapStatement :%s"map" `SP` `Identifier` [`Mixins`] *`WS` `MapMembers` MapMembers :"{" *`WS` `MapKey` `BR` `MapValue` *`WS` "}" - MapKey :[TraitStatements] (`ElidedMapKey` / `ExplicitMapKey`) - MapValue :[TraitStatements] (`ElidedMapValue` / `ExplicitMapValue`) + MapKey :`TraitStatements` (`ElidedMapKey` / `ExplicitMapKey`) + MapValue :`TraitStatements` (`ElidedMapValue` / `ExplicitMapValue`) ElidedMapKey :%s"$key" ExplicitMapKey :%s"key" *`SP` ":" *`SP` `ShapeId` ElidedMapValue :%s"$value" @@ -282,8 +282,9 @@ The :token:`control section ` of a model contains :token:`control statements ` that apply parser directives to a *specific IDL file*. Because control statements influence parsing, they MUST appear at the beginning of a file before any other statements and have -no effect on the :ref:`semantic model ` The following control -statements are currently supported: +no effect on the :ref:`semantic model `. + +The following control statements are currently supported: .. list-table:: :header-rows: 1 @@ -315,7 +316,7 @@ Version statement The Smithy specification is versioned using a ``major`` . ``minor`` versioning scheme. A version requirement is specified for a model file using -the ``$version`` control statement. When no version Number is specified in +the ``$version`` control statement. When no version number is specified in the IDL, an implementation SHOULD assume that the model can be loaded. Because this can lead to unexpected parsing errors, models SHOULD always include a version. @@ -345,21 +346,21 @@ support a version greater than or equal to ``2.0`` and less than ``3.0``: A minor version SHOULD be provided when a model depends on a feature released in a minor update of the specification. The following example sets the -version requirement of a file to ``2.0``, meaning that tooling MUST support a -version greater than or equal to ``2.0`` and less than ``3.0``: +version requirement of a file to ``2.1``, meaning that tooling MUST support a +version greater than or equal to ``2.1`` and less than ``3.0``: .. tab:: Smithy .. code-block:: smithy - $version: "2.0" + $version: "2.1" .. tab:: JSON .. code-block:: json { - "smithy": "2.0" + "smithy": "2.1" } .. rubric:: Version compatibility @@ -395,7 +396,7 @@ The following example defines metadata in the model: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "metadata": { "greeting": "hello", "stringList": ["a", "b", "c"] @@ -437,7 +438,7 @@ The following example defines a string shape named ``MyString`` in the .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyString": { "type": "string" @@ -589,7 +590,7 @@ The above model is equivalent to the following JSON AST model: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyList": { "type": "list", @@ -623,7 +624,7 @@ The above example is equivalent to the following incorrect JSON AST: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#Error": { "type": "structure", @@ -656,7 +657,7 @@ The above example is equivalent to the following JSON AST: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "metadata": { "String": "smithy.api#String" } @@ -712,7 +713,7 @@ The following example defines a ``string`` shape: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#String": { "type": "string" @@ -737,7 +738,7 @@ The following example defines an ``integer`` shape with a :ref:`range-trait`: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MaxResults": { "type": "integer", @@ -889,7 +890,7 @@ The following example defines a list with a string member from the .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyList": { "type": "list", @@ -920,7 +921,7 @@ Traits can be applied to the list shape and its member: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyList": { "type": "list", @@ -970,7 +971,7 @@ The following example defines a map of strings to integers: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "type": "map", "smithy.example#IntegerMap": { @@ -1007,7 +1008,7 @@ Traits can be applied to the map shape and its members: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#IntegerMap": { "type": "map", @@ -1067,7 +1068,7 @@ The following example defines a structure with two members: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyStructure": { "type": "structure", @@ -1108,7 +1109,7 @@ Traits can be applied to structure members: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyStructure": { "type": "structure", @@ -1184,7 +1185,7 @@ The following example defines a union shape with several members: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyUnion": { "type": "union", @@ -1238,7 +1239,7 @@ a resource named ``Model`` and an operation named ``PingService``: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#ModelRepository": { "type": "service", @@ -1288,7 +1289,7 @@ can potentially return the ``Unavailable`` or ``BadRequest`` .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#PingService": { "type": "operation", @@ -1445,7 +1446,7 @@ and defines a :ref:`read ` operation: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#Sprocket": { "type": "resource", @@ -1633,7 +1634,7 @@ is equivalent to the following JSON AST model: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyString": { "type": "string", @@ -1714,7 +1715,7 @@ The following example applies the :ref:`length-trait` and .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyString": { "type": "string", @@ -1803,7 +1804,7 @@ The following applications of the ``foo`` trait are equivalent: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#foo": { "type": "structure", @@ -1876,7 +1877,7 @@ The following example applies the :ref:`documentation-trait` to the .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyString": { "type": "apply", @@ -1908,7 +1909,7 @@ and :ref:`length-trait` to the ``smithy.example#MyString`` shape: .. code-block:: json { - "smithy": "2.0", + "smithy": "2", "shapes": { "smithy.example#MyString": { "type": "apply", @@ -2005,7 +2006,7 @@ The following examples define objects with zero, one, and two key value pairs: .. rubric:: Number node A node :token:`smithy:Number` contains numeric data. It is defined like a JSON -Number. The following examples define several ``Number`` values: +number. The following examples define several ``Number`` values: * ``0`` * ``0.0`` @@ -2184,7 +2185,7 @@ incidental whitespace using the following algorithm: [" Foo", " Baz", "", " ", " Bar", " "] 2. Compute the *common whitespace prefix* by iterating over each line, - counting the Number of leading spaces (" ") and taking the minimum count. + counting the number of leading spaces (" ") and taking the minimum count. Except for the last line of content, lines that are empty or consist wholly of whitespace are not considered. If the last line of content (that is, the line that contains the closing delimiter) appears on its own line, then diff --git a/docs/source-2.0/spec/protocol-traits.rst b/docs/source-2.0/spec/protocol-traits.rst index ad6d405774b..2b179e68f46 100644 --- a/docs/source-2.0/spec/protocol-traits.rst +++ b/docs/source-2.0/spec/protocol-traits.rst @@ -897,11 +897,11 @@ Trait selector *A structure, union, or member* Value type - ``string`` value that MUST adhere to the :token:`smithy:xml_name` ABNF production: + ``string`` value that MUST adhere to the :token:`smithy:XmlName` ABNF production: .. productionlist:: smithy - xml_name :xml_identifier / (xml_identifier ":" xml_identifier) - xml_identifier :(ALPHA / "_") *(ALPHA / DIGIT / "-" / "_") + XmlName :`XmlIdentifier` / (`XmlIdentifier`` ":" `XmlIdentifier``) + XmlIdentifier :(ALPHA / "_") *(ALPHA / DIGIT / "-" / "_") By default, structure properties are serialized in attributes or nested elements using the same name as the structure member name. Given the following: @@ -976,7 +976,7 @@ The ``xmlNamespace`` trait is a structure that contains the following members: - ``string`` value - The `namespace prefix`_ for elements from this namespace. Values provides for ``prefix`` property MUST adhere to the - :token:`smithy:xml_identifier` production. + :token:`smithy:XmlIdentifier` production. Given the following: diff --git a/docs/source-2.0/spec/selectors.rst b/docs/source-2.0/spec/selectors.rst index 1f3c8958607..b4f991f30da 100644 --- a/docs/source-2.0/spec/selectors.rst +++ b/docs/source-2.0/spec/selectors.rst @@ -1629,10 +1629,10 @@ Selectors are defined by the following ABNF_ grammar. SelectorForwardUndirectedNeighbor :">" SelectorReverseUndirectedNeighbor :"<" SelectorForwardDirectedNeighbor :"-[" `SelectorDirectedRelationships` "]->" - SelectorReverseDirectedNeighbor :"<-[" SelectorDirectedRelationships "]-" + SelectorReverseDirectedNeighbor :"<-[" `SelectorDirectedRelationships` "]-" SelectorDirectedRelationships :`smithy:Identifier` *("," `smithy:Identifier`) SelectorForwardRecursiveNeighbor :"~>" - SelectorAttr :"[" `SelectorKey` [SelectorAttrComparison] "]" + SelectorAttr :"[" `SelectorKey` [`SelectorAttrComparison`] "]" SelectorAttrComparison :`SelectorComparator` `SelectorAttrValues` ["i"] SelectorKey :`smithy:Identifier` ["|" `SelectorPath`] SelectorPath :`SelectorPathSegment` *("|" `SelectorPathSegment`) @@ -1660,7 +1660,7 @@ Selectors are defined by the following ABNF_ grammar. SelectorDoubleQuotedText :DQUOTE 1*`SelectorDoubleQuotedChar` DQUOTE SelectorSingleQuotedChar :%x20-26 / %x28-5B / %x5D-10FFFF ; Excludes (') SelectorDoubleQuotedChar :%x20-21 / %x23-5B / %x5D-10FFFF ; Excludes (") - SelectorVariableSet :"$" `smithy:Identifier` "(" selector ")" + SelectorVariableSet :"$" `smithy:Identifier` "(" `Selector` ")" SelectorVariableGet :"${" `smithy:Identifier` "}" .. _ABNF: https://tools.ietf.org/html/rfc5234