Change recommended operation IDL syntax

The old operation syntax is now deprecated in favor of a syntax that's more consistent with the rest of the IDL. The following operation, operation Foo(Input) -> Output errors[X, Y, Z] Is now defined as: operation Foo { input: Input, output: Output, errors: [X, Y, Z] } Why? - This new syntax is more consistent with other shapes like resources, operations, structures, etc. This consistency makes it easier to implement parsers, formatters, etc. - Virtually all *actual* models define operations with errors. When an operation uses long input names, output, *and* defines errors, they either are one really long line or span multiple lines. How an operation definition was broken across multiple lines is something that has been approached with great inconsistency within AWS and Amazon. Using a syntax format that removes all ambiguity will help drive consistency in models, thereby making them easier to read. The old syntax is still supported, but no longer documented. A validation event is emitted when it is encountered. Support for the old syntax will be removed in Smithy 1.0.
backend-souls · Jan 13, 2020 · 96a684b · 96a684b
1 parent bcaf8b6
commit 96a684b
Show file tree

Hide file tree

Showing 44 changed files with 502 additions and 193 deletions.
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -307,7 +307,11 @@ Let's define the operation used to "read" a ``City``.
     .. code-tab:: smithy
 
         @readonly
-        operation GetCity(GetCityInput) -> GetCityOutput errors [NoSuchResource]
+        operation GetCity {
+            input: GetCityInput,
+            output: GetCityOutput,
+            errors: [NoSuchResource]
+        }
 
         structure GetCityInput {
             // "cityId" provides the identifier for the resource and
@@ -460,7 +464,10 @@ cities, so there's no way we could provide a City identifier.
         // sets default pagination configuration settings on each operation.
         @paginated(items: "items")
         @readonly
-        operation ListCities(ListCitiesInput) -> ListCitiesOutput
+        operation ListCities {
+            input: ListCitiesInput,
+            output: ListCitiesOutput
+        }
 
         structure ListCitiesInput {
             nextToken: String,
@@ -622,7 +629,9 @@ service.
         }
 
         @readonly
-        operation GetCurrentTime() -> GetCurrentTimeOutput
+        operation GetCurrentTime {
+            output: GetCurrentTimeOutput
+        }
 
         structure GetCurrentTimeOutput {
             @required
@@ -720,7 +729,11 @@ Complete example
         string CityId
 
         @readonly
-        operation GetCity(GetCityInput) -> GetCityOutput errors [NoSuchResource]
+        operation GetCity {
+            input: GetCityInput,
+            output: GetCityOutput,
+            errors: [NoSuchResource]
+        }
 
         structure GetCityInput {
             // "cityId" provides the identifier for the resource and
@@ -760,7 +773,10 @@ Complete example
         // return truncated results.
         @readonly
         @paginated(items: "items")
-        operation ListCities(ListCitiesInput) -> ListCitiesOutput
+        operation ListCities {
+            input: ListCitiesInput,
+            output: ListCitiesOutput
+        }
 
         structure ListCitiesInput {
             nextToken: String,
@@ -790,15 +806,20 @@ Complete example
         }
 
         @readonly
-        operation GetCurrentTime() -> GetCurrentTimeOutput
+        operation GetCurrentTime {
+            output: GetCurrentTimeOutput
+        }
 
         structure GetCurrentTimeOutput {
             @required
             time: Timestamp
         }
 
         @readonly
-        operation GetForecast(GetForecastInput) -> GetForecastOutput
+        operation GetForecast {
+            input: GetForecastInput,
+            output: GetForecastOutput
+        }
 
         // "cityId" provides the only identifier for the resource since
         // a Forecast doesn't have its own.

diff --git a/docs/source/smithylexer.py b/docs/source/smithylexer.py
@@ -32,8 +32,7 @@ class SmithyLexer(RegexLexer):
             (r'///.*$', Comment.Multiline),
             (r'//.*$', Comment),
             (r'@[0-9a-zA-Z\.#-]*', Name.Decorator),
-            (r'(->|=)', Name.Decorator),
-            (r'errors', Name.Decorator),
+            (r'(=)', Name.Decorator),
             (r'^(\$version)(:)(.+)', bygroups(Keyword.Declaration, Name.Decorator, Name.Class)),
             (r'^(namespace)(\s+' + identifier + r')\b', bygroups(Keyword.Declaration, Name.Class)),
             (r'^(use|byte|short|integer|long|float|'

diff --git a/docs/source/spec/aws-core.rst b/docs/source/spec/aws-core.rst
@@ -752,7 +752,10 @@ plane unless an operation or resource is marked with the
         use aws.api#controlPlane
 
         @controlPlane
-        operation PutThings(PutThingsInput) -> PutThingsOutput
+        operation PutThings {
+            input: PutThingsInput,
+            output: PutThingsOutput
+        }
 
     .. code-tab:: json
 
@@ -803,7 +806,10 @@ plane unless an operation or resource is marked with the
         use aws.api#controlPlane
 
         @dataPlane
-        operation PutThings(PutThingsInput) -> PutThingsOutput
+        operation PutThings {
+            input: PutThingsInput,
+            output: PutThingsOutput
+        }
 
     .. code-tab:: json
 
@@ -859,7 +865,10 @@ operation MUST NOT be used as part of the request signature calculation:
         use aws.api#unsignedPayload
 
         @unsignedPayload
-        operation PutThings(PutThingsInput) -> PutThingsOutput
+        operation PutThings {
+            input: PutThingsInput,
+            output: PutThingsOutput
+        }
 
     .. code-tab:: json
 
@@ -891,7 +900,10 @@ only when using the "aws.v4" authentication scheme:
         use aws.api#unsignedPayload
 
         @unsignedPayload(["aws.v4"])
-        operation PutThings(PutThingsInput) -> PutThingsOutput
+        operation PutThings {
+            input: PutThingsInput,
+            output: PutThingsOutput
+        }
 
     .. code-tab:: json
 
@@ -949,7 +961,7 @@ when serializing an INPUT. For example, given the following Smithy model:
             bar: String
         }
 
-    .. code-tabe:: json
+    .. code-tab:: json
 
         {
             "smithy": "0.5.0",
@@ -970,7 +982,7 @@ when serializing an INPUT. For example, given the following Smithy model:
 
 The serialization of this structure as an input is:
 
-.. code-block::
+::
 
     MyStruct.bar=baz
 
@@ -1108,9 +1120,11 @@ using an ``clientEndpointDiscoveryId``.
           operations: [DescribeEndpoints, GetObject]
         }
 
-        operation DescribeEndpoints(DescribeEndpointsInput)
-            -> DescribeEndpointsOutput
-            errors [InvalidEndpointError]
+        operation DescribeEndpoints {
+            input: DescribeEndpointsInput,
+            output: DescribeEndpointsOutput,
+            errors: [InvalidEndpointError]
+        }
 
         @error("client")
         @httpError(421)
@@ -1140,7 +1154,10 @@ using an ``clientEndpointDiscoveryId``.
         }
 
         @aws.api#clientDiscoveredEndpoint(required: true)
-        operation GetObject(GetObjectInput) -> GetObjectOutput
+        operation GetObject {
+            input: GetObjectInput,
+            output: GetObjectOutput
+        }
 
         structure GetObjectInput {
           @clientEndpointDiscoveryId

diff --git a/docs/source/spec/aws-iam.rst b/docs/source/spec/aws-iam.rst
@@ -46,7 +46,7 @@ Value type
         use aws.iam#actionPermissionDescription
 
         @actionPermissionDescription("This will allow the user to Foo.")
-        operation FooOperation()
+        operation FooOperation {}
 
     .. code-tab:: json
 
@@ -107,7 +107,7 @@ The following example's ``MyResource`` resource has the
         }
 
         @conditionKeys(["aws:region"])
-        operation MyOperation
+        operation MyOperation {}
 
     .. code-tab:: json
 
@@ -434,7 +434,7 @@ operation for it to complete successfully.
         }
 
         @requiredActions(["otherservice:OtherOperation"])
-        operation MyOperation
+        operation MyOperation {}
 
     .. code-tab:: json
 
@@ -530,7 +530,7 @@ Given the following model,
         }
 
         @conditionKeys(["aws:region"])
-        operation MyOperation
+        operation MyOperation {}
 
     .. code-tab:: json