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)" + ] +} 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..f245751cd57 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", @@ -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