From fa4ef08e69a37c08b819c509030a7a31cf4df629 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Thu, 22 Jan 2026 14:43:02 +0100 Subject: [PATCH 1/3] Update sphinx to 9.x --- docs/landing-page/package-lock.json | 37 ++++++++++++++++++++--------- docs/pyproject.toml | 2 +- 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/landing-page/package-lock.json b/docs/landing-page/package-lock.json index 910588b9f1d..f79a4533b1b 100644 --- a/docs/landing-page/package-lock.json +++ b/docs/landing-page/package-lock.json @@ -108,6 +108,7 @@ "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@babel/code-frame": "^7.27.1", "@babel/generator": "^7.28.5", @@ -2688,8 +2689,7 @@ "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@types/babel__core": { "version": "7.20.5", @@ -2785,6 +2785,7 @@ "integrity": "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "undici-types": "~7.16.0" } @@ -2795,6 +2796,7 @@ "integrity": "sha512-Lpo8kgb/igvMIPeNV2rsYKTgaORYdO1XGVZ4Qz3akwOj0ySGYMPlQWa8BaLn0G63D1aSaAQ5ldR06wCpChQCjA==", "devOptional": true, "license": "MIT", + "peer": true, "dependencies": { "csstype": "^3.2.2" } @@ -2805,6 +2807,7 @@ "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==", "devOptional": true, "license": "MIT", + "peer": true, "peerDependencies": { "@types/react": "^19.2.0" } @@ -2861,6 +2864,7 @@ "integrity": "sha512-nm3cvFN9SqZGXjmw5bZ6cGmvJSyJPn0wU9gHAZZHDnZl2wF9PhHv78Xf06E0MaNk4zLVHL8hb2/c32XvyJOLQg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.53.1", "@typescript-eslint/types": "8.53.1", @@ -3207,6 +3211,7 @@ "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "dev": true, "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -3391,6 +3396,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.8.25", "caniuse-lite": "^1.0.30001754", @@ -3802,8 +3808,7 @@ "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz", "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/eastasianwidth": { "version": "0.2.0", @@ -3870,6 +3875,7 @@ "dev": true, "hasInstallScript": true, "license": "MIT", + "peer": true, "bin": { "esbuild": "bin/esbuild" }, @@ -3921,6 +3927,7 @@ "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", @@ -4475,6 +4482,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "@babel/runtime": "^7.28.4" }, @@ -5258,7 +5266,6 @@ "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", "dev": true, "license": "MIT", - "peer": true, "bin": { "lz-string": "bin/bin.js" } @@ -5648,6 +5655,7 @@ "integrity": "sha512-yEPsovQfpxYfgWNhCfECjG5AQaO+K3dp6XERmOepyPDVqcJm+bjyCVO3pmU+nAPe0N5dDvekfGezt/EIiRe1TA==", "dev": true, "license": "MIT", + "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -5664,7 +5672,6 @@ "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", @@ -5680,7 +5687,6 @@ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=8" } @@ -5691,7 +5697,6 @@ "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=10" }, @@ -5714,6 +5719,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.3.tgz", "integrity": "sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10.0" } @@ -5755,6 +5761,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.3.tgz", "integrity": "sha512-yELu4WmLPw5Mr/lmeEpox5rw3RETacE++JgHqQzd2dg+YbJuat3jH4ingc+WPZhxaoFzdv9y33G+F7Nl5O0GBg==", "license": "MIT", + "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -5794,8 +5801,7 @@ "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/react-refresh": { "version": "0.18.0", @@ -5990,6 +5996,7 @@ "integrity": "sha512-w8GmOxZfBmKknvdXU1sdM9NHcoQejwF/4mNgj2JuEEdRaHwwF12K7e9eXn1nLZ07ad+du76mkVsyeb2rKGllsA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@types/estree": "1.0.8" }, @@ -6146,6 +6153,7 @@ "integrity": "sha512-fIQnFtpksRRgHR1CO1onGX3djaog4qsW/c5U8arqYTkUEr2TaWpn05mIJDOBoPJFlOdqFrB4Ttv0PZJxV7avhw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@storybook/global": "^5.0.0", "@storybook/icons": "^2.0.1", @@ -6376,7 +6384,8 @@ "version": "4.1.18", "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz", "integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==", - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/tailwindcss-animate": { "version": "1.0.7", @@ -6448,6 +6457,7 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -6539,6 +6549,7 @@ "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "~0.27.0", "get-tsconfig": "^4.7.5" @@ -6571,6 +6582,7 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", + "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -6747,6 +6759,7 @@ "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.27.0", "fdir": "^6.5.0", @@ -6840,6 +6853,7 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -7074,6 +7088,7 @@ "integrity": "sha512-AvvthqfqrAhNH9dnfmrfKzX5upOdjUVJYFqNSlkmGf64gRaTzlPwz99IHYnVs28qYAybvAlBV+H7pn0saFY4Ig==", "dev": true, "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 1b236153e6b..a600191247f 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -9,7 +9,7 @@ module-root = "" name = "smithy" version = "1.0.0" dependencies = [ - "sphinx==8.2.3", + "sphinx==9.1.0", "pygments==2.19.2", "furo==2025.12.19", From bb86e646290ea2c03fcfba404dc0649d4b6cc66b Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 23 Jan 2026 12:43:42 +0100 Subject: [PATCH 2/3] Update 1.0 docs to use new tab library At some point in the migration to 2.0 we changed the tab library we use for Sphinx. At the time we didn't update the 1.0 docs to also use that library, and just left a todo to get rid of it. This gets rid of the old library. This was done now because it was causing some issues with an upgrade to sphinx 9. --- docs/pyproject.toml | 3 - docs/source-1.0/conf.py | 4 +- .../guides/building-models/build-config.rst | 1018 +++++----- .../guides/building-models/gradle-plugin.rst | 276 ++- docs/source-1.0/guides/model-linters.rst | 12 +- .../source-1.0/spec/aws/amazon-apigateway.rst | 142 +- docs/source-1.0/spec/aws/aws-auth.rst | 142 +- .../spec/aws/aws-cloudformation.rst | 50 +- docs/source-1.0/spec/aws/aws-core.rst | 645 +++--- .../spec/aws/aws-ec2-query-protocol.rst | 106 +- docs/source-1.0/spec/aws/aws-iam.rst | 603 +++--- .../spec/aws/aws-json-1_0-protocol.rst | 45 +- .../spec/aws/aws-json-1_1-protocol.rst | 45 +- .../spec/aws/aws-query-protocol.rst | 130 +- .../spec/aws/aws-restjson1-protocol.rst | 45 +- .../spec/aws/aws-restxml-protocol.rst | 45 +- docs/source-1.0/spec/core/auth-traits.rst | 318 +-- docs/source-1.0/spec/core/behavior-traits.rst | 121 +- .../spec/core/constraint-traits.rst | 574 +++--- .../spec/core/documentation-traits.rst | 324 ++-- docs/source-1.0/spec/core/endpoint-traits.rst | 424 ++-- docs/source-1.0/spec/core/http-traits.rst | 28 +- docs/source-1.0/spec/core/idl.rst | 1154 +++++------ docs/source-1.0/spec/core/index.rst | 79 +- .../source-1.0/spec/core/model-validation.rst | 12 +- docs/source-1.0/spec/core/model.rst | 1727 +++++++++-------- docs/source-1.0/spec/core/protocol-traits.rst | 217 ++- docs/source-1.0/spec/core/resource-traits.rst | 133 +- docs/source-1.0/spec/core/stream-traits.rst | 318 +-- .../spec/core/type-refinement-traits.rst | 189 +- docs/source-1.0/spec/core/xml-traits.rst | 697 +++---- .../spec/http-protocol-compliance-tests.rst | 141 +- 32 files changed, 4991 insertions(+), 4776 deletions(-) diff --git a/docs/pyproject.toml b/docs/pyproject.toml index a600191247f..f245751cd57 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -17,9 +17,6 @@ dependencies = [ "sphinx-inline-tabs==2025.12.21.14", "Sphinx-Substitution-Extensions==2026.1.12", - # Used by old docs - "sphinx-tabs>=3.4.7", - "sphinx_copybutton==0.5.2", "sphinx-autobuild==2025.8.25", diff --git a/docs/source-1.0/conf.py b/docs/source-1.0/conf.py index 6547f0bc0d0..7c2726cea8c 100644 --- a/docs/source-1.0/conf.py +++ b/docs/source-1.0/conf.py @@ -3,8 +3,8 @@ with open(shared_config) as file: exec(file.read()) -# TODO: Migrate to use the 2.0 tabs library. -extensions.append("sphinx_tabs.tabs") +# Add sphinx-inline-tabs extension for converted tabs +extensions.append("sphinx_inline_tabs") # Place version specific overrides after here. html_title = "Smithy 1.0" diff --git a/docs/source-1.0/guides/building-models/build-config.rst b/docs/source-1.0/guides/building-models/build-config.rst index 70250c751ed..7478cb0d9b6 100644 --- a/docs/source-1.0/guides/building-models/build-config.rst +++ b/docs/source-1.0/guides/building-models/build-config.rst @@ -57,49 +57,47 @@ The configuration file accepts the following properties: The following is an example ``smithy-build.json`` configuration: -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "outputDirectory": "build/output", - "imports": ["foo.json", "some/directory"], - "projections": { - "my-abstract-projection": { - "abstract": true - }, - "projection-name": { - "imports": ["projection-specific-imports/"], - "transforms": [ - { - "name": "excludeShapesByTag", - "args": { - "tags": ["internal", "beta", "..."] - } - }, - { - "name": "excludeShapesByTrait", - "args": { - "traits": ["internal"] - } - } - ], - "plugins": { - "plugin-name": { - "plugin-config": "value" - }, - "...": {} - } - } - }, - "plugins": { - "plugin-name": { - "plugin-config": "value" - }, - "...": {} - } - } +.. code-block:: json + + { + "version": "1.0", + "outputDirectory": "build/output", + "imports": ["foo.json", "some/directory"], + "projections": { + "my-abstract-projection": { + "abstract": true + }, + "projection-name": { + "imports": ["projection-specific-imports/"], + "transforms": [ + { + "name": "excludeShapesByTag", + "args": { + "tags": ["internal", "beta", "..."] + } + }, + { + "name": "excludeShapesByTrait", + "args": { + "traits": ["internal"] + } + } + ], + "plugins": { + "plugin-name": { + "plugin-config": "value" + }, + "...": {} + } + } + }, + "plugins": { + "plugin-name": { + "plugin-config": "value" + }, + "...": {} + } + } .. _projections: @@ -218,34 +216,32 @@ Applies the transforms defined in the given projection names. referenced projections are applied in the order provided. No cycles are allowed in ``apply``. -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "my-abstract-projection": { - "abstract": true, - "transforms": [ - {"name": "foo"} - ] - }, - "projection-name": { - "imports": ["projection-specific-imports/"], - "transforms": [ - {"name": "baz"}, - { - "name": "apply", - "args": { - "projections": ["my-abstract-projection"] - } - }, - {"name": "bar"} - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "my-abstract-projection": { + "abstract": true, + "transforms": [ + {"name": "foo"} + ] + }, + "projection-name": { + "imports": ["projection-specific-imports/"], + "transforms": [ + {"name": "baz"}, + { + "name": "apply", + "args": { + "projections": ["my-abstract-projection"] + } + }, + {"name": "bar"} + ] + } + } + } .. _changeStringEnumsToEnumShapes: @@ -372,25 +368,23 @@ the :ref:`tags trait `. - ``[string]`` - The set of tags that causes shapes to be removed. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeShapesByTag", - "args": { - "tags": ["foo", "baz"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeShapesByTag", + "args": { + "tags": ["foo", "baz"] + } + } + ] + } + } + } .. note:: @@ -418,25 +412,23 @@ Removes shapes if they are marked with one or more specific traits. shape IDs are assumed to be in the ``smithy.api`` :ref:`prelude ` namespace. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeShapesByTrait", - "args": { - "traits": ["internal"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeShapesByTrait", + "args": { + "traits": ["internal"] + } + } + ] + } + } + } .. _includeShapesByTag-transform: @@ -458,25 +450,23 @@ via the :ref:`tags trait `. - ``[string]`` - The set of tags that causes shapes to be retained in the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeShapesByTag", - "args": { - "tags": ["foo", "baz"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeShapesByTag", + "args": { + "tags": ["foo", "baz"] + } + } + ] + } + } + } .. note:: @@ -502,25 +492,23 @@ Note that this does not filter out traits based on namespaces. - ``[string]`` - The namespaces to include in the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeNamespaces", - "args": { - "namespaces": ["com.foo.bar", "my.api"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeNamespaces", + "args": { + "namespaces": ["com.foo.bar", "my.api"] + } + } + ] + } + } + } .. note:: @@ -547,25 +535,23 @@ shape IDs. - The service shape IDs to include in the model. Each entry MUST be a valid service shape ID. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeServices", - "args": { - "services": ["my.api#MyService"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeServices", + "args": { + "services": ["my.api#MyService"] + } + } + ] + } + } + } .. _excludeTags-transform: @@ -587,25 +573,23 @@ provided ``tags``. - ``[string]`` - The set of tags that are removed from the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeTags", - "args": { - "tags": ["tagA", "tagB"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeTags", + "args": { + "tags": ["tagA", "tagB"] + } + } + ] + } + } + } .. _excludeTraits-transform: @@ -635,50 +619,46 @@ orphaned shapes. shape IDs that are relative are assumed to be part of the ``smithy.api`` prelude namespace. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeTraits", - "args": { - "traits": ["since", "com.foo#customTrait"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeTraits", + "args": { + "traits": ["since", "com.foo#customTrait"] + } + } + ] + } + } + } You can exclude all of the traits in a namespace by ending one of the arguments with "#". For example, the following configuration excludes all traits in the "example.foo" namespace: -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeTraits", - "args": { - "traits": ["example.foo#"] - } - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeTraits", + "args": { + "traits": ["example.foo#"] + } + } + ] + } + } + } .. _excludeTraitsByTag-transform: @@ -705,25 +685,23 @@ orphaned shapes. - ``[string]`` - The list of tags that, if present, cause a trait to be removed. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeTraitsByTag", - "args": { - "tags": ["internal"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeTraitsByTag", + "args": { + "tags": ["internal"] + } + } + ] + } + } + } .. note:: @@ -800,139 +778,127 @@ and the :ref:`suppress-trait`. The following example removes suppressions that have no effect in the ``exampleProjection``: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "removeUnused": true - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "removeUnused": true + } + } + ] + } + } + } The following example removes suppressions from metadata that refer to deny-listed namespaces: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "namespaceDenyList": ["com.internal"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "namespaceDenyList": ["com.internal"] + } + } + ] + } + } + } The following example removes suppressions from metadata that refer to namespaces outside of the allow-listed namespaces: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "namespaceAllowList": ["com.external"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "namespaceAllowList": ["com.external"] + } + } + ] + } + } + } The following example removes suppressions that refer to deny-listed event IDs: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "eventIdDenyList": ["MyInternalValidator"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "eventIdDenyList": ["MyInternalValidator"] + } + } + ] + } + } + } The following example removes suppressions that refer to event IDs outside of the event ID allow list: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "eventIdAllowList": ["A", "B", "C"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "eventIdAllowList": ["A", "B", "C"] + } + } + ] + } + } + } The following example removes the ``reason`` property from metadata suppressions: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "filterSuppressions", - "args": { - "removeReasons": true - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "filterSuppressions", + "args": { + "removeReasons": true + } + } + ] + } + } + } .. _includeTags-transform: @@ -954,25 +920,23 @@ list. - ``[string]`` - The set of tags that are retained in the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeTags", - "args": { - "tags": ["foo", "baz"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeTags", + "args": { + "tags": ["foo", "baz"] + } + } + ] + } + } + } .. _includeTraits-transform: @@ -1002,50 +966,46 @@ orphaned shapes. relative are assumed to be part of the ``smithy.api`` prelude namespace. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeTraits", - "args": { - "traits": ["sensitive", "com.foo.baz#customTrait"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeTraits", + "args": { + "traits": ["sensitive", "com.foo.baz#customTrait"] + } + } + ] + } + } + } You can include all of the traits in a namespace by ending one of the arguments with "#". For example, the following configuration includes all traits in the "smithy.api" namespace: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeTraits", - "args": { - "traits": ["smithy.api#"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeTraits", + "args": { + "traits": ["smithy.api#"] + } + } + ] + } + } + } .. _includeTraitsByTag-transform: @@ -1073,25 +1033,23 @@ orphaned shapes. - The list of tags that must be present for a trait to be included in the filtered model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeTraitsByTag", - "args": { - "tags": ["public"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeTraitsByTag", + "args": { + "tags": ["public"] + } + } + ] + } + } + } .. note:: @@ -1117,25 +1075,23 @@ key is in the provided ``keys`` list. - ``[string]`` - The set of metadata keys that are removed from the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "excludeMetadata", - "args": { - "keys": ["suppressions"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "excludeMetadata", + "args": { + "keys": ["suppressions"] + } + } + ] + } + } + } .. _includeMetadata-transform: @@ -1157,25 +1113,23 @@ key is not in the provided ``keys`` list. - ``[string]`` - The set of metadata keys that are retained in the model. -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "includeMetadata", - "args": { - "keys": ["authors"] - } - } - ] - } - } - } + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "includeMetadata", + "args": { + "keys": ["authors"] + } + } + ] + } + } + } .. _flattenNamespaces: @@ -1217,27 +1171,25 @@ them through the service shape's ``rename`` property. Shapes tagged with long as they don't conflict with a shape within the :ref:`service closure `. -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "flattenNamespaces", - "args": { - "namespace": "ns.foo", - "service": "ns.bar#MyService", - "includeTagged": ["baz", "qux"] - } - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "flattenNamespaces", + "args": { + "namespace": "ns.foo", + "service": "ns.bar#MyService", + "includeTagged": ["baz", "qux"] + } + } + ] + } + } + } .. _removeTraitDefinitions-transform: @@ -1266,28 +1218,26 @@ definition and adding the list of export tags in the ``exportTagged`` argument. The following example removes trait definitions but keeps the instances of the trait intact on shapes in the model: -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "removeTraitDefinitions", - "args": { - "exportTagged": [ - "export-tag1", - "another-export-tag" - ] - } - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "removeTraitDefinitions", + "args": { + "exportTagged": [ + "export-tag1", + "another-export-tag" + ] + } + } + ] + } + } + } .. _removeUnusedShapes-transform: @@ -1317,28 +1267,26 @@ the ``exportTagged`` argument. The following example removes shapes that are not connected to any service, but keeps the shape if it has any of the provided tags: -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "removeUnusedShapes", - "args": { - "exportTagged": [ - "export-tag1", - "another-export-tag" - ] - } - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "removeUnusedShapes", + "args": { + "exportTagged": [ + "export-tag1", + "another-export-tag" + ] + } + } + ] + } + } + } .. _renameShapes-transform: @@ -1364,27 +1312,25 @@ shapes that are being renamed. The following example renames the ``ns.foo#Bar`` shape to ``ns.foo#Baz``. Any references to ``ns.foo#Bar`` on other shapes will also be updated. -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "exampleProjection": { - "transforms": [ - { - "name": "renameShapes", - "args": { - "renamed": { - "ns.foo#Bar": "ns.foo#Baz" - } - } - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "exampleProjection": { + "transforms": [ + { + "name": "renameShapes", + "args": { + "renamed": { + "ns.foo#Bar": "ns.foo#Baz" + } + } + } + ] + } + } + } .. _build_envars: diff --git a/docs/source-1.0/guides/building-models/gradle-plugin.rst b/docs/source-1.0/guides/building-models/gradle-plugin.rst index 151368b68bf..2810b46a8ec 100644 --- a/docs/source-1.0/guides/building-models/gradle-plugin.rst +++ b/docs/source-1.0/guides/building-models/gradle-plugin.rst @@ -16,13 +16,11 @@ Installation The Smithy Gradle plugin is applied using the ``software.amazon.smithy`` plugin. The following example configures a project to use the Smithy Gradle plugin: -.. tabs:: +.. code-block:: kotlin - .. code-tab:: kotlin - - plugins { - id("software.amazon.smithy").version("0.6.0") - } + plugins { + id("software.amazon.smithy").version("0.6.0") + } .. _smithy-model-sources: @@ -66,13 +64,11 @@ Smithy extension properties This plugin is configured using the ``software.amazon.smithy.gradle.SmithyExtension`` extension: -.. tabs:: - - .. code-tab:: kotlin +.. code-block:: kotlin - configure { - projection = "foo" - } + configure { + projection = "foo" + } This extension supports the following properties: @@ -133,31 +129,29 @@ build scripts, Smithy models are discovered using only the The following example ``build.gradle.kts`` will build a Smithy model using a "source" build: -.. tabs:: +.. code-block:: kotlin - .. code-tab:: kotlin + plugins { + id("software.amazon.smithy").version("0.6.0") + } - plugins { - id("software.amazon.smithy").version("0.6.0") - } + // The SmithyExtension is used to customize the build. This example + // doesn't set any values and can be completely omitted. + configure {} - // The SmithyExtension is used to customize the build. This example - // doesn't set any values and can be completely omitted. - configure {} + repositories { + mavenLocal() + mavenCentral() + } - repositories { - mavenLocal() - mavenCentral() - } + dependencies { + implementation("software.amazon.smithy:smithy-model:__smithy_version__") - dependencies { - implementation("software.amazon.smithy:smithy-model:__smithy_version__") - - // These are just examples of dependencies. This model has a dependency on - // a "common" model package and uses the external AWS traits. - implementation("com.foo.baz:foo-model-internal-common:1.0.0") - implementation("software.amazon.smithy:smithy-aws-traits:__smithy_version__") - } + // These are just examples of dependencies. This model has a dependency on + // a "common" model package and uses the external AWS traits. + implementation("com.foo.baz:foo-model-internal-common:1.0.0") + implementation("software.amazon.smithy:smithy-aws-traits:__smithy_version__") + } .. _generating-projection: @@ -179,91 +173,87 @@ projected version of the model. The following example ``build.gradle.kts`` file will run a "projection" build that uses the "external" projection. -.. tabs:: - - .. code-tab:: kotlin - - plugins { - id("software.amazon.smithy").version("0.6.0") - } - - buildscript { - repositories { - mavenLocal() - mavenCentral() - } - dependencies { - classpath("software.amazon.smithy:smithy-aws-traits:__smithy_version__") - - // Take a dependency on the internal model package. This - // dependency *must* be a buildscript only dependency to ensure - // that is does not appear in the generated JAR. - classpath("com.foo.baz:foo-internal-model:1.0.0") - } - } - - // Use the "external" projection. This projection must be found in the - // smithy-build.json file. This also ensures that models found in the - // foo-internal-package that weren't filtered out are copied into the - // projection created by this package. - configure { - projection = "external" - projectionSourceTags = setOf("com.foo.baz:foo-internal-model") - } - - repositories { - mavenLocal() - mavenCentral() - } - - dependencies { - implementation("software.amazon.smithy:smithy-model:__smithy_version__") - - // Any dependencies that the projected model needs must be (re)declared - // here. For example, let's assume that the smithy-aws-traits package is - // needed in the projected model too. - implementation("software.amazon.smithy:smithy-aws-traits:__smithy_version__") - } +.. code-block:: kotlin + + plugins { + id("software.amazon.smithy").version("0.6.0") + } + + buildscript { + repositories { + mavenLocal() + mavenCentral() + } + dependencies { + classpath("software.amazon.smithy:smithy-aws-traits:__smithy_version__") + + // Take a dependency on the internal model package. This + // dependency *must* be a buildscript only dependency to ensure + // that is does not appear in the generated JAR. + classpath("com.foo.baz:foo-internal-model:1.0.0") + } + } + + // Use the "external" projection. This projection must be found in the + // smithy-build.json file. This also ensures that models found in the + // foo-internal-package that weren't filtered out are copied into the + // projection created by this package. + configure { + projection = "external" + projectionSourceTags = setOf("com.foo.baz:foo-internal-model") + } + + repositories { + mavenLocal() + mavenCentral() + } + + dependencies { + implementation("software.amazon.smithy:smithy-model:__smithy_version__") + + // Any dependencies that the projected model needs must be (re)declared + // here. For example, let's assume that the smithy-aws-traits package is + // needed in the projected model too. + implementation("software.amazon.smithy:smithy-aws-traits:__smithy_version__") + } Because the ``projection`` of the ``SmithyExtension`` was set to ``external``, a ``smithy-build.json`` file **must** be found that defines the ``external`` projection. For example: -.. tabs:: - - .. code-tab:: json - - { - "version": "1.0", - "projections": { - "external": { - "transforms": [ - { - "name": "excludeShapesByTag", - "args": { - "tags": ["internal"] - } - }, - { - "name": "excludeShapesByTrait", - "args": { - "traits": ["internal"] - } - }, - { - "name": "excludeMetadata", - "args": { - "keys": ["suppressions", "validators"] - } - }, - { - "name": "removeUnusedShapes" - } - ] - } - } - } +.. code-block:: json + + { + "version": "1.0", + "projections": { + "external": { + "transforms": [ + { + "name": "excludeShapesByTag", + "args": { + "tags": ["internal"] + } + }, + { + "name": "excludeShapesByTrait", + "args": { + "traits": ["internal"] + } + }, + { + "name": "excludeMetadata", + "args": { + "keys": ["suppressions", "validators"] + } + }, + { + "name": "removeUnusedShapes" + } + ] + } + } + } .. _projection-tags: @@ -275,26 +265,22 @@ Projections are meant to *project* and filter other models into another model. You need to specify which dependencies are being projected into your JAR by setting the ``projectionSourceTags`` property. -.. tabs:: - - .. code-tab:: kotlin +.. code-block:: kotlin - configure { - projection = "external" - projectionSourceTags = setOf("Foo", "com.baz:bar") - } + configure { + projection = "external" + projectionSourceTags = setOf("Foo", "com.baz:bar") + } Tags are used to logically group packages to make it easier to build projections. The ``tags`` property is used to add ``Smithy-Tags`` to a JAR. -.. tabs:: +.. code-block:: kotlin - .. code-tab:: kotlin - - configure { - tags = setOf("X", "foobaz-model") - } + configure { + tags = setOf("X", "foobaz-model") + } For example, if your service is made up of 10 packages, you can add the @@ -317,37 +303,33 @@ will be used to generate :ref:`artifacts ` from the Smithy The following example generates an OpenAPI model from a Smithy model: -.. tabs:: - - .. code-tab:: json +.. code-block:: json - { - "version": "1.0", - "plugins": { - "openapi": { - "service": "foo.baz#MyService" - } - } - } + { + "version": "1.0", + "plugins": { + "openapi": { + "service": "foo.baz#MyService" + } + } + } The above Smithy plugin also requires a ``buildscript`` dependency in ``build.gradle.kts``: -.. tabs:: - - .. code-tab:: kotlin +.. code-block:: kotlin - buildscript { - // ... - dependencies { - // ... + buildscript { + // ... + dependencies { + // ... - // This dependency is required in order to apply the "openapi" - // plugin in smithy-build.json - classpath("software.amazon.smithy:smithy-openapi:__smithy_version__") - } - } + // This dependency is required in order to apply the "openapi" + // plugin in smithy-build.json + classpath("software.amazon.smithy:smithy-openapi:__smithy_version__") + } + } Complete Examples ================= diff --git a/docs/source-1.0/guides/model-linters.rst b/docs/source-1.0/guides/model-linters.rst index 31b9a664072..d345cdaafc4 100644 --- a/docs/source-1.0/guides/model-linters.rst +++ b/docs/source-1.0/guides/model-linters.rst @@ -16,14 +16,12 @@ can be used to apply additional validation to Smithy models. The following example adds ``smithy-linters`` as a Gradle dependency to a ``build.gradle.kts`` file: -.. tabs:: +.. code-block:: kotlin - .. code-tab:: kotlin - - dependencies { - implementation("software.amazon.smithy:smithy-model:__smithy_version__") - implementation("software.amazon.smithy:smithy-linters:__smithy_version__") - } + dependencies { + implementation("software.amazon.smithy:smithy-model:__smithy_version__") + implementation("software.amazon.smithy:smithy-linters:__smithy_version__") + } After the dependency is added and available on the Java classpath, validators defined in the package and registered using `Java SPI`_ are available for diff --git a/docs/source-1.0/spec/aws/amazon-apigateway.rst b/docs/source-1.0/spec/aws/amazon-apigateway.rst index 360fbe8ed5d..c746dad7614 100644 --- a/docs/source-1.0/spec/aws/amazon-apigateway.rst +++ b/docs/source-1.0/spec/aws/amazon-apigateway.rst @@ -39,33 +39,36 @@ See also The following example sets the ``X-API-Key`` header as the API key source. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.apigateway#apiKeySource + use aws.apigateway#apiKeySource - @apiKeySource("HEADER") - service Weather { - version: "2018-03-17" - } + @apiKeySource("HEADER") + service Weather { + version: "2018-03-17" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#Weather": { - "type": "service", - "version": "2018-03-17", - "traits": { - "aws.apigateway#apiKeySource": "HEADER" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Weather": { + "type": "service", + "version": "2018-03-17", + "traits": { + "aws.apigateway#apiKeySource": "HEADER" + } + } + } + } .. note:: @@ -179,33 +182,31 @@ An *authorizer* definition is a structure that supports the following members: API Gateway will cache authorizer responses. If this field is not set, the default value is 300. The maximum value is 3600, or 1 hour. -.. tabs:: - - .. code-tab:: smithy - - namespace ns.foo - - use aws.apigateway#authorizer - use aws.apigateway#authorizers - use aws.auth#sigv4 - use aws.protocols#restJson1 - - @restJson1 - @sigv4(name: "weather") - @authorizer("arbitrary-name") - @authorizers( - "arbitrary-name": { - scheme: sigv4, - type: "request", - uri: "arn:foo:baz", - credentials: "arn:foo:bar", - identitySource: "mapping.expression", - identityValidationExpression: "[A-Z]+", - resultTtlInSeconds: 100 - }) - service Weather { - version: "2018-03-17" - } +.. code-block:: smithy + + namespace ns.foo + + use aws.apigateway#authorizer + use aws.apigateway#authorizers + use aws.auth#sigv4 + use aws.protocols#restJson1 + + @restJson1 + @sigv4(name: "weather") + @authorizer("arbitrary-name") + @authorizers( + "arbitrary-name": { + scheme: sigv4, + type: "request", + uri: "arn:foo:baz", + credentials: "arn:foo:bar", + identitySource: "mapping.expression", + identityValidationExpression: "[A-Z]+", + resultTtlInSeconds: 100 + }) + service Weather { + version: "2018-03-17" + } .. note:: @@ -277,33 +278,36 @@ See also Then following example enables request validation on a service: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.apigateway#requestValidator + use aws.apigateway#requestValidator - @requestValidator("full") - service Weather { - version: "2018-03-17" - } + @requestValidator("full") + service Weather { + version: "2018-03-17" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#Weather": { - "type": "service", - "version": "2018-03-17", - "traits": { - "aws.apigateway#requestValidator": "full" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Weather": { + "type": "service", + "version": "2018-03-17", + "traits": { + "aws.apigateway#requestValidator": "full" + } + } + } + } .. note:: diff --git a/docs/source-1.0/spec/aws/aws-auth.rst b/docs/source-1.0/spec/aws/aws-auth.rst index 2f93e681a55..e200f91727b 100644 --- a/docs/source-1.0/spec/aws/aws-auth.rst +++ b/docs/source-1.0/spec/aws/aws-auth.rst @@ -35,43 +35,46 @@ Trait value NOT be empty. This value SHOULD match the ``arnNamespace`` property of the :ref:`aws.api#service-trait`. -.. tabs:: - - .. code-tab:: smithy - - namespace aws.fooBaz - - use aws.api#service - use aws.auth#sigv4 - use aws.protocols#restJson1 - - @service(sdkId: "Some Value") - @sigv4(name: "foobaz") - @restJson1 - service FooBaz { - version: "2018-03-17", - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "aws.fooBaz#FooBaz": { - "type": "service", - "version": "2018-03-17", - "traits": { - "aws.protocols#restJson1": {}, - "aws.api#service": { - "sdkId": "Some Value" - }, - "aws.auth#sigv4": { - "name": "foobaz" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace aws.fooBaz + + use aws.api#service + use aws.auth#sigv4 + use aws.protocols#restJson1 + + @service(sdkId: "Some Value") + @sigv4(name: "foobaz") + @restJson1 + service FooBaz { + version: "2018-03-17", + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "aws.fooBaz#FooBaz": { + "type": "service", + "version": "2018-03-17", + "traits": { + "aws.protocols#restJson1": {}, + "aws.api#service": { + "sdkId": "Some Value" + }, + "aws.auth#sigv4": { + "name": "foobaz" + } + } + } + } + } .. smithy-trait:: aws.auth#unsignedPayload @@ -97,37 +100,40 @@ payload of a request is not signed. The following example defines an operation that indicates the payload of the operation MUST NOT be used as part of the request signature calculation: -.. tabs:: - - .. code-tab:: smithy - - use aws.auth#unsignedPayload - - @unsignedPayload - operation PutThings { - input: PutThingsInput, - output: PutThingsOutput - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#PutThings": { - "type": "operation", - "input": { - "target": "smithy.example#PutThingsInput" - }, - "output": { - "target": "smithy.example#PutThingsOutput" - }, - "traits": { - "aws.auth#unsignedPayload": {} - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + use aws.auth#unsignedPayload + + @unsignedPayload + operation PutThings { + input: PutThingsInput, + output: PutThingsOutput + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#PutThings": { + "type": "operation", + "input": { + "target": "smithy.example#PutThingsInput" + }, + "output": { + "target": "smithy.example#PutThingsOutput" + }, + "traits": { + "aws.auth#unsignedPayload": {} + } + } + } + } Unsigned Payloads and signature version 4 diff --git a/docs/source-1.0/spec/aws/aws-cloudformation.rst b/docs/source-1.0/spec/aws/aws-cloudformation.rst index 293e5a16009..72e13770393 100644 --- a/docs/source-1.0/spec/aws/aws-cloudformation.rst +++ b/docs/source-1.0/spec/aws/aws-cloudformation.rst @@ -59,20 +59,18 @@ supports the following members: The following example defines a simple resource that is also a CloudFormation resource: -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.cloudformation#cfnResource + use aws.cloudformation#cfnResource - @cfnResource - resource Foo { - identifiers: { - fooId: String, - }, - } + @cfnResource + resource Foo { + identifiers: { + fooId: String, + }, + } Resources that have properties that cannot be :ref:`automatically derived @@ -84,26 +82,24 @@ cannot be automatically converted to CloudFormation properties. The following example provides a ``name`` value and one structure shape in the ``additionalSchemas`` list. -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.cloudformation#cfnResource + use aws.cloudformation#cfnResource - @cfnResource( - name: "Foo", - additionalSchemas: [AdditionalFooProperties]) - resource FooResource { - identifiers: { - fooId: String, - }, - } + @cfnResource( + name: "Foo", + additionalSchemas: [AdditionalFooProperties]) + resource FooResource { + identifiers: { + fooId: String, + }, + } - structure AdditionalFooProperties { - barProperty: String, - } + structure AdditionalFooProperties { + barProperty: String, + } .. _aws-cloudformation-property-deriviation: diff --git a/docs/source-1.0/spec/aws/aws-core.rst b/docs/source-1.0/spec/aws/aws-core.rst index c2e84b37611..3da06ab5d96 100644 --- a/docs/source-1.0/spec/aws/aws-core.rst +++ b/docs/source-1.0/spec/aws/aws-core.rst @@ -33,80 +33,86 @@ The following example defines an AWS service that uses the default values of ``cloudFormationService``, ``arnNamespace``, ``cloudTrailEventSource`` and ``docId``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - $version: "1.0" - namespace aws.fooBaz + $version: "1.0" + namespace aws.fooBaz - use aws.api#service + use aws.api#service - @service(sdkId: "Some Value") - service FooBaz { - version: "2018-03-17", - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "aws.fooBaz#FooBaz": { - "type": "service", - "version": "2018-03-17", - "traits": { - "aws.api#service": { - "sdkId": "Some Value" - } - } - } - } - } - -The following example provides explicit values for all properties: - -.. tabs:: + @service(sdkId: "Some Value") + service FooBaz { + version: "2018-03-17", + } - .. code-tab:: smithy - $version: "1.0" - namespace aws.fooBaz +.. tab:: JSON - use aws.api#service + .. code-block:: json - @service( - sdkId: "Some Value", - cloudFormationName: "FooBaz", - arnNamespace: "myservice", - cloudTrailEventSource: "myservice.amazon.aws", - docId: "some-value-2018-03-17", - endpointPrefix: "my-endpoint" - ) - service FooBaz { - version: "2018-03-17", - } + { + "smithy": "1.0", + "shapes": { + "aws.fooBaz#FooBaz": { + "type": "service", + "version": "2018-03-17", + "traits": { + "aws.api#service": { + "sdkId": "Some Value" + } + } + } + } + } - .. code-tab:: json +The following example provides explicit values for all properties: - { - "smithy": "1.0", - "shapes": { - "aws.fooBaz#FooBaz": { - "type": "service", - "version": "2018-03-17", - "traits": { - "aws.api#service": { - "sdkId": "Some Value", - "cloudFormationName": "FooBaz", - "arnNamespace": "myservice", - "docId": "some-value-2018-03-17", - "cloudTrailEventSource": "myservice.amazon.aws" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + $version: "1.0" + namespace aws.fooBaz + + use aws.api#service + + @service( + sdkId: "Some Value", + cloudFormationName: "FooBaz", + arnNamespace: "myservice", + cloudTrailEventSource: "myservice.amazon.aws", + docId: "some-value-2018-03-17", + endpointPrefix: "my-endpoint" + ) + service FooBaz { + version: "2018-03-17", + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "aws.fooBaz#FooBaz": { + "type": "service", + "version": "2018-03-17", + "traits": { + "aws.api#service": { + "sdkId": "Some Value", + "cloudFormationName": "FooBaz", + "arnNamespace": "myservice", + "docId": "some-value-2018-03-17", + "cloudTrailEventSource": "myservice.amazon.aws" + } + } + } + } + } .. _service-sdk-id: @@ -401,60 +407,63 @@ label placeholders. For example, given the following service: -.. tabs:: - - .. code-tab:: smithy - - namespace aws.fooBaz - - use aws.api#service - use aws.api#arn - - @service(sdkId: "Some Value") - service FooBaz { - version: "2018-03-17", - resources: [MyResource], - } - - @arn(template: "myresource/{myId}") - resource MyResource { - identifiers: {myId: MyResourceId}, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#FooBaz": { - "type": "service", - "version": "2018-03-17", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ], - "traits": { - "aws.api#service": { - "sdkId": "Some Value" - } - } - }, - "smithy.example#MyResource": { - "type": "resource", - "identifiers": { - "myId": { - "target": "smithy.example#MyResourceId" - } - }, - "traits": { - "aws.api#arn": { - "template": "myresource/{myId}" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace aws.fooBaz + + use aws.api#service + use aws.api#arn + + @service(sdkId: "Some Value") + service FooBaz { + version: "2018-03-17", + resources: [MyResource], + } + + @arn(template: "myresource/{myId}") + resource MyResource { + identifiers: {myId: MyResourceId}, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#FooBaz": { + "type": "service", + "version": "2018-03-17", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ], + "traits": { + "aws.api#service": { + "sdkId": "Some Value" + } + } + }, + "smithy.example#MyResource": { + "type": "resource", + "identifiers": { + "myId": { + "target": "smithy.example#MyResourceId" + } + }, + "traits": { + "aws.api#arn": { + "template": "myresource/{myId}" + } + } + } + } + } The ARN template assigned to ``MyResource`` when used with the ``FooBaz`` service expands to ``arn:{AWS::partition}:myservice:{AWS::Region}:{AWS::AccountId}:myresource/{myId}`` @@ -472,51 +481,54 @@ its identifier, an absolute ARN template MUST be defined on the resource that uses a placeholder containing the name of the identifier of the resource. -.. tabs:: - - .. code-tab:: smithy - - use aws.api#arn - use aws.api#arnReference - - @arn(template: "{arn}", absolute: true) - resource MyResource { - identifiers: {arn: Arn} - } - - @arnReference(service: FooBaz, resource: MyResource) - string Arn - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyResource": { - "type": "resource", - "identifiers": { - "arn": { - "target": "smithy.example#Arn" - } - }, - "traits": { - "aws.api#arn": { - "template": "{arn}", - "absolute": true - } - } - }, - "smithy.example#Arn": { - "type": "string", - "traits": { - "aws.api#arnReference": { - "service": "FooBaz", - "resource": "MyResource" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + use aws.api#arn + use aws.api#arnReference + + @arn(template: "{arn}", absolute: true) + resource MyResource { + identifiers: {arn: Arn} + } + + @arnReference(service: FooBaz, resource: MyResource) + string Arn + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyResource": { + "type": "resource", + "identifiers": { + "arn": { + "target": "smithy.example#Arn" + } + }, + "traits": { + "aws.api#arn": { + "template": "{arn}", + "absolute": true + } + } + }, + "smithy.example#Arn": { + "type": "string", + "traits": { + "aws.api#arnReference": { + "service": "FooBaz", + "resource": "MyResource" + } + } + } + } + } .. smithy-trait:: aws.api#arnReference @@ -573,67 +585,73 @@ The CloudFormation name of the resource and the Smithy service and resource shape IDs are provided to give tooling additional information about the referenced resource. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.api#arnReference + use aws.api#arnReference - @arnReference( - type: "AWS::SomeService::SomeResource", - service: com.foo#SomeService, - resource: com.foo#SomeResource) - string SomeResourceId + @arnReference( + type: "AWS::SomeService::SomeResource", + service: com.foo#SomeService, + resource: com.foo#SomeResource) + string SomeResourceId - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#SomeResourceId": { - "type": "string", - "traits": { - "aws.api#arnReference": { - "type": "AWS::SomeService::SomeResource", - "service": "com.foo#SomeService", - "resource": "com.foo#SomeResource" - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#SomeResourceId": { + "type": "string", + "traits": { + "aws.api#arnReference": { + "type": "AWS::SomeService::SomeResource", + "service": "com.foo#SomeService", + "resource": "com.foo#SomeResource" + } + } + } + } + } The following example defines an ARN reference that doesn't provide an context about the referenced shape. While this is valid, it is not as useful as the previous example: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - $version: "1.0" - namespace smithy.example + $version: "1.0" + namespace smithy.example - use aws.api#arnReference + use aws.api#arnReference - @arnReference - string SomeResourceId + @arnReference + string SomeResourceId - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#SomeResourceId": { - "type": "string", - "traits": { - "aws.api#arnReference": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#SomeResourceId": { + "type": "string", + "traits": { + "aws.api#arnReference": {} + } + } + } + } .. smithy-trait:: aws.api#data @@ -656,56 +674,59 @@ 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. -.. tabs:: - - .. code-tab:: smithy - - use aws.api#data - - @data("permissions") - structure MyStructure { - name: String, - - @data("content") - content: String, - - tags: TagList, - } - - @data("tagging") - list TagList { - member: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "content": { - "target": "smithy.api#String", - "aws.api#data": "content" - }, - "tags": { - "target": "smithy.example#TagList" - }, - "name": { - "target": "smithy.api#String", - } - } - }, - "smithy.example#TagList": { - "type": "list", - "member": { - "target": "smithy.api#String" - }, - "aws.api#data": "tagging" - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + use aws.api#data + + @data("permissions") + structure MyStructure { + name: String, + + @data("content") + content: String, + + tags: TagList, + } + + @data("tagging") + list TagList { + member: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "content": { + "target": "smithy.api#String", + "aws.api#data": "content" + }, + "tags": { + "target": "smithy.example#TagList" + }, + "name": { + "target": "smithy.api#String", + } + } + }, + "smithy.example#TagList": { + "type": "list", + "member": { + "target": "smithy.api#String" + }, + "aws.api#data": "tagging" + } + } + } The effective data classifications in the previous example are as follows: @@ -792,37 +813,40 @@ operations bound within the shape are also considered part of the control plane unless an operation or resource is marked with the :ref:`aws.api#dataPlane-trait`. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - use aws.api#controlPlane + use aws.api#controlPlane - @controlPlane - operation PutThings { - input: PutThingsInput, - output: PutThingsOutput - } + @controlPlane + operation PutThings { + input: PutThingsInput, + output: PutThingsOutput + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#PutThings": { - "type": "operation", - "input": { - "target": "smithy.example#PutThingsInput" - }, - "output": { - "target": "smithy.example#PutThingsOutput" - }, - "traits": { - "aws.api#controlPlane": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#PutThings": { + "type": "operation", + "input": { + "target": "smithy.example#PutThingsInput" + }, + "output": { + "target": "smithy.example#PutThingsOutput" + }, + "traits": { + "aws.api#controlPlane": {} + } + } + } + } .. smithy-trait:: aws.api#dataPlane @@ -848,37 +872,40 @@ operations bound within the shape are also considered part of the data plane unless an operation or resource is marked with the :ref:`aws.api#controlPlane-trait`. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - use aws.api#controlPlane + use aws.api#controlPlane - @dataPlane - operation PutThings { - input: PutThingsInput, - output: PutThingsOutput - } + @dataPlane + operation PutThings { + input: PutThingsInput, + output: PutThingsOutput + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#PutThings": { - "type": "operation", - "input": { - "target": "smithy.example#PutThingsInput" - }, - "output": { - "target": "smithy.example#PutThingsOutput" - }, - "traits": { - "aws.api#dataPlane": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#PutThings": { + "type": "operation", + "input": { + "target": "smithy.example#PutThingsInput" + }, + "output": { + "target": "smithy.example#PutThingsOutput" + }, + "traits": { + "aws.api#dataPlane": {} + } + } + } + } .. _endpoint-discovery: 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 d15859283ec..7fe1d3e4c67 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 @@ -32,33 +32,36 @@ Value type * This protocol does not support :ref:`HTTP binding traits `. HTTP binding traits MUST be ignored if they are present. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#ec2Query + use aws.protocols#ec2Query - @ec2Query - service MyService { - version: "2020-02-05" - } + @ec2Query + service MyService { + version: "2020-02-05" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-02-05", - "traits": { - "aws.protocols#ec2Query": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-02-05", + "traits": { + "aws.protocols#ec2Query": {} + } + } + } + } .. smithy-trait:: aws.protocols#ec2QueryName @@ -84,35 +87,38 @@ Value type Given the following structure definition: -.. tabs:: - - .. code-tab:: smithy - - use aws.protocols#ec2QueryName - - structure MyStruct { - @ec2QueryName("foo") - bar: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStruct": { - "type": "structure", - "members": { - "bar": { - "target": "smithy.api#String", - "traits": { - "aws.protocols#ec2QueryName": "foo" - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + use aws.protocols#ec2QueryName + + structure MyStruct { + @ec2QueryName("foo") + bar: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStruct": { + "type": "structure", + "members": { + "bar": { + "target": "smithy.api#String", + "traits": { + "aws.protocols#ec2QueryName": "foo" + } + } + } + } + } + } and the following values provided for ``MyStruct``, diff --git a/docs/source-1.0/spec/aws/aws-iam.rst b/docs/source-1.0/spec/aws/aws-iam.rst index 8d1d149d997..92d7cc3f345 100644 --- a/docs/source-1.0/spec/aws/aws-iam.rst +++ b/docs/source-1.0/spec/aws/aws-iam.rst @@ -33,30 +33,33 @@ Trait selector Value type ``string`` -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.iam#actionPermissionDescription + use aws.iam#actionPermissionDescription - @actionPermissionDescription("This will allow the user to Foo.") - operation FooOperation {} + @actionPermissionDescription("This will allow the user to Foo.") + operation FooOperation {} - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#FooOperation": { - "type": "operation", - "traits": { - "aws.iam#actionPermissionDescription": "This will allow the user to Foo." - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#FooOperation": { + "type": "operation", + "traits": { + "aws.iam#actionPermissionDescription": "This will allow the user to Foo." + } + } + } + } .. smithy-trait:: aws.iam#conditionKeys @@ -81,85 +84,88 @@ The following example's ``MyResource`` resource has the ``myservice:MyResourceFoo`` and ``otherservice:Bar`` condition keys. The ``MyOperation`` operation has the ``aws:region`` condition key. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - use aws.api#service - use aws.iam#definedContextKeys - use aws.iam#conditionKeys - - @service(sdkId: "My Value", arnNamespace: "myservice") - @defineConditionKeys("otherservice:Bar": { type: "String" }) - service MyService { - version: "2017-02-11", - resources: [MyResource], - } - - @conditionKeys(["otherservice:Bar"]) - resource MyResource { - identifiers: {foo: String}, - operations: [MyOperation], - } - - @conditionKeys(["aws:region"]) - operation MyOperation {} - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ], - "traits": { - "aws.api#service": { - "sdkId": "My Value", - "arnNamespace": "myservice" - }, - "aws.iam#defineConditionKeys": { - "otherservice:Bar": { - "type": "String" - } - } - } - }, - "smithy.example#MyResource": { - "type": "resource", - "identifiers": { - "foo": { - "target": "smithy.api#String" - } - }, - "operations": [ - { - "target": "smithy.example#MyOperation" - } - ], - "traits": { - "aws.iam#conditionKeys": [ - "otherservice:Bar" - ] - } - }, - "smithy.example#MyOperation": { - "type": "operation", - "traits": { - "aws.iam#conditionKeys": [ - "aws:region" - ] - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + use aws.api#service + use aws.iam#definedContextKeys + use aws.iam#conditionKeys + + @service(sdkId: "My Value", arnNamespace: "myservice") + @defineConditionKeys("otherservice:Bar": { type: "String" }) + service MyService { + version: "2017-02-11", + resources: [MyResource], + } + + @conditionKeys(["otherservice:Bar"]) + resource MyResource { + identifiers: {foo: String}, + operations: [MyOperation], + } + + @conditionKeys(["aws:region"]) + operation MyOperation {} + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ], + "traits": { + "aws.api#service": { + "sdkId": "My Value", + "arnNamespace": "myservice" + }, + "aws.iam#defineConditionKeys": { + "otherservice:Bar": { + "type": "String" + } + } + } + }, + "smithy.example#MyResource": { + "type": "resource", + "identifiers": { + "foo": { + "target": "smithy.api#String" + } + }, + "operations": [ + { + "target": "smithy.example#MyOperation" + } + ], + "traits": { + "aws.iam#conditionKeys": [ + "otherservice:Bar" + ] + } + }, + "smithy.example#MyOperation": { + "type": "operation", + "traits": { + "aws.iam#conditionKeys": [ + "aws:region" + ] + } + } + } + } .. note:: @@ -210,56 +216,59 @@ Each condition key structure supports the following members: - ``string`` - A valid URL that defines more information about the condition key. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - use aws.api#service - use aws.iam#defineConditionKeys - - @service(sdkId: "My Value", arnNamespace: "myservice") - @defineConditionKeys( - "otherservice:Bar": { - type: "String", - documentation: "The Bar string", - externalDocumentation: "http://example.com" - }) - service MyService { - version: "2017-02-11", - resources: [MyResource], - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ], - "traits": { - "aws.api#service": { - "sdkId": "My Value", - "arnNamespace": "myservice" - }, - "aws.iam#defineConditionKeys": { - "otherservice:Bar": { - "type": "String", - "documentation": "The Bar string", - "externalDocumentation": "http://example.com" - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + use aws.api#service + use aws.iam#defineConditionKeys + + @service(sdkId: "My Value", arnNamespace: "myservice") + @defineConditionKeys( + "otherservice:Bar": { + type: "String", + documentation: "The Bar string", + externalDocumentation: "http://example.com" + }) + service MyService { + version: "2017-02-11", + resources: [MyResource], + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ], + "traits": { + "aws.api#service": { + "sdkId": "My Value", + "arnNamespace": "myservice" + }, + "aws.iam#defineConditionKeys": { + "otherservice:Bar": { + "type": "String", + "documentation": "The Bar string", + "externalDocumentation": "http://example.com" + } + } + } + } + } + } .. note:: @@ -332,65 +341,68 @@ the identifiers of its ancestors (if present.) The following example shows a resource, ``MyResource``, that has had its condition key inference disabled. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - use aws.api#service - use aws.iam#disableConditionKeyInference - - @service(sdkId: "My Value", arnNamespace: "myservice") - service MyService { - version: "2017-02-11", - resources: [MyResource], - } - - @disableConditionKeyInference - resource MyResource { - identifiers: { - foo: String, - bar: String, - }, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ], - "traits": { - "aws.api#service": { - "sdkId": "My Value", - "arnNamespace": "myservice" - } - } - }, - "smithy.example#MyResource": { - "type": "resource", - "identifiers": { - "foo": { - "target": "smithy.api#String" - }, - "bar": { - "target": "smithy.api#String" - } - }, - "traits": { - "aws.iam#disableConditionKeyInference": {} - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + use aws.api#service + use aws.iam#disableConditionKeyInference + + @service(sdkId: "My Value", arnNamespace: "myservice") + service MyService { + version: "2017-02-11", + resources: [MyResource], + } + + @disableConditionKeyInference + resource MyResource { + identifiers: { + foo: String, + bar: String, + }, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ], + "traits": { + "aws.api#service": { + "sdkId": "My Value", + "arnNamespace": "myservice" + } + } + }, + "smithy.example#MyResource": { + "type": "resource", + "identifiers": { + "foo": { + "target": "smithy.api#String" + }, + "bar": { + "target": "smithy.api#String" + } + }, + "traits": { + "aws.iam#disableConditionKeyInference": {} + } + } + } + } .. smithy-trait:: aws.iam#requiredActions @@ -415,72 +427,75 @@ indicates that, in order to invoke the ``MyOperation`` operation, the invoker must also be authorized to execute the ``otherservice:OtherOperation`` operation for it to complete successfully. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - use aws.api#service - use aws.iam#requiredActions - - @service(sdkId: "My Value", arnNamespace: "myservice") - service MyService { - version: "2017-02-11", - resources: [MyResource], - } - - resource MyResource { - identifiers: {foo: String}, - operations: [MyOperation], - } - - @requiredActions(["otherservice:OtherOperation"]) - operation MyOperation {} - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ], - "traits": { - "aws.api#service": { - "sdkId": "My Value", - "arnNamespace": "myservice" - } - } - }, - "smithy.example#MyResource": { - "type": "resource", - "identifiers": { - "foo": { - "target": "smithy.api#String" - } - }, - "operations": [ - { - "target": "smithy.example#MyOperation" - } - ] - }, - "smithy.example#MyOperation": { - "type": "operation", - "traits": { - "aws.iam#requiredActions": [ - "otherservice:OtherOperation" - ] - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + use aws.api#service + use aws.iam#requiredActions + + @service(sdkId: "My Value", arnNamespace: "myservice") + service MyService { + version: "2017-02-11", + resources: [MyResource], + } + + resource MyResource { + identifiers: {foo: String}, + operations: [MyOperation], + } + + @requiredActions(["otherservice:OtherOperation"]) + operation MyOperation {} + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ], + "traits": { + "aws.api#service": { + "sdkId": "My Value", + "arnNamespace": "myservice" + } + } + }, + "smithy.example#MyResource": { + "type": "resource", + "identifiers": { + "foo": { + "target": "smithy.api#String" + } + }, + "operations": [ + { + "target": "smithy.example#MyOperation" + } + ] + }, + "smithy.example#MyOperation": { + "type": "operation", + "traits": { + "aws.iam#requiredActions": [ + "otherservice:OtherOperation" + ] + } + } + } + } .. smithy-trait:: aws.iam#supportedPrincipalTypes @@ -509,24 +524,22 @@ The following example defines two operations: the IAM principal types supported by this operation are the principal types applied to the service. -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.iam#supportedPrincipalTypes + use aws.iam#supportedPrincipalTypes - @supportedPrincipalTypes(["Root", "IAMUser", "IAMRole", "FederatedUser"]) - service MyService { - version: "2020-07-02", - operations: [OperationA, OperationB], - } + @supportedPrincipalTypes(["Root", "IAMUser", "IAMRole", "FederatedUser"]) + service MyService { + version: "2020-07-02", + operations: [OperationA, OperationB], + } - @supportedPrincipalTypes(["Root"]) - operation OperationA {} + @supportedPrincipalTypes(["Root"]) + operation OperationA {} - operation OperationB {} + operation OperationB {} .. smithy-trait:: aws.iam#iamResource @@ -560,20 +573,18 @@ members: The following example defines a simple resource with a name in AWS IAM that deviates from the :ref:`shape name of the shape ID ` of the resource. -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.iam#iamResource + use aws.iam#iamResource - @iamResource(name: "super") - resource SuperResource { - identifiers: { - superId: String, - }, - } + @iamResource(name: "super") + resource SuperResource { + identifiers: { + superId: String, + }, + } .. _deriving-condition-keys: diff --git a/docs/source-1.0/spec/aws/aws-json-1_0-protocol.rst b/docs/source-1.0/spec/aws/aws-json-1_0-protocol.rst index 30aebc72a74..839d531f7d0 100644 --- a/docs/source-1.0/spec/aws/aws-json-1_0-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-json-1_0-protocol.rst @@ -54,33 +54,36 @@ values are provided. The following example defines a service that uses ``aws.protocols#awsJson1_0``. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#awsJson1_0 + use aws.protocols#awsJson1_0 - @awsJson1_0 - service MyService { - version: "2020-02-05" - } + @awsJson1_0 + service MyService { + version: "2020-02-05" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-02-05", - "traits": { - "aws.protocols#awsJson1_0": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-02-05", + "traits": { + "aws.protocols#awsJson1_0": {} + } + } + } + } The following example defines a service that requires the use of ``h2`` when using event streams. 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 b07379944eb..25004c440d0 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 @@ -54,33 +54,36 @@ values are provided. The following example defines a service that uses ``aws.protocols#awsJson1_1``. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#awsJson1_1 + use aws.protocols#awsJson1_1 - @awsJson1_1 - service MyService { - version: "2020-02-05" - } + @awsJson1_1 + service MyService { + version: "2020-02-05" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-02-05", - "traits": { - "aws.protocols#awsJson1_1": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-02-05", + "traits": { + "aws.protocols#awsJson1_1": {} + } + } + } + } The following example defines a service that requires the use of ``h2`` when using event streams. 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 384559ce93f..611618ae370 100644 --- a/docs/source-1.0/spec/aws/aws-query-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-query-protocol.rst @@ -461,37 +461,40 @@ Value type See `Protocol tests `_ -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#awsQuery + use aws.protocols#awsQuery - @awsQuery - @xmlNamespace(uri: "http://foo.com") - service MyService { - version: "2020-02-05" - } + @awsQuery + @xmlNamespace(uri: "http://foo.com") + service MyService { + version: "2020-02-05" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-02-05", - "traits": { - "aws.protocols#awsQuery": {}, - "smithy.api#xmlNamespace": { - "uri": "example.com" - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-02-05", + "traits": { + "aws.protocols#awsQuery": {}, + "smithy.api#xmlNamespace": { + "uri": "example.com" + } + } + } + } + } .. smithy-trait:: aws.protocols#awsQueryError @@ -540,43 +543,46 @@ Value type The following example defines an error that uses a custom "Code" of "InvalidThing" and an HTTP status code of 400. -.. tabs:: - - .. code-tab:: smithy - - use aws.protocols#awsQueryError - - @awsQueryError( - code: "InvalidThing", - httpResponseCode: 400, - ) - @error("client") - structure InvalidThingException { - message: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#InvalidThingException": { - "type": "structure", - "members": { - "message": { - "target": "smithy.api#String" - } - }, - "traits": { - "aws.protocols#awsQueryError": { - "code": "InvalidThing", - "httpResponseCode": 400 - }, - "smithy.api#error": "client" - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + use aws.protocols#awsQueryError + + @awsQueryError( + code: "InvalidThing", + httpResponseCode: 400, + ) + @error("client") + structure InvalidThingException { + message: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#InvalidThingException": { + "type": "structure", + "members": { + "message": { + "target": "smithy.api#String" + } + }, + "traits": { + "aws.protocols#awsQueryError": { + "code": "InvalidThing", + "httpResponseCode": 400 + }, + "smithy.api#error": "client" + } + } + } + } .. smithy-trait:: aws.protocols#awsQueryCompatible 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 0c47eb3bad8..18df0605b51 100644 --- a/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-restjson1-protocol.rst @@ -55,33 +55,36 @@ values are provided. The following example defines a service that uses ``aws.protocols#restJson1``. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#restJson1 + use aws.protocols#restJson1 - @restJson1 - service MyService { - version: "2020-04-02" - } + @restJson1 + service MyService { + version: "2020-04-02" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-04-02", - "traits": { - "aws.protocols#restJson1": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-04-02", + "traits": { + "aws.protocols#restJson1": {} + } + } + } + } The following example defines a service that requires the use of ``h2`` when using event streams. 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 ecf98f6d87e..5fc306a9016 100644 --- a/docs/source-1.0/spec/aws/aws-restxml-protocol.rst +++ b/docs/source-1.0/spec/aws/aws-restxml-protocol.rst @@ -57,33 +57,36 @@ values are provided. The following example defines a service that uses ``aws.protocols#restXml``. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - use aws.protocols#restXml + use aws.protocols#restXml - @restXml - service MyService { - version: "2020-04-02" - } + @restXml + service MyService { + version: "2020-04-02" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2020-04-02", - "traits": { - "aws.protocols#restXml": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2020-04-02", + "traits": { + "aws.protocols#restXml": {} + } + } + } + } The following example defines a service that requires the use of ``h2`` when using event streams. diff --git a/docs/source-1.0/spec/core/auth-traits.rst b/docs/source-1.0/spec/core/auth-traits.rst index 3a6503e41df..db1dfbcce24 100644 --- a/docs/source-1.0/spec/core/auth-traits.rst +++ b/docs/source-1.0/spec/core/auth-traits.rst @@ -45,46 +45,49 @@ supported authentication schemes. The following example defines a service that supports both ``httpBasicAuth`` and the hypothetical ``fooExample`` authentication scheme. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - @authDefinition - @trait(selector: "service") - structure fooExample {} - - @fooExample - @httpBasicAuth - service WeatherService { - version: "2017-02-11", - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#WeatherService": { - "type": "service", - "version": "2017-02-11", - "traits": { - "smithy.example#fooExample": {}, - "smithy.api#httpBasicAuth": {} - } - }, - "smithy.example#fooExample": { - "type": "structure", - "traits": { - "smithy.api#authDefinition": {}, - "smithy.api#trait": { - "selector": "service" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + @authDefinition + @trait(selector: "service") + structure fooExample {} + + @fooExample + @httpBasicAuth + service WeatherService { + version: "2017-02-11", + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#WeatherService": { + "type": "service", + "version": "2017-02-11", + "traits": { + "smithy.example#fooExample": {}, + "smithy.api#httpBasicAuth": {} + } + }, + "smithy.example#fooExample": { + "type": "structure", + "traits": { + "smithy.api#authDefinition": {}, + "smithy.api#trait": { + "selector": "service" + } + } + } + } + } Because authentication scheme definitions are just specialized shapes, they can also support configuration settings. @@ -329,122 +332,125 @@ to services and operations: * ``OperationD`` is annotated with the ``auth`` trait and defines an explicit list of authentication schemes. -.. tabs:: - - .. code-tab:: smithy - - @httpBasicAuth - @httpDigestAuth - @httpBearerAuth - service ServiceWithNoAuthTrait { - version: "2020-01-29", - operations: [ - OperationA, - OperationB - ] - } - - // This operation does not have the @auth trait and is bound to a service - // without the @auth trait. The effective set of authentication schemes it - // supports are: httpBasicAuth, httpDigestAuth and httpBearerAuth - operation OperationA {} - - // This operation does have the @auth trait and is bound to a service - // without the @auth trait. The effective set of authentication schemes it - // supports are: httpDigestAuth. - @auth([httpDigestAuth]) - operation OperationB {} - - @httpBasicAuth - @httpDigestAuth - @httpBearerAuth - @auth([httpBasicAuth, httpDigestAuth]) - service ServiceWithAuthTrait { - version: "2020-01-29", - operations: [ - OperationC, - OperationD - ] - } - - // This operation does not have the @auth trait and is bound to a service - // with the @auth trait. The effective set of authentication schemes it - // supports are: httpBasicAuth, httpDigestAuth - operation OperationC {} - - // This operation has the @auth trait and is bound to a service - // with the @auth trait. The effective set of authentication schemes it - // supports are: httpBearerAuth - @auth([httpBearerAuth]) - operation OperationD {} - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#OperationA": { - "type": "operation" - }, - "smithy.example#OperationB": { - "type": "operation", - "traits": { - "smithy.api#auth": [ - "smithy.api#httpDigestAuth" - ] - } - }, - "smithy.example#OperationC": { - "type": "operation" - }, - "smithy.example#OperationD": { - "type": "operation", - "traits": { - "smithy.api#auth": [ - "smithy.api#httpBearerAuth" - ] - } - }, - "smithy.example#ServiceWithAuthTrait": { - "type": "service", - "traits": { - "smithy.api#auth": [ - "smithy.api#httpBasicAuth", - "smithy.api#httpDigestAuth" - ], - "smithy.api#httpBasicAuth": {}, - "smithy.api#httpBearerAuth": {}, - "smithy.api#httpDigestAuth": {} - }, - "version": "2020-01-29", - "operations": [ - { - "target": "smithy.example#OperationC" - }, - { - "target": "smithy.example#OperationD" - } - ] - }, - "smithy.example#ServiceWithNoAuthTrait": { - "type": "service", - "traits": { - "smithy.api#httpBasicAuth": {}, - "smithy.api#httpBearerAuth": {}, - "smithy.api#httpDigestAuth": {} - }, - "version": "2020-01-29", - "operations": [ - { - "target": "smithy.example#OperationA" - }, - { - "target": "smithy.example#OperationB" - } - ] - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @httpBasicAuth + @httpDigestAuth + @httpBearerAuth + service ServiceWithNoAuthTrait { + version: "2020-01-29", + operations: [ + OperationA, + OperationB + ] + } + + // This operation does not have the @auth trait and is bound to a service + // without the @auth trait. The effective set of authentication schemes it + // supports are: httpBasicAuth, httpDigestAuth and httpBearerAuth + operation OperationA {} + + // This operation does have the @auth trait and is bound to a service + // without the @auth trait. The effective set of authentication schemes it + // supports are: httpDigestAuth. + @auth([httpDigestAuth]) + operation OperationB {} + + @httpBasicAuth + @httpDigestAuth + @httpBearerAuth + @auth([httpBasicAuth, httpDigestAuth]) + service ServiceWithAuthTrait { + version: "2020-01-29", + operations: [ + OperationC, + OperationD + ] + } + + // This operation does not have the @auth trait and is bound to a service + // with the @auth trait. The effective set of authentication schemes it + // supports are: httpBasicAuth, httpDigestAuth + operation OperationC {} + + // This operation has the @auth trait and is bound to a service + // with the @auth trait. The effective set of authentication schemes it + // supports are: httpBearerAuth + @auth([httpBearerAuth]) + operation OperationD {} + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#OperationA": { + "type": "operation" + }, + "smithy.example#OperationB": { + "type": "operation", + "traits": { + "smithy.api#auth": [ + "smithy.api#httpDigestAuth" + ] + } + }, + "smithy.example#OperationC": { + "type": "operation" + }, + "smithy.example#OperationD": { + "type": "operation", + "traits": { + "smithy.api#auth": [ + "smithy.api#httpBearerAuth" + ] + } + }, + "smithy.example#ServiceWithAuthTrait": { + "type": "service", + "traits": { + "smithy.api#auth": [ + "smithy.api#httpBasicAuth", + "smithy.api#httpDigestAuth" + ], + "smithy.api#httpBasicAuth": {}, + "smithy.api#httpBearerAuth": {}, + "smithy.api#httpDigestAuth": {} + }, + "version": "2020-01-29", + "operations": [ + { + "target": "smithy.example#OperationC" + }, + { + "target": "smithy.example#OperationD" + } + ] + }, + "smithy.example#ServiceWithNoAuthTrait": { + "type": "service", + "traits": { + "smithy.api#httpBasicAuth": {}, + "smithy.api#httpBearerAuth": {}, + "smithy.api#httpDigestAuth": {} + }, + "version": "2020-01-29", + "operations": [ + { + "target": "smithy.example#OperationA" + }, + { + "target": "smithy.example#OperationB" + } + ] + } + } + } The following ``auth`` trait is invalid because it references an authentication scheme trait that is not applied to the service: diff --git a/docs/source-1.0/spec/core/behavior-traits.rst b/docs/source-1.0/spec/core/behavior-traits.rst index c1b0d1e45df..26d1912b97a 100644 --- a/docs/source-1.0/spec/core/behavior-traits.rst +++ b/docs/source-1.0/spec/core/behavior-traits.rst @@ -265,58 +265,61 @@ inherited service setting. The following example defines a paginated operation that inherits some settings from a service. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - @paginated(inputToken: "nextToken", outputToken: "nextToken", - pageSize: "maxResults") - service Example { - version: "2019-06-27", - operations: [GetFoos], - } - - @readonly @paginated(items: "foos") - operation GetFoos { - input: GetFoosInput, - output: GetFoosOutput - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Example": { - "type": "service", - "version": "2019-06-27", - "traits": { - "smithy.api#paginated": { - "inputToken": "nextToken", - "outputToken": "nextToken", - "pageSize": "maxResults" - } - } - }, - "smithy.example#GetFoos": { - "type": "operation", - "input": { - "target": "smithy.example#GetFoosInput" - }, - "output": { - "target": "smithy.example#GetFoosOutput" - }, - "traits": { - "smithy.api#readonly": {}, - "smithy.api#paginated": { - "items": "foos" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + @paginated(inputToken: "nextToken", outputToken: "nextToken", + pageSize: "maxResults") + service Example { + version: "2019-06-27", + operations: [GetFoos], + } + + @readonly @paginated(items: "foos") + operation GetFoos { + input: GetFoosInput, + output: GetFoosOutput + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Example": { + "type": "service", + "version": "2019-06-27", + "traits": { + "smithy.api#paginated": { + "inputToken": "nextToken", + "outputToken": "nextToken", + "pageSize": "maxResults" + } + } + }, + "smithy.example#GetFoos": { + "type": "operation", + "input": { + "target": "smithy.example#GetFoosInput" + }, + "output": { + "target": "smithy.example#GetFoosOutput" + }, + "traits": { + "smithy.api#readonly": {}, + "smithy.api#paginated": { + "items": "foos" + } + } + } + } + } The values for ``outputToken`` and ``items`` are paths. :dfn:`Paths` are a series of identifiers separated by dots (``.``) where each identifier represents a @@ -513,15 +516,13 @@ Value type See :rfc:`1864` -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - @httpChecksumRequired - operation PutSomething { - input: PutSomethingInput, - output: PutSomethingOutput - } + @httpChecksumRequired + operation PutSomething { + input: PutSomethingInput, + output: PutSomethingOutput + } .. smithy-trait:: smithy.api#requestCompression diff --git a/docs/source-1.0/spec/core/constraint-traits.rst b/docs/source-1.0/spec/core/constraint-traits.rst index cc5a218771f..07d2e07d3ce 100644 --- a/docs/source-1.0/spec/core/constraint-traits.rst +++ b/docs/source-1.0/spec/core/constraint-traits.rst @@ -85,74 +85,77 @@ An *enum definition* is a structure that supports the following members: The following example defines an enum of valid string values for ``MyString``. -.. tabs:: - - .. code-tab:: smithy - - @enum([ - { - value: "t2.nano", - name: "T2_NANO", - documentation: """ - T2 instances are Burstable Performance - Instances that provide a baseline level of CPU - performance with the ability to burst above the - baseline.""", - tags: ["ebsOnly"] - }, - { - value: "t2.micro", - name: "T2_MICRO", - documentation: """ - T2 instances are Burstable Performance - Instances that provide a baseline level of CPU - performance with the ability to burst above the - baseline.""", - tags: ["ebsOnly"] - }, - { - value: "m256.mega", - name: "M256_MEGA", - deprecated: true - } - ]) - string MyString - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "string", - "traits": { - "smithy.api#enum": [ - { - "value": "t2.nano", - "name": "T2_NANO", - "documentation": "T2 instances are ...", - "tags": [ - "ebsOnly" - ] - }, - { - "value": "t2.micro", - "name": "T2_MICRO", - "documentation": "T2 instances are ...", - "tags": [ - "ebsOnly" - ] - }, - { - "value": "m256.mega", - "name": "M256_MEGA", - "deprecated": true - } - ] - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @enum([ + { + value: "t2.nano", + name: "T2_NANO", + documentation: """ + T2 instances are Burstable Performance + Instances that provide a baseline level of CPU + performance with the ability to burst above the + baseline.""", + tags: ["ebsOnly"] + }, + { + value: "t2.micro", + name: "T2_MICRO", + documentation: """ + T2 instances are Burstable Performance + Instances that provide a baseline level of CPU + performance with the ability to burst above the + baseline.""", + tags: ["ebsOnly"] + }, + { + value: "m256.mega", + name: "M256_MEGA", + deprecated: true + } + ]) + string MyString + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "string", + "traits": { + "smithy.api#enum": [ + { + "value": "t2.nano", + "name": "T2_NANO", + "documentation": "T2 instances are ...", + "tags": [ + "ebsOnly" + ] + }, + { + "value": "t2.micro", + "name": "T2_MICRO", + "documentation": "T2 instances are ...", + "tags": [ + "ebsOnly" + ] + }, + { + "value": "m256.mega", + "name": "M256_MEGA", + "deprecated": true + } + ] + } + } + } + } .. smithy-trait:: smithy.api#idRef @@ -210,99 +213,105 @@ To illustrate an example, a custom trait named ``integerRef`` is defined. This trait can be attached to any shape, and the value of the trait MUST contain a valid shape ID that targets an integer shape in the model. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @trait - @idRef(failWhenMissing: true, selector: "integer") - string integerRef + @trait + @idRef(failWhenMissing: true, selector: "integer") + string integerRef - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#integerRef": { - "type": "string", - "traits": { - "smithy.api#trait": {}, - "smithy.api#idRef": { - "failWhenMissing": true, - "selector": "integer" - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#integerRef": { + "type": "string", + "traits": { + "smithy.api#trait": {}, + "smithy.api#idRef": { + "failWhenMissing": true, + "selector": "integer" + } + } + } + } + } Given the following model, -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - @integerRef(NotFound) - string InvalidShape1 - - @integerRef(String) - string InvalidShape2 - - @integerRef("invalid-shape-id!") - string InvalidShape3 - - @integerRef(Integer) - string ValidShape - - @integerRef(MyShape) - string ValidShape2 - - integer MyShape - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#InvalidShape1": { - "type": "string", - "traits": { - "smithy.example#integerRef": "NotFound" - } - }, - "smithy.example#InvalidShape2": { - "type": "string", - "traits": { - "smithy.example#integerRef": "String" - } - }, - "smithy.example#InvalidShape3": { - "type": "string", - "traits": { - "smithy.example#integerRef": "invalid-shape-id!" - } - }, - "smithy.example#ValidShape": { - "type": "string", - "traits": { - "smithy.example#integerRef": "Integer" - } - }, - "smithy.example#ValidShape2": { - "type": "string", - "traits": { - "smithy.example#integerRef": "smithy.example#MyShape" - } - }, - "smithy.example#MyShape": { - "type": "integer" - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + @integerRef(NotFound) + string InvalidShape1 + + @integerRef(String) + string InvalidShape2 + + @integerRef("invalid-shape-id!") + string InvalidShape3 + + @integerRef(Integer) + string ValidShape + + @integerRef(MyShape) + string ValidShape2 + + integer MyShape + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#InvalidShape1": { + "type": "string", + "traits": { + "smithy.example#integerRef": "NotFound" + } + }, + "smithy.example#InvalidShape2": { + "type": "string", + "traits": { + "smithy.example#integerRef": "String" + } + }, + "smithy.example#InvalidShape3": { + "type": "string", + "traits": { + "smithy.example#integerRef": "invalid-shape-id!" + } + }, + "smithy.example#ValidShape": { + "type": "string", + "traits": { + "smithy.example#integerRef": "Integer" + } + }, + "smithy.example#ValidShape2": { + "type": "string", + "traits": { + "smithy.example#integerRef": "smithy.example#MyShape" + } + }, + "smithy.example#MyShape": { + "type": "integer" + } + } + } - ``InvalidShape1`` is invalid because the "NotFound" shape cannot be found in the model. @@ -362,29 +371,32 @@ string The number of `Unicode scalar values ` and resolve @@ -428,24 +440,27 @@ one namespace can appear per file. The following example defines a string shape named ``MyString`` in the ``smithy.example`` namespace: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - string MyString + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "string" - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "string" + } + } + } .. _use-statement: @@ -695,52 +710,58 @@ Simple shapes The following example defines a ``string`` shape: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - string MyString + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#String": { - "type": "string" - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#String": { + "type": "string" + } + } + } The following example defines an ``integer`` shape with a :ref:`range-trait`: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @range(min: 0, max: 1000) - integer MaxResults + @range(min: 0, max: 1000) + integer MaxResults - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MaxResults": { - "type": "integer", - "traits": { - "smithy.api#range": { - "min": 0, - "max": 100 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MaxResults": { + "type": "integer", + "traits": { + "smithy.api#range": { + "min": 0, + "max": 100 + } + } + } + } + } .. _idl-list: @@ -753,69 +774,75 @@ 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 `: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - list MyList { - member: String - } + list MyList { + member: String + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyList": { - "type": "list", - "member": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyList": { + "type": "list", + "member": { + "target": "smithy.api#String" + } + } + } + } Traits can be applied to the list shape and its member: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @length(min: 3, max: 10) - list MyList { - @length(min: 1, max: 100) - member: String - } + @length(min: 3, max: 10) + list MyList { + @length(min: 1, max: 100) + member: String + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyList": { - "type": "list", - "member": { - "target": "smithy.api#String", - "traits": { - "smithy.api#length": { - "min": 1, - "max": 100 - } - } - }, - "traits": { - "smithy.api#length": { - "min": 3, - "max": 10 - } - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyList": { + "type": "list", + "member": { + "target": "smithy.api#String", + "traits": { + "smithy.api#length": { + "min": 1, + "max": 100 + } + } + }, + "traits": { + "smithy.api#length": { + "min": 3, + "max": 10 + } + } + } + } + } .. _idl-set: @@ -827,63 +854,69 @@ A :ref:`set ` set shape is defined using a :token:`smithy:SetStatement`. The following example defines a set of strings: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - set StringSet { - member: String - } + set StringSet { + member: String + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#StringSet": { - "type": "set", - "member": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#StringSet": { + "type": "set", + "member": { + "target": "smithy.api#String" + } + } + } + } Traits can be applied to the set shape and its members: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @deprecated - set StringSet { - @pattern("\\w+") - member: String - } + @deprecated + set StringSet { + @pattern("\\w+") + member: String + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#StringSet": { - "type": "set", - "member": { - "target": "smithy.api#String", - "traits": { - "smithy.api#pattern": "\\w+" - } - }, - "traits": { - "smithy.api#deprecated": {} - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#StringSet": { + "type": "set", + "member": { + "target": "smithy.api#String", + "traits": { + "smithy.api#pattern": "\\w+" + } + }, + "traits": { + "smithy.api#deprecated": {} + } + } + } + } .. _idl-map: @@ -895,85 +928,91 @@ A :ref:`map ` shape is defined using a :token:`smithy:MapStatement`. The following example defines a map of strings to integers: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - map IntegerMap { - key: String, - value: Integer - } + map IntegerMap { + key: String, + value: Integer + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "type": "map", - "smithy.example#IntegerMap": { - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - } - } - } - } -Traits can be applied to the map shape and its members: +.. tab:: JSON -.. tabs:: + .. code-block:: json - .. code-tab:: smithy + { + "smithy": "1.0", + "shapes": { + "type": "map", + "smithy.example#IntegerMap": { + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + } + } + } + } - namespace smithy.example +Traits can be applied to the map shape and its members: - @length(min: 0, max: 100) - map IntegerMap { - @length(min: 1, max: 10) - key: String, - - @range(min: 1, max: 1000) - value: Integer - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#IntegerMap": { - "type": "map", - "key": { - "target": "smithy.api#String", - "traits": { - "smithy.api#length": { - "min": 1, - "max": 10 - } - } - }, - "value": { - "target": "smithy.api#Integer", - "traits": { - "smithy.api#range": { - "min": 1, - "max": 1000 - } - } - }, - "traits": { - "smithy.api#length": { - "min": 0, - "max": 100 - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + @length(min: 0, max: 100) + map IntegerMap { + @length(min: 1, max: 10) + key: String, + + @range(min: 1, max: 1000) + value: Integer + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#IntegerMap": { + "type": "map", + "key": { + "target": "smithy.api#String", + "traits": { + "smithy.api#length": { + "min": 1, + "max": 10 + } + } + }, + "value": { + "target": "smithy.api#Integer", + "traits": { + "smithy.api#range": { + "min": 1, + "max": 1000 + } + } + }, + "traits": { + "smithy.api#length": { + "min": 0, + "max": 100 + } + } + } + } + } .. _idl-structure: @@ -986,84 +1025,90 @@ A :ref:`structure ` shape is defined using a The following example defines a structure with two members: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - structure MyStructure { - foo: String, - baz: Integer, - } + structure MyStructure { + foo: String, + baz: Integer, + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String" - }, - "baz": { - "target": "smithy.api#Integer" - } - } - } - } - } - -Traits can be applied to structure members: -.. tabs:: +.. tab:: JSON - .. code-tab:: smithy + .. code-block:: json - namespace smithy.example + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String" + }, + "baz": { + "target": "smithy.api#Integer" + } + } + } + } + } - /// This is MyStructure. - structure MyStructure { - /// This is documentation for `foo`. - @required - foo: String, - - /// This is documentation for `baz`. - @deprecated - baz: Integer, - } +Traits can be applied to structure members: - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#documentation": "This is documentation for `foo`.", - "smithy.api#required": {} - } - }, - "baz": { - "target": "smithy.api#Integer", - "traits": { - "smithy.api#documentation": "This is documentation for `baz`.", - "smithy.api#deprecated": {} - } - } - }, - "traits": { - "smithy.api#documentation": "This is MyStructure." - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + /// This is MyStructure. + structure MyStructure { + /// This is documentation for `foo`. + @required + foo: String, + + /// This is documentation for `baz`. + @deprecated + baz: Integer, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#documentation": "This is documentation for `foo`.", + "smithy.api#required": {} + } + }, + "baz": { + "target": "smithy.api#Integer", + "traits": { + "smithy.api#documentation": "This is documentation for `baz`.", + "smithy.api#deprecated": {} + } + } + }, + "traits": { + "smithy.api#documentation": "This is MyStructure." + } + } + } + } .. _idl-union: @@ -1075,46 +1120,49 @@ A :ref:`union ` shape is defined using a :token:`smithy:UnionStatement`. The following example defines a union shape with several members: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - union MyUnion { - i32: Integer, + union MyUnion { + i32: Integer, - @length(min: 1, max: 100) - string: String, + @length(min: 1, max: 100) + string: String, - time: Timestamp, - } + time: Timestamp, + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyUnion": { - "type": "union", - "members": { - "i32": { - "target": "smithy.api#Integer" - }, - "string": { - "target": "smithy.api#String", - "smithy.api#length": { - "min": 1, - "max": 100 - } - }, - "time": { - "target": "smithy.api#Timestamp" - } - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyUnion": { + "type": "union", + "members": { + "i32": { + "target": "smithy.api#Integer" + }, + "string": { + "target": "smithy.api#String", + "smithy.api#length": { + "min": 1, + "max": 100 + } + }, + "time": { + "target": "smithy.api#Timestamp" + } + } + } + } + } .. _idl-service: @@ -1129,38 +1177,41 @@ A service shape is defined using a :token:`smithy:ServiceStatement` and the prov The following example defines a service named ``ModelRepository`` that binds a resource named ``Model`` and an operation named ``PingService``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - service ModelRepository { - version: "2020-07-13", - resources: [Model], - operations: [PingService] - } + service ModelRepository { + version: "2020-07-13", + resources: [Model], + operations: [PingService] + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ModelRepository": { - "type": "service", - "resources": [ - { - "target": "smithy.example#Model" - } - ], - "operations": [ - { - "target": "smithy.example#PingService" - } - ] - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ModelRepository": { + "type": "service", + "resources": [ + { + "target": "smithy.example#Model" + } + ], + "operations": [ + { + "target": "smithy.example#PingService" + } + ] + } + } + } .. _idl-operation: @@ -1177,42 +1228,45 @@ structure named ``Input``, returns an output structure named ``Output``, and can potentially return the ``Unavailable`` or ``BadRequest`` :ref:`error structures `. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - operation PingService { - input: PingServiceInput, - output: PingServiceOutput, - errors: [UnavailableError, BadRequestError] - } + operation PingService { + input: PingServiceInput, + output: PingServiceOutput, + errors: [UnavailableError, BadRequestError] + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#PingService": { - "type": "operation", - "input": { - "target": "smithy.example#PingServiceInput" - }, - "output": { - "target": "smithy.example#PingServiceOutput" - }, - "errors": [ - { - "target": "smithy.example#UnavailableError" - }, - { - "target": "smithy.example#BadRequestError" - } - ] - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#PingService": { + "type": "operation", + "input": { + "target": "smithy.example#PingServiceInput" + }, + "output": { + "target": "smithy.example#PingServiceOutput" + }, + "errors": [ + { + "target": "smithy.example#UnavailableError" + }, + { + "target": "smithy.example#BadRequestError" + } + ] + } + } + } .. _idl-resource: @@ -1227,37 +1281,40 @@ provided :token:`smithy:NodeObject` supports the same properties defined in the The following example defines a resource shape that has a single identifier, and defines a :ref:`read ` operation: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - resource SprocketResource { - identifiers: { - sprocketId: String, - }, - read: GetSprocket, - } + resource SprocketResource { + identifiers: { + sprocketId: String, + }, + read: GetSprocket, + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Sprocket": { - "type": "resource", - "identifiers": { - "sprocketId": { - "target": "smithy.api#String" - } - }, - "read": { - "target": "smithy.example#SprocketResource" - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Sprocket": { + "type": "resource", + "identifiers": { + "sprocketId": { + "target": "smithy.api#String" + } + }, + "read": { + "target": "smithy.example#SprocketResource" + } + } + } + } .. _documentation-comment: @@ -1364,33 +1421,36 @@ and the current namespace in exactly the same way as The following example applies the :ref:`length-trait` and :ref:`documentation-trait` to ``MyString``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @length(min: 1, max: 100) - @documentation("Contains a string") - string MyString + @length(min: 1, max: 100) + @documentation("Contains a string") + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "string", - "traits": { - "smithy.api#documentation": "Contains a string", - "smithy.api#length": { - "min": 1, - "max": 100 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "string", + "traits": { + "smithy.api#documentation": "Contains a string", + "smithy.api#length": { + "min": 1, + "max": 100 + } + } + } + } + } .. _trait-values: @@ -1445,46 +1505,49 @@ Omitting a value is allowed on ``list``, ``set``, ``map``, and ``structure`` traits if the shapes have no ``length`` constraints or ``required`` members. The following applications of the ``foo`` trait are equivalent: -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - @trait - structure foo {} - - @foo - string MyString1 - - @foo() - string MyString2 - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#foo": { - "type": "structure", - "traits": { - "smithy.api#trait": {} - } - }, - "smithy.example#MyString1": { - "type": "string", - "traits": { - "smithy.api#foo": {} - } - }, - "smithy.example#MyString2": { - "type": "string", - "traits": { - "smithy.api#foo": {} - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + @trait + structure foo {} + + @foo + string MyString1 + + @foo() + string MyString2 + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#foo": { + "type": "structure", + "traits": { + "smithy.api#trait": {} + } + }, + "smithy.example#MyString1": { + "type": "string", + "traits": { + "smithy.api#foo": {} + } + }, + "smithy.example#MyString2": { + "type": "string", + "traits": { + "smithy.api#foo": {} + } + } + } + } List and set trait values @@ -1522,32 +1585,35 @@ Traits can be applied to shapes outside of a shape's definition using an The following example applies the :ref:`documentation-trait` and :ref:`length-trait` to the ``smithy.example#MyString`` shape: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - apply MyString @documentation("This is my string!") - apply MyString @length(min: 1, max: 10) + apply MyString @documentation("This is my string!") + apply MyString @length(min: 1, max: 10) - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "apply", - "traits": { - "smithy.api#documentation": "This is my string!", - "smithy.api#length": { - "min": 1, - "max": 10 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "apply", + "traits": { + "smithy.api#documentation": "This is my string!", + "smithy.api#length": { + "min": 1, + "max": 10 + } + } + } + } + } Traits can be applied to members too: diff --git a/docs/source-1.0/spec/core/index.rst b/docs/source-1.0/spec/core/index.rst index 551bf10add8..35bbeadd264 100644 --- a/docs/source-1.0/spec/core/index.rst +++ b/docs/source-1.0/spec/core/index.rst @@ -30,44 +30,47 @@ are written using the :ref:`Smithy interface definition language (IDL) ` syntax. Complementary :ref:`JSON AST ` examples are provided alongside Smithy IDL examples where appropriate. For example: -.. tabs:: - - .. code-tab:: smithy - - $version: "1.0" - - metadata foo = "bar" - - namespace smithy.example - - use smithy.other.namespace#MyString - - structure MyStructure { - @required - foo: MyString - } - - .. code-tab:: json - - { - "smithy": "1.0", - "metadata": { - "foo": "bar" - }, - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.other.namespace#MyString", - "traits": { - "smithy.api#required": {} - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + $version: "1.0" + + metadata foo = "bar" + + namespace smithy.example + + use smithy.other.namespace#MyString + + structure MyStructure { + @required + foo: MyString + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "metadata": { + "foo": "bar" + }, + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.other.namespace#MyString", + "traits": { + "smithy.api#required": {} + } + } + } + } + } + } ----------------- Table of contents diff --git a/docs/source-1.0/spec/core/model-validation.rst b/docs/source-1.0/spec/core/model-validation.rst index 71a35822806..2bc129a20db 100644 --- a/docs/source-1.0/spec/core/model-validation.rst +++ b/docs/source-1.0/spec/core/model-validation.rst @@ -194,16 +194,14 @@ Value type The following example suppresses the ``Foo`` and ``Bar`` validation events for the ``smithy.example#MyString`` shape: -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - $version: "1.0" + $version: "1.0" - namespace smithy.example + namespace smithy.example - @suppress(["Foo", "Bar"]) - string MyString + @suppress(["Foo", "Bar"]) + string MyString .. _suppressions-metadata: diff --git a/docs/source-1.0/spec/core/model.rst b/docs/source-1.0/spec/core/model.rst index 78f1659dc55..3781c2cf4bf 100644 --- a/docs/source-1.0/spec/core/model.rst +++ b/docs/source-1.0/spec/core/model.rst @@ -364,72 +364,75 @@ Simple shapes are defined in the IDL using a :ref:`simple_shape_statement `. The following example defines a list with a string member from the :ref:`prelude `: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - list MyList { - member: String - } + list MyList { + member: String + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyList": { - "type": "list", - "member": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyList": { + "type": "list", + "member": { + "target": "smithy.api#String" + } + } + } + } .. rubric:: List member nullability @@ -520,31 +526,34 @@ The :ref:`box-trait` is not used to determine if a list is dense or sparse; a list with no ``@sparse`` trait is always considered dense. The following example defines a sparse list: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - @sparse - list SparseList { - member: String - } + @sparse + list SparseList { + member: String + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#SparseList": { - "type": "list", - "member": { - "target": "smithy.api#String" - }, - "traits": { - "smithy.api#sparse": {} - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#SparseList": { + "type": "list", + "member": { + "target": "smithy.api#String" + }, + "traits": { + "smithy.api#sparse": {} + } + } + } + } If a client encounters a ``null`` value when deserializing a dense list returned from a service, the client MUST discard the ``null`` value. If a @@ -580,29 +589,32 @@ contain floats, doubles, or documents. Sets are defined in the IDL using a :ref:`set_statement `. The following example defines a set of strings: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - set StringSet { - member: String - } + set StringSet { + member: String + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#StringSet": { - "type": "set", - "member": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#StringSet": { + "type": "set", + "member": { + "target": "smithy.api#String" + } + } + } + } .. rubric:: Sets MUST NOT contain ``null`` values @@ -642,33 +654,36 @@ that MUST target a ``string`` shape and a member named ``value``. Maps are defined in the IDL using a :ref:`map_statement `. The following example defines a map of strings to integers: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - map IntegerMap { - key: String, - value: Integer - } + map IntegerMap { + key: String, + value: Integer + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#IntegerMap": { - "type": "map", - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#IntegerMap": { + "type": "map", + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + } + } + } + } .. rubric:: Map keys MUST NOT be ``null`` @@ -684,35 +699,38 @@ Maps values are considered *dense* by default, meaning they MAY NOT contain is dense or sparse; a map with no ``@sparse`` trait is always considered dense. The following example defines a sparse map: -.. tabs:: - - .. code-tab:: smithy +.. tab:: Smithy - @sparse - map SparseMap { - key: String, - value: String - } + .. code-block:: smithy - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#SparseMap": { - "type": "map", - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - }, - "traits": { - "smithy.api#sparse": {} - } - } - } - } + @sparse + map SparseMap { + key: String, + value: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#SparseMap": { + "type": "map", + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + }, + "traits": { + "smithy.api#sparse": {} + } + } + } + } If a client encounters a ``null`` map value when deserializing a dense map returned from a service, the client MUST discard the ``null`` entry. If a @@ -742,40 +760,43 @@ Structures are defined in the IDL using a The following example defines a structure with two members, one of which is marked with the :ref:`required-trait`. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - structure MyStructure { - foo: String, + structure MyStructure { + foo: String, - @required - baz: Integer, - } + @required + baz: Integer, + } - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String" - }, - "baz": { - "target": "smithy.api#Integer", - "traits": { - "smithy.api#required": {} - } - } - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String" + }, + "baz": { + "target": "smithy.api#Integer", + "traits": { + "smithy.api#required": {} + } + } + } + } + } + } .. seealso:: @@ -829,46 +850,49 @@ Unions are defined in the IDL using a :ref:`union_statement `. A union shape MUST contain one or more named :ref:`members `. The following example defines a union shape with several members: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy - - namespace smithy.example - - union MyUnion { - i32: Integer, + .. code-block:: smithy - @length(min: 1, max: 100) - string: String, - - time: Timestamp, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyUnion": { - "type": "union", - "members": { - "i32": { - "target": "smithy.api#Integer" - }, - "string": { - "target": "smithy.api#String", - "smithy.api#length": { - "min": 1, - "max": 100 - } - }, - "time": { - "target": "smithy.api#Timestamp" - } - } - } - } - } + namespace smithy.example + + union MyUnion { + i32: Integer, + + @length(min: 1, max: 100) + string: String, + + time: Timestamp, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyUnion": { + "type": "union", + "members": { + "i32": { + "target": "smithy.api#Integer" + }, + "string": { + "target": "smithy.api#String", + "smithy.api#length": { + "min": 1, + "max": 100 + } + }, + "time": { + "target": "smithy.api#Timestamp" + } + } + } + } + } .. rubric:: Unit types in unions @@ -986,67 +1010,73 @@ Smithy allows recursive shape definitions with the following limitations: The following recursive shape definition is **valid**: -.. tabs:: - - .. code-tab:: smithy +.. tab:: Smithy - namespace smithy.example + .. code-block:: smithy - list ValidList { - member: IntermediateStructure - } + namespace smithy.example + + list ValidList { + member: IntermediateStructure + } + + structure IntermediateStructure { + foo: ValidList + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ValidList": { + "type": "list", + "member": { + "target": "smithy.example#IntermediateStructure" + } + }, + "smithy.example#IntermediateStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.example#ValidList" + } + } + } + } + } - structure IntermediateStructure { - foo: ValidList - } +The following recursive shape definition is **invalid**: - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ValidList": { - "type": "list", - "member": { - "target": "smithy.example#IntermediateStructure" - } - }, - "smithy.example#IntermediateStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.example#ValidList" - } - } - } - } - } +.. tab:: Smithy -The following recursive shape definition is **invalid**: + .. code-block:: smithy -.. tabs:: + namespace smithy.example - .. code-tab:: smithy + list RecursiveList { + member: RecursiveList + } - namespace smithy.example - list RecursiveList { - member: RecursiveList - } +.. tab:: JSON - .. code-tab:: json + .. code-block:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#RecursiveList": { - "type": "list", - "member": { - "target": "smithy.example#RecursiveList" - } - } - } - } + { + "smithy": "1.0", + "shapes": { + "smithy.example#RecursiveList": { + "type": "list", + "member": { + "target": "smithy.example#RecursiveList" + } + } + } + } The following recursive shape definition is **invalid** due to mutual recursion and the :ref:`required-trait`. @@ -1152,67 +1182,73 @@ The service shape supports the following properties: The following example defines a service with no operations or resources. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - service MyService { - version: "2017-02-11" - } + service MyService { + version: "2017-02-11" + } - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11" - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11" + } + } + } The following example defines a service shape that defines a set of errors that are common to every operation in the service: -.. tabs:: +.. tab:: Smithy + + .. code-block:: smithy - .. code-tab:: smithy + namespace smithy.example - namespace smithy.example + service MyService { + version: "2017-02-11", + errors: [SomeError] + } - service MyService { - version: "2017-02-11", - errors: [SomeError] - } + @error("client") + structure SomeError {} - @error("client") - structure SomeError {} - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "errors": [ - { - "target": "smithy.example#SomeError" - } - ] - }, - "smithy.example#SomeError": { - "type": "structure", - "traits": { - "smithy.api#error": "client" - } - } - } - } + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "errors": [ + { + "target": "smithy.example#SomeError" + } + ] + }, + "smithy.example#SomeError": { + "type": "structure", + "traits": { + "smithy.api#error": "client" + } + } + } + } @@ -1226,44 +1262,47 @@ shape ID of an operation to the ``operations`` property of a service. Operations bound directly to a service are typically RPC-style operations that do not fit within a resource hierarchy. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - service MyService { - version: "2017-02-11", - operations: [GetServerTime], - } +.. tab:: Smithy - @readonly - operation GetServerTime { - output: GetServerTimeOutput - } + .. code-block:: smithy - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "operations": [ - { - "target": "smithy.example#GetServerTime" - } - ] - }, - "smithy.example#GetServerTime": { - "type": "operation", - "output": { - "target": "smithy.example#GetServerTimeOutput" - } - } - } - } + namespace smithy.example + + service MyService { + version: "2017-02-11", + operations: [GetServerTime], + } + + @readonly + operation GetServerTime { + output: GetServerTimeOutput + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "operations": [ + { + "target": "smithy.example#GetServerTime" + } + ] + }, + "smithy.example#GetServerTime": { + "type": "operation", + "output": { + "target": "smithy.example#GetServerTimeOutput" + } + } + } + } .. _service-resources: @@ -1274,38 +1313,41 @@ Service resources :ref:`Resource ` shapes can be bound to a service by adding the shape ID of a resource to the ``resources`` property of a service. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - service MyService { - version: "2017-02-11", - resources: [MyResource], - } + service MyService { + version: "2017-02-11", + resources: [MyResource], + } - resource MyResource {} - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyService": { - "type": "service", - "version": "2017-02-11", - "resources": [ - { - "target": "smithy.example#MyResource" - } - ] - }, - "smithy.example#MyResource": { - "type": "resource" - } - } - } + resource MyResource {} + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyService": { + "type": "service", + "version": "2017-02-11", + "resources": [ + { + "target": "smithy.example#MyResource" + } + ] + }, + "smithy.example#MyResource": { + "type": "resource" + } + } + } .. _service-closure: @@ -1585,38 +1627,41 @@ The identifiers property of a resource is a map of identifier names to For example, the following model defines a ``Forecast`` resource with a single identifier named ``forecastId`` that targets the ``ForecastId`` shape: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - resource Forecast { - identifiers: { - forecastId: ForecastId - } - } + resource Forecast { + identifiers: { + forecastId: ForecastId + } + } - string ForecastId - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Forecast": { - "type": "resource", - "identifiers": { - "forecastId": { - "target": "smithy.example#ForecastId" - } - } - }, - "smithy.example#ForecastId": { - "type": "string" - } - } - } + string ForecastId + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Forecast": { + "type": "resource", + "identifiers": { + "forecastId": { + "target": "smithy.example#ForecastId" + } + } + }, + "smithy.example#ForecastId": { + "type": "string" + } + } + } When a resource is bound as a child to another resource using the "resources" property, all of the identifiers of the parent resource MUST be repeated @@ -1631,83 +1676,86 @@ identifiers. For example, given the following model, -.. tabs:: - - .. code-tab:: smithy - - resource ResourceA { - identifiers: { - a: String - }, - resources: [ResourceB], - } - - resource ResourceB { - identifiers: { - a: String, - b: String, - }, - resources: [ResourceC], - } +.. tab:: Smithy - resource ResourceC { - identifiers: { - a: String, - b: String, - c: String, - } - } + .. code-block:: smithy - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ResourceA": { - "type": "resource", - "resources": [ - { - "target": "smithy.example#ResourceB" - } - ], - "identifiers": { - "a": { - "target": "smithy.api#String" - } - } - }, - "smithy.example#ResourceB": { - "type": "resource", - "resources": [ - { - "target": "smithy.example#ResourceC" - } - ], - "identifiers": { - "a": { - "target": "smithy.api#String" - }, - "b": { - "target": "smithy.api#String" - } - } - }, - "smithy.example#ResourceC": { - "type": "resource", - "identifiers": { - "a": { - "target": "smithy.api#String" - }, - "b": { - "target": "smithy.api#String" - }, - "c": { - "target": "smithy.api#String" - } - } - } - } - } + resource ResourceA { + identifiers: { + a: String + }, + resources: [ResourceB], + } + + resource ResourceB { + identifiers: { + a: String, + b: String, + }, + resources: [ResourceC], + } + + resource ResourceC { + identifiers: { + a: String, + b: String, + c: String, + } + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ResourceA": { + "type": "resource", + "resources": [ + { + "target": "smithy.example#ResourceB" + } + ], + "identifiers": { + "a": { + "target": "smithy.api#String" + } + } + }, + "smithy.example#ResourceB": { + "type": "resource", + "resources": [ + { + "target": "smithy.example#ResourceC" + } + ], + "identifiers": { + "a": { + "target": "smithy.api#String" + }, + "b": { + "target": "smithy.api#String" + } + } + }, + "smithy.example#ResourceC": { + "type": "resource", + "identifiers": { + "a": { + "target": "smithy.api#String" + }, + "b": { + "target": "smithy.api#String" + }, + "c": { + "target": "smithy.api#String" + } + } + } + } + } ``ResourceB`` is a valid child of ``ResourceA`` and contains a child identifier of "b". ``ResourceC`` is a valid child of ``ResourceB`` and @@ -1716,78 +1764,81 @@ contains a child identifier of "c". However, the following defines two *invalid* child resources that do not define an ``identifiers`` property that is compatible with their parents: -.. tabs:: - - .. code-tab:: smithy - - resource ResourceA { - identifiers: { - a: String, - b: String, - }, - resources: [Invalid1, Invalid2], - } - - resource Invalid1 { - // Invalid: missing "a". - identifiers: { - b: String, - }, - } +.. tab:: Smithy - resource Invalid2 { - identifiers: { - a: String, - // Invalid: does not target the same shape. - b: SomeOtherString, - }, - } + .. code-block:: smithy - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ResourceA": { - "type": "resource", - "identifiers": { - "a": { - "target": "smithy.api#String" - }, - "b": { - "target": "smithy.api#String" - } - }, - "resources": [ - { - "target": "smithy.example#Invalid1" - }, - { - "target": "smithy.example#Invalid2" - } - ] - }, - "smithy.example#Invalid1": { - "type": "resource", - "identifiers": { - "b": { - "target": "smithy.api#String" - } - } - }, - "smithy.example#Invalid2": { - "type": "resource", - "identifiers": { - "a": { - "target": "smithy.api#String" - }, - "b": { - "target": "smithy.example#SomeOtherString" - } - } - } - } - } + resource ResourceA { + identifiers: { + a: String, + b: String, + }, + resources: [Invalid1, Invalid2], + } + + resource Invalid1 { + // Invalid: missing "a". + identifiers: { + b: String, + }, + } + + resource Invalid2 { + identifiers: { + a: String, + // Invalid: does not target the same shape. + b: SomeOtherString, + }, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ResourceA": { + "type": "resource", + "identifiers": { + "a": { + "target": "smithy.api#String" + }, + "b": { + "target": "smithy.api#String" + } + }, + "resources": [ + { + "target": "smithy.example#Invalid1" + }, + { + "target": "smithy.example#Invalid2" + } + ] + }, + "smithy.example#Invalid1": { + "type": "resource", + "identifiers": { + "b": { + "target": "smithy.api#String" + } + } + }, + "smithy.example#Invalid2": { + "type": "resource", + "identifiers": { + "a": { + "target": "smithy.api#String" + }, + "b": { + "target": "smithy.example#SomeOtherString" + } + } + } + } + } .. _binding-identifiers: @@ -2218,33 +2269,36 @@ Traits are applied to shapes in the IDL using :token:`smithy:TraitStatements` th immediately precede a shape. The following example applies the :ref:`length-trait` and :ref:`documentation-trait` to ``MyString``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @length(min: 1, max: 100) - @documentation("Contains a string") - string MyString + @length(min: 1, max: 100) + @documentation("Contains a string") + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "string", - "traits": { - "smithy.api#documentation": "Contains a string", - "smithy.api#length": { - "min": 1, - "max": 100 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "string", + "traits": { + "smithy.api#documentation": "Contains a string", + "smithy.api#length": { + "min": 1, + "max": 100 + } + } + } + } + } * Refer to the :ref:`IDL specification ` for a description of how traits are applied in the IDL. @@ -2276,32 +2330,35 @@ own a model that applies documentation traits to the shapes. The following example applies the :ref:`documentation-trait` and :ref:`length-trait` to the ``smithy.example#MyString`` shape: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - apply MyString @documentation("This is my string!") - apply MyString @length(min: 1, max: 10) + apply MyString @documentation("This is my string!") + apply MyString @length(min: 1, max: 10) - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "apply", - "traits": { - "smithy.api#documentation": "This is my string!", - "smithy.api#length": { - "min": 1, - "max": 10 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "apply", + "traits": { + "smithy.api#documentation": "This is my string!", + "smithy.api#length": { + "min": 1, + "max": 10 + } + } + } + } + } .. note:: @@ -2467,39 +2524,42 @@ a shape. This trait can only be applied to simple types, ``list``, ``map``, The following example defines a trait with a :ref:`shape ID ` of ``smithy.example#myTraitName`` and applies it to ``smithy.example#MyString``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @trait(selector: "*") - structure myTraitName {} + @trait(selector: "*") + structure myTraitName {} - @myTraitName - string MyString + @myTraitName + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#myTraitName": { - "type": "structure", - "traits": { - "smithy.api#trait": { - "selector": "*" - } - } - }, - "smithy.example#MyString": { - "type": "string", - "traits": { - "smithy.api#myTraitName": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#myTraitName": { + "type": "structure", + "traits": { + "smithy.api#trait": { + "selector": "*" + } + } + }, + "smithy.example#MyString": { + "type": "string", + "traits": { + "smithy.api#myTraitName": {} + } + } + } + } .. rubric:: Trait properties @@ -2538,103 +2598,106 @@ The following example defines a trait with a :ref:`shape ID ` of The following example defines two custom traits: ``beta`` and ``structuredTrait``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy - - namespace smithy.example - - /// A trait that can be applied to a member. - @trait(selector: "structure > member") - structure beta {} - - /// A trait that has members. - @trait(selector: "string", conflicts: [beta]) - structure structuredTrait { - @required - lorem: StringShape, - - @required - ipsum: StringShape, - - dolor: StringShape, - } - - // Apply the "beta" trait to the "foo" member. - structure MyShape { - @required - @beta - foo: StringShape, - } + .. code-block:: smithy - // Apply the structuredTrait to the string. - @structuredTrait( - lorem: "This is a custom trait!", - ipsum: "lorem and ipsum are both required values.") - string StringShape - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#beta": { - "type": "apply", - "traits": { - "smithy.api#type": "structure", - "smithy.api#trait": { - "selector": "structure > member" - }, - "smithy.api#documentation": "A trait that can be applied to a member." - } - }, - "smithy.example#structuredTrait": { - "type": "apply", - "traits": { - "smithy.api#type": "structure", - "smithy.api#trait": { - "selector": "string", - "conflicts": [ - "smithy.example#beta" - ] - }, - "smithy.api#members": { - "lorem": { - "target": "StringShape", - "required": true - }, - "dolor": { - "target": "StringShape" - } - }, - "smithy.api#documentation": "A trait that has members." - } - }, - "smithy.example#MyShape": { - "type": "apply", - "traits": { - "smithy.api#type": "structure", - "smithy.api#members": { - "beta": { - "target": "StringShape", - "required": true, - "beta": true - } - } - } - }, - "smithy.example#StringShape": { - "type": "apply", - "traits": { - "smithy.api#type": "string", - "smithy.api#structuredTrait": { - "lorem": "This is a custom trait!", - "ipsum": "lorem and ipsum are both required values." - } - } - } - } - } + namespace smithy.example + + /// A trait that can be applied to a member. + @trait(selector: "structure > member") + structure beta {} + + /// A trait that has members. + @trait(selector: "string", conflicts: [beta]) + structure structuredTrait { + @required + lorem: StringShape, + + @required + ipsum: StringShape, + + dolor: StringShape, + } + + // Apply the "beta" trait to the "foo" member. + structure MyShape { + @required + @beta + foo: StringShape, + } + + // Apply the structuredTrait to the string. + @structuredTrait( + lorem: "This is a custom trait!", + ipsum: "lorem and ipsum are both required values.") + string StringShape + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#beta": { + "type": "apply", + "traits": { + "smithy.api#type": "structure", + "smithy.api#trait": { + "selector": "structure > member" + }, + "smithy.api#documentation": "A trait that can be applied to a member." + } + }, + "smithy.example#structuredTrait": { + "type": "apply", + "traits": { + "smithy.api#type": "structure", + "smithy.api#trait": { + "selector": "string", + "conflicts": [ + "smithy.example#beta" + ] + }, + "smithy.api#members": { + "lorem": { + "target": "StringShape", + "required": true + }, + "dolor": { + "target": "StringShape" + } + }, + "smithy.api#documentation": "A trait that has members." + } + }, + "smithy.example#MyShape": { + "type": "apply", + "traits": { + "smithy.api#type": "structure", + "smithy.api#members": { + "beta": { + "target": "StringShape", + "required": true, + "beta": true + } + } + } + }, + "smithy.example#StringShape": { + "type": "apply", + "traits": { + "smithy.api#type": "string", + "smithy.api#structuredTrait": { + "lorem": "This is a custom trait!", + "ipsum": "lorem and ipsum are both required values." + } + } + } + } + } .. rubric:: Prelude traits @@ -2666,74 +2729,80 @@ boolean trait, the trait can safely add optional members over time as needed. The following example defines an annotation trait named ``foo``: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @trait - structure foo {} + @trait + structure foo {} - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#foo": { - "type": "structure", - "traits": { - "smithy.api#trait": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#foo": { + "type": "structure", + "traits": { + "smithy.api#trait": {} + } + } + } + } A member can be safely added to an annotation trait if the member is not marked as :ref:`required `. The applications of the ``foo`` trait in the previous example and the following example are all valid even after adding a member to the ``foo`` trait: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy - - namespace smithy.example - - @trait - structure foo { - baz: String, - } + .. code-block:: smithy - @foo(baz: "bar") - string MyString4 - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#foo": { - "type": "structure", - "members": { - "baz": { - "target": "smithy.api#String" - } - }, - "traits": { - "smithy.api#trait": {} - } - }, - "smithy.example#MyString4": { - "type": "string", - "traits": { - "smithy.api#foo": { - "baz": "bar" - } - } - } - } - } + namespace smithy.example + + @trait + structure foo { + baz: String, + } + + @foo(baz: "bar") + string MyString4 + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#foo": { + "type": "structure", + "members": { + "baz": { + "target": "smithy.api#String" + } + }, + "traits": { + "smithy.api#trait": {} + } + }, + "smithy.example#MyString4": { + "type": "string", + "traits": { + "smithy.api#foo": { + "baz": "bar" + } + } + } + } + } .. _trait-breaking-change-rules: @@ -3092,48 +3161,54 @@ semantic model: The following example defines metadata using a node value: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - metadata foo = "hello" + metadata foo = "hello" - .. code-tab:: json - { - "smithy": "1.0", - "metadata": { - "foo": "hello" - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "metadata": { + "foo": "hello" + } + } The following example defines a trait using a node value: -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - namespace smithy.example + namespace smithy.example - @length(min: 1, max: 10) - string MyString + @length(min: 1, max: 10) + string MyString - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyString": { - "type": "string", - "traits": { - "smithy.api#length": { - "min": 1, - "max": 10 - } - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyString": { + "type": "string", + "traits": { + "smithy.api#length": { + "min": 1, + "max": 10 + } + } + } + } + } Node value types diff --git a/docs/source-1.0/spec/core/protocol-traits.rst b/docs/source-1.0/spec/core/protocol-traits.rst index 61c1af42b56..5c1af1fa3eb 100644 --- a/docs/source-1.0/spec/core/protocol-traits.rst +++ b/docs/source-1.0/spec/core/protocol-traits.rst @@ -54,61 +54,64 @@ MAY be used to influence how messages are serialized (for example, The following example defines a service that supports both the hypothetical ``jsonExample`` and ``xmlExample`` protocols. -.. tabs:: - - .. code-tab:: smithy - - /// An example JSON protocol. - @protocolDefinition - @trait(selector: "service") - structure jsonExample {} - - /// An example XML protocol. - @protocolDefinition - @trait(selector: "service") - structure xmlExample {} - - @jsonExample - @xmlExample - service WeatherService { - version: "2017-02-11", - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#WeatherService": { - "type": "service", - "version": "2017-02-11", - "traits": { - "smithy.example#jsonExample": {}, - "smithy.example#xmlExample": {} - } - }, - "smithy.example#jsonExample": { - "type": "structure", - "traits": { - "smithy.api#documentation": "An example JSON protocol." - "smithy.api#protocolDefinition": {}, - "smithy.api#trait": { - "selector": "service" - } - } - }, - "smithy.example#xmlExample": { - "type": "structure", - "traits": { - "smithy.api#documentation": "An example JSON protocol." - "smithy.api#protocolDefinition": {}, - "smithy.api#trait": { - "selector": "service" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + /// An example JSON protocol. + @protocolDefinition + @trait(selector: "service") + structure jsonExample {} + + /// An example XML protocol. + @protocolDefinition + @trait(selector: "service") + structure xmlExample {} + + @jsonExample + @xmlExample + service WeatherService { + version: "2017-02-11", + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#WeatherService": { + "type": "service", + "version": "2017-02-11", + "traits": { + "smithy.example#jsonExample": {}, + "smithy.example#xmlExample": {} + } + }, + "smithy.example#jsonExample": { + "type": "structure", + "traits": { + "smithy.api#documentation": "An example JSON protocol." + "smithy.api#protocolDefinition": {}, + "smithy.api#trait": { + "selector": "service" + } + } + }, + "smithy.example#xmlExample": { + "type": "structure", + "traits": { + "smithy.api#documentation": "An example JSON protocol." + "smithy.api#protocolDefinition": {}, + "smithy.api#trait": { + "selector": "service" + } + } + } + } + } Because protocol definitions are just specialized shapes, they can also support configuration settings. @@ -147,38 +150,41 @@ Value type Given the following structure definition, -.. tabs:: - - .. code-tab:: smithy - - structure MyStructure { - @jsonName("Foo") - foo: String, - - bar: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#jsonName": "Foo" - } - }, - "bar": { - "target": "smithy.api#String" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure MyStructure { + @jsonName("Foo") + foo: String, + + bar: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#jsonName": "Foo" + } + }, + "bar": { + "target": "smithy.api#String" + } + } + } + } + } and the following values provided for ``MyStructure``, @@ -222,28 +228,31 @@ Value type The following example defines a ``video/quicktime`` blob: -.. tabs:: +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example - .. code-tab:: smithy + @mediaType("video/quicktime") + blob VideoData - namespace smithy.example - @mediaType("video/quicktime") - blob VideoData +.. tab:: JSON - .. code-tab:: json + .. code-block:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#VideoData": { - "type": "blob", - "traits": { - "smithy.api#mediaType": "video/quicktime" - } - } - } - } + { + "smithy": "1.0", + "shapes": { + "smithy.example#VideoData": { + "type": "blob", + "traits": { + "smithy.api#mediaType": "video/quicktime" + } + } + } + } .. rubric:: Use cases diff --git a/docs/source-1.0/spec/core/resource-traits.rst b/docs/source-1.0/spec/core/resource-traits.rst index 16631ab4942..c2a8a3e61d8 100644 --- a/docs/source-1.0/spec/core/resource-traits.rst +++ b/docs/source-1.0/spec/core/resource-traits.rst @@ -33,42 +33,45 @@ client, making it appropriate to model in Smithy as a ``put`` lifecycle operation. However, ``UpdateTable`` is used to update a table and attempting to call ``CreateTable`` on a table that already exists will return an error. -.. tabs:: - - .. code-tab:: smithy - - @noReplace - resource Table { - put: CreateTable - } - - @idempotent - operation CreateTable { - // ... - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Table": { - "type": "resource", - "put": { - "target": "smithy.example#CreateTable" - }, - "traits": { - "smithy.api#noReplace": {} - } - }, - "smithy.example#CreateTable": { - "type": "operation", - "traits": { - "smithy.api#idempotent": {} - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @noReplace + resource Table { + put: CreateTable + } + + @idempotent + operation CreateTable { + // ... + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Table": { + "type": "resource", + "put": { + "target": "smithy.example#CreateTable" + }, + "traits": { + "smithy.api#noReplace": {} + } + }, + "smithy.example#CreateTable": { + "type": "operation", + "traits": { + "smithy.api#idempotent": {} + } + } + } + } .. smithy-trait:: smithy.api#references @@ -196,37 +199,35 @@ defined if needed. For example: The following example defines several references: -.. tabs:: - - .. code-tab:: smithy - - @references([ - {resource: Forecast}, - {resource: ShapeName}, - {resource: Meteorologist}, - { - resource: com.foo.baz#Object, - service: com.foo.baz#Service, - ids: {bucket: "bucketName", object: "objectKey"}, - ]) - structure ForecastInformation { - someId: SomeShapeIdentifier, - - @required - forecastId: ForecastId, - - @required - meteorologistId: MeteorologistId, - - @required - otherData: SomeOtherShape, - - @required - bucketName: BucketName, +.. code-block:: smithy - @required - objectKey: ObjectKey, - } + @references([ + {resource: Forecast}, + {resource: ShapeName}, + {resource: Meteorologist}, + { + resource: com.foo.baz#Object, + service: com.foo.baz#Service, + ids: {bucket: "bucketName", object: "objectKey"}, + ]) + structure ForecastInformation { + someId: SomeShapeIdentifier, + + @required + forecastId: ForecastId, + + @required + meteorologistId: MeteorologistId, + + @required + otherData: SomeOtherShape, + + @required + bucketName: BucketName, + + @required + objectKey: ObjectKey, + } .. rubric:: References on string shapes diff --git a/docs/source-1.0/spec/core/stream-traits.rst b/docs/source-1.0/spec/core/stream-traits.rst index db0260b7f8b..db92aa77937 100644 --- a/docs/source-1.0/spec/core/stream-traits.rst +++ b/docs/source-1.0/spec/core/stream-traits.rst @@ -100,13 +100,11 @@ Validation * ``requiresLength`` shapes can only be referenced from top-level members of operation input structures. -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - @streaming - @requiresLength - blob FiniteStreamingBlob + @streaming + @requiresLength + blob FiniteStreamingBlob .. _event-streams: @@ -399,87 +397,93 @@ protocol-specific document. The following example serializes the "a" and "b" members as event headers and the "c" member as the payload. -.. tabs:: - - .. code-tab:: smithy - - structure ExampleEvent { - @eventHeader - a: String, - - @eventHeader - b: String, - - @eventPayload - c: Blob, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ExampleEvent": { - "type": "structure", - "members": { - "a": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventPayload": {} - } - }, - "b": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventPayload": {} - } - }, - "c": { - "target": "smithy.api#Blob", - "traits": { - "smithy.api#eventPayload": {} - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure ExampleEvent { + @eventHeader + a: String, + + @eventHeader + b: String, + + @eventPayload + c: Blob, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ExampleEvent": { + "type": "structure", + "members": { + "a": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventPayload": {} + } + }, + "b": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventPayload": {} + } + }, + "c": { + "target": "smithy.api#Blob", + "traits": { + "smithy.api#eventPayload": {} + } + } + } + } + } + } The following example serializes the "a", "b", and "c" members as the payload of the event using a protocol-specific document. For example, when using a JSON based protocol, the event payload is serialized as a JSON object: -.. tabs:: - - .. code-tab:: smithy - - structure ExampleEvent { - a: String, - b: String, - c: Blob, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ExampleEvent": { - "type": "structure", - "members": { - "a": { - "target": "smithy.api#String" - }, - "b": { - "target": "smithy.api#String" - }, - "c": { - "target": "smithy.api#Blob" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure ExampleEvent { + a: String, + b: String, + c: Blob, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ExampleEvent": { + "type": "structure", + "members": { + "a": { + "target": "smithy.api#String" + }, + "b": { + "target": "smithy.api#String" + }, + "c": { + "target": "smithy.api#Blob" + } + } + } + } + } Event stream traits =================== @@ -513,42 +517,45 @@ Conflicts with The following example defines multiple event headers: -.. tabs:: - - .. code-tab:: smithy - - structure ExampleEvent { - @eventHeader - a: String, - - @eventHeader - b: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ExampleEvent": { - "type": "structure", - "members": { - "a": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventHeader": {} - } - }, - "b": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventHeader": {} - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure ExampleEvent { + @eventHeader + a: String, + + @eventHeader + b: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ExampleEvent": { + "type": "structure", + "members": { + "a": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventHeader": {} + } + }, + "b": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventHeader": {} + } + } + } + } + } + } .. smithy-trait:: smithy.api#eventPayload @@ -585,42 +592,45 @@ Event payload is serialized using the following logic: The following example defines an event header and sends a blob as the payload of an event: -.. tabs:: - - .. code-tab:: smithy - - structure ExampleEvent { - @eventPayload - a: String, - - @eventHeader - b: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#ExampleEvent": { - "type": "structure", - "members": { - "a": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventPayload": {} - } - }, - "b": { - "target": "smithy.api#String", - "traits": { - "smithy.api#eventHeader": {} - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure ExampleEvent { + @eventPayload + a: String, + + @eventHeader + b: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#ExampleEvent": { + "type": "structure", + "members": { + "a": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventPayload": {} + } + }, + "b": { + "target": "smithy.api#String", + "traits": { + "smithy.api#eventHeader": {} + } + } + } + } + } + } The following structure is **invalid** because the "a" member is bound to the ``eventPayload``, and the "b" member is not bound to an ``eventHeader``. diff --git a/docs/source-1.0/spec/core/type-refinement-traits.rst b/docs/source-1.0/spec/core/type-refinement-traits.rst index dbdd9121dff..ca5256995c5 100644 --- a/docs/source-1.0/spec/core/type-refinement-traits.rst +++ b/docs/source-1.0/spec/core/type-refinement-traits.rst @@ -37,26 +37,29 @@ in Java, this might mean the value provided as the member of an aggregate shape can be set to null. In a language like Rust, this might mean the value is wrapped in an `Option type`_. -.. tabs:: +.. tab:: Smithy - .. code-tab:: smithy + .. code-block:: smithy - @box - integer BoxedInteger + @box + integer BoxedInteger - .. code-tab:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#BoxedInteger": { - "type": "integer", - "traits": { - "smithy.api#box": {} - } - } - } - } +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#BoxedInteger": { + "type": "integer", + "traits": { + "smithy.api#box": {} + } + } + } + } The :ref:`prelude ` contains predefined simple shapes that can be used in all Smithy models, including boxed and unboxed shapes. @@ -83,36 +86,30 @@ Conflicts with The following structure defines a throttling error. -.. tabs:: +.. code-block:: smithy - .. code-tab:: smithy - - @error("client") - structure ThrottlingError {} + @error("client") + structure ThrottlingError {} Note that this structure is lacking the ``retryable`` trait that generically lets clients know that the error is retryable. -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - @error("client") - @retryable - structure ThrottlingError {} + @error("client") + @retryable + structure ThrottlingError {} When using an HTTP-based protocol, it is recommended to add an :ref:`httpError-trait` to use an appropriate HTTP status code with the error. -.. tabs:: +.. code-block:: smithy - .. code-tab:: smithy - - @error("client") - @retryable - @httpError(429) - structure ThrottlingError {} + @error("client") + @retryable + @httpError(429) + structure ThrottlingError {} The ``message`` member of an error structure is special-cased. It contains the human-readable message that describes the error. If the ``message`` member @@ -120,17 +117,15 @@ is not defined in the structure, code generated for the error may not provide an idiomatic way to access the error message (e.g., an exception message in Java). -.. tabs:: - - .. code-tab:: smithy +.. code-block:: smithy - @error("client") - @retryable - @httpError(429) - structure ThrottlingError { - @required - message: String, - } + @error("client") + @retryable + @httpError(429) + structure ThrottlingError { + @required + message: String, + } .. smithy-trait:: smithy.api#input @@ -210,63 +205,69 @@ Value type The following example defines a :ref:`list ` shape that MAY contain ``null`` values: -.. tabs:: +.. tab:: Smithy + + .. code-block:: smithy + + @sparse + list SparseList { + member: String + } - .. code-tab:: smithy - @sparse - list SparseList { - member: String - } +.. tab:: JSON - .. code-tab:: json + .. code-block:: json - { - "smithy": "1.0", - "shapes": { - "smithy.example#SparseList": { - "type": "list", - "member": { - "target": "smithy.api#String", - }, - "traits": { - "smithy.api#sparse": {} - } - } - } - } + { + "smithy": "1.0", + "shapes": { + "smithy.example#SparseList": { + "type": "list", + "member": { + "target": "smithy.api#String", + }, + "traits": { + "smithy.api#sparse": {} + } + } + } + } The following example defines a :ref:`map ` shape that MAY contain ``null`` values: -.. tabs:: - - .. code-tab:: smithy - - @sparse - map SparseMap { - key: String, - value: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#SparseMap": { - "type": "map", - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - }, - "traits": { - "smithy.api#sparse": {} - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @sparse + map SparseMap { + key: String, + value: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#SparseMap": { + "type": "map", + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + }, + "traits": { + "smithy.api#sparse": {} + } + } + } + } .. _Option type: https://doc.rust-lang.org/std/option/enum.Option.html diff --git a/docs/source-1.0/spec/core/xml-traits.rst b/docs/source-1.0/spec/core/xml-traits.rst index b678f6fd6ba..9726da78bf0 100644 --- a/docs/source-1.0/spec/core/xml-traits.rst +++ b/docs/source-1.0/spec/core/xml-traits.rst @@ -69,49 +69,52 @@ An ``xmlName`` trait applied to a structure or union changes the element name of the serialized shape; however, it does not influence the serialization of members that target it. Given the following: -.. tabs:: - - .. code-tab:: smithy - - @xmlName("AStruct") - structure A { - b: B, - } - - @xmlName("BStruct") - structure B { - hello: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#A": { - "type": "structure", - "members": { - "b": { - "target": "smithy.example#B" - } - }, - "traits": { - "smithy.api#xmlName": "AStruct" - } - }, - "smithy.example#B": { - "type": "structure", - "members": { - "hello": { - "target": "smithy.api#String" - } - }, - "traits": { - "smithy.api#xmlName": "BStruct" - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @xmlName("AStruct") + structure A { + b: B, + } + + @xmlName("BStruct") + structure B { + hello: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#A": { + "type": "structure", + "members": { + "b": { + "target": "smithy.example#B" + } + }, + "traits": { + "smithy.api#xmlName": "AStruct" + } + }, + "smithy.example#B": { + "type": "structure", + "members": { + "hello": { + "target": "smithy.api#String" + } + }, + "traits": { + "smithy.api#xmlName": "BStruct" + } + } + } + } The XML serialization of ``AStruct`` is: @@ -240,43 +243,46 @@ The XML serialization of ``Foo`` is: The :ref:`xmlname-trait` can be applied to the member of a list or set to change the nested element name. For example, given the following: -.. tabs:: - - .. code-tab:: smithy - - structure Foo { - values: MyList - } - - list MyList { - @xmlName("Item") - member: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Foo": { - "type": "structure", - "members": { - "values": { - "target": "smithy.example#MyList" - } - } - }, - "smithy.example#MyList": { - "type": "list", - "member": { - "target": "smithy.api#String", - "traits": { - "smithy.api#xmlName": "Item" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure Foo { + values: MyList + } + + list MyList { + @xmlName("Item") + member: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Foo": { + "type": "structure", + "members": { + "values": { + "target": "smithy.example#MyList" + } + } + }, + "smithy.example#MyList": { + "type": "list", + "member": { + "target": "smithy.api#String", + "traits": { + "smithy.api#xmlName": "Item" + } + } + } + } + } The XML serialization of ``Foo`` is: @@ -453,47 +459,50 @@ Flattened map serialization The :ref:`xmlFlattened-trait` can be used to flatten the members of map into a containing structure/union. For example, given the following: -.. tabs:: - - .. code-tab:: smithy - - structure Bar { - @xmlFlattened - flatMap: MyMap - } - - map MyMap { - key: String, - value: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Bar": { - "type": "structure", - "members": { - "flatMap": { - "target": "smithy.example#MyMap", - "traits": { - "smithy.api#xmlFlattened": {} - } - } - } - }, - "smithy.example#MyMap": { - "type": "map", - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure Bar { + @xmlFlattened + flatMap: MyMap + } + + map MyMap { + key: String, + value: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Bar": { + "type": "structure", + "members": { + "flatMap": { + "target": "smithy.example#MyMap", + "traits": { + "smithy.api#xmlFlattened": {} + } + } + } + }, + "smithy.example#MyMap": { + "type": "map", + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + } + } + } + } The XML serialization of ``Bar`` is: @@ -613,38 +622,41 @@ Conflicts with By default, the serialized XML attribute name is the same as the structure member name. For example, given the following: -.. tabs:: - - .. code-tab:: smithy - - structure MyStructure { - @xmlAttribute - foo: String, - - bar: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#xmlAttribute": {} - } - }, - "bar": { - "target": "smithy.api#String" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure MyStructure { + @xmlAttribute + foo: String, + + bar: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#xmlAttribute": {} + } + }, + "bar": { + "target": "smithy.api#String" + } + } + } + } + } The XML serialization is: @@ -657,35 +669,38 @@ The XML serialization is: The serialized attribute name can be changed using the :ref:`xmlname-trait`. Given the following: -.. tabs:: - - .. code-tab:: smithy - - structure MyStructure { - @xmlAttribute - @xmlName("NotFoo") - foo: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#xmlAttribute": {}, - "smithy.api#xmlName": "NotFoo" - } - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure MyStructure { + @xmlAttribute + @xmlName("NotFoo") + foo: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#xmlAttribute": {}, + "smithy.api#xmlName": "NotFoo" + } + } + } + } + } + } The XML serialization is: @@ -714,48 +729,51 @@ Value type Given the following: -.. tabs:: - - .. code-tab:: smithy - - structure Foo { - @xmlFlattened - flat: MyList, - - nested: MyList, - } - - list MyList { - member: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Foo": { - "type": "structure", - "members": { - "flat": { - "target": "smithy.example#MyList", - "traits": { - "smithy.api#xmlFlattened": {} - } - }, - "nested": { - "target": "smithy.example#MyList" - } - } - }, - "smithy.example#MyList": { - "type": "list", - "member": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure Foo { + @xmlFlattened + flat: MyList, + + nested: MyList, + } + + list MyList { + member: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Foo": { + "type": "structure", + "members": { + "flat": { + "target": "smithy.example#MyList", + "traits": { + "smithy.api#xmlFlattened": {} + } + }, + "nested": { + "target": "smithy.example#MyList" + } + } + }, + "smithy.example#MyList": { + "type": "list", + "member": { + "target": "smithy.api#String" + } + } + } + } The XML serialization of ``Foo`` is: @@ -774,52 +792,55 @@ The XML serialization of ``Foo`` is: Maps can be flattened into structures too. Given the following: -.. tabs:: - - .. code-tab:: smithy - - structure Foo { - @xmlFlattened - flat: MyMap, - - notFlat: MyMap, - } - - map MyMap { - key: String - value: String - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#Foo": { - "type": "structure", - "members": { - "flat": { - "target": "smithy.example#MyMap", - "traits": { - "smithy.api#xmlFlattened": {} - } - }, - "notFlat": { - "target": "smithy.example#MyMap" - } - } - }, - "smithy.example#MyMap": { - "type": "map", - "key": { - "target": "smithy.api#String" - }, - "value": { - "target": "smithy.api#String" - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure Foo { + @xmlFlattened + flat: MyMap, + + notFlat: MyMap, + } + + map MyMap { + key: String + value: String + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#Foo": { + "type": "structure", + "members": { + "flat": { + "target": "smithy.example#MyMap", + "traits": { + "smithy.api#xmlFlattened": {} + } + }, + "notFlat": { + "target": "smithy.example#MyMap" + } + } + }, + "smithy.example#MyMap": { + "type": "map", + "key": { + "target": "smithy.api#String" + }, + "value": { + "target": "smithy.api#String" + } + } + } + } The XML serialization is: @@ -871,38 +892,41 @@ Value type By default, structure properties are serialized in attributes or nested elements using the same name as the structure member name. Given the following: -.. tabs:: - - .. code-tab:: smithy - - structure MyStructure { - @xmlName("Foo") - foo: String, - - bar: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#xmlName": "Foo" - } - }, - "bar": { - "target": "smithy.api#String" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + structure MyStructure { + @xmlName("Foo") + foo: String, + + bar: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#xmlName": "Foo" + } + }, + "bar": { + "target": "smithy.api#String" + } + } + } + } + } The XML serialization is: @@ -970,39 +994,42 @@ The ``xmlNamespace`` trait is a structure that contains the following members: Given the following: -.. tabs:: - - .. code-tab:: smithy - - @xmlNamespace(uri: "http://foo.com") - structure MyStructure { - foo: String, - bar: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#MyStructure": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String" - }, - "bar": { - "target": "smithy.api#String" - } - }, - "traits": { - "smithy.api#xmlNamespace": { - "uri": "http://foo.com" - } - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + @xmlNamespace(uri: "http://foo.com") + structure MyStructure { + foo: String, + bar: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#MyStructure": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String" + }, + "bar": { + "target": "smithy.api#String" + } + }, + "traits": { + "smithy.api#xmlNamespace": { + "uri": "http://foo.com" + } + } + } + } + } The XML serialization is: 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 a2654d0ab91..8131a2fd6f2 100644 --- a/docs/source-1.0/spec/http-protocol-compliance-tests.rst +++ b/docs/source-1.0/spec/http-protocol-compliance-tests.rst @@ -491,75 +491,78 @@ trait associated with an operation can be properly deserialized. The following example defines a protocol compliance test for a JSON protocol that uses :ref:`HTTP binding traits `. -.. tabs:: - - .. code-tab:: smithy - - namespace smithy.example - - use smithy.test#httpResponseTests - - @error("client") - @httpError(400) - @httpResponseTests([ - { - id: "invalid_greeting", - protocol: exampleProtocol, - params: {foo: "baz", message: "Hi"}, - code: 400, - headers: {"X-Foo": "baz"}, - body: "{\"message\": \"Hi\"}", - bodyMediaType: "application/json", - } - ]) - structure InvalidGreeting { - @httpHeader("X-Foo") - foo: String, - - message: String, - } - - .. code-tab:: json - - { - "smithy": "1.0", - "shapes": { - "smithy.example#InvalidGreeting": { - "type": "structure", - "members": { - "foo": { - "target": "smithy.api#String", - "traits": { - "smithy.api#httpHeader": "X-Foo" - } - }, - "message": { - "target": "smithy.api#String" - } - }, - "traits": { - "smithy.api#error": "client", - "smithy.api#httpError": 400, - "smithy.test#httpResponseTests": [ - { - "id": "invalid_greeting", - "protocol": "smithy.example#exampleProtocol", - "body": "{\"message\": \"Hi\"}", - "bodyMediaType": "application/json", - "headers": { - "X-Foo": "baz" - }, - "params": { - "foo": "baz", - "message": "Hi" - }, - "code": 400 - } - ] - } - } - } - } +.. tab:: Smithy + + .. code-block:: smithy + + namespace smithy.example + + use smithy.test#httpResponseTests + + @error("client") + @httpError(400) + @httpResponseTests([ + { + id: "invalid_greeting", + protocol: exampleProtocol, + params: {foo: "baz", message: "Hi"}, + code: 400, + headers: {"X-Foo": "baz"}, + body: "{\"message\": \"Hi\"}", + bodyMediaType: "application/json", + } + ]) + structure InvalidGreeting { + @httpHeader("X-Foo") + foo: String, + + message: String, + } + + +.. tab:: JSON + + .. code-block:: json + + { + "smithy": "1.0", + "shapes": { + "smithy.example#InvalidGreeting": { + "type": "structure", + "members": { + "foo": { + "target": "smithy.api#String", + "traits": { + "smithy.api#httpHeader": "X-Foo" + } + }, + "message": { + "target": "smithy.api#String" + } + }, + "traits": { + "smithy.api#error": "client", + "smithy.api#httpError": 400, + "smithy.test#httpResponseTests": [ + { + "id": "invalid_greeting", + "protocol": "smithy.example#exampleProtocol", + "body": "{\"message\": \"Hi\"}", + "bodyMediaType": "application/json", + "headers": { + "X-Foo": "baz" + }, + "params": { + "foo": "baz", + "message": "Hi" + }, + "code": 400 + } + ] + } + } + } + } .. smithy-trait:: smithy.test#httpMalformedRequestTests From 923ce733ef7dfe7956be7006e2019a0facc9e9de Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Fri, 23 Jan 2026 13:18:46 +0100 Subject: [PATCH 3/3] Add changelog entry for tabs update --- ...mentation-c3032bfab7d72e585876ebdf5918879eaa7006bb.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .changes/next-release/documentation-c3032bfab7d72e585876ebdf5918879eaa7006bb.json diff --git a/.changes/next-release/documentation-c3032bfab7d72e585876ebdf5918879eaa7006bb.json b/.changes/next-release/documentation-c3032bfab7d72e585876ebdf5918879eaa7006bb.json new file mode 100644 index 00000000000..07c25a82c9b --- /dev/null +++ b/.changes/next-release/documentation-c3032bfab7d72e585876ebdf5918879eaa7006bb.json @@ -0,0 +1,7 @@ +{ + "type": "documentation", + "description": "Updated Sphinx to 9.1 and updated the tabs in the Smithy 1.0 docs to use the same tab library that 2.0 uses.", + "pull_requests": [ + "[#2942](https://github.com/smithy-lang/smithy/pull/2942)" + ] +}