Make IDL commas whitespace and newlines optional

Commas are now treated as whitespace to reduce visual noise in models,
reduce diff noise when changes are made to models, and prevent modelers
from worrying about tricks like trailing commas. Commas are still
allowed because they do make traits and JSON-like node values defined on
a single line easier to read; however, they should be omitted everywhere
else.

The IDL previously required a newline after various statements. This
wasn't grammatically necessary, but was done to force good practice in
models. However, it added complexity to the grammar and parser. While
models should still define all statements on different lines, to simplify
parsers and the grammar, a new line after statements is no longer
required.

README.md

@@ -19,16 +19,16 @@ shapes.
 namespace example.weather
 
 service Weather {
-    version: "2006-03-01",
-    resources: [City],
+    version: "2006-03-01"
+    resources: [City]
     operations: [GetCurrentTime]
 }
 
 resource City {
-    identifiers: { cityId: CityId },
-    read: GetCity,
-    list: ListCities,
-    resources: [Forecast],
+    identifiers: { cityId: CityId }
+    read: GetCity
+    list: ListCities
+    resources: [Forecast]
 }
 
 // See the full example at https://awslabs.github.io/smithy/quickstart.html#complete-example

docs/source/1.0/guides/converting-to-openapi.rst

@@ -696,8 +696,8 @@ For example, given the following Smithy model:
     @restJson1
     @httpApiKeyAuth(name: "x-api-key", in: "header")
     service Foo {
-        version: "2006-03-01",
-        operations: [ExampleOperation],
+        version: "2006-03-01"
+        operations: [ExampleOperation]
     }
 
     @http(method: "GET", uri: "/")
@@ -957,12 +957,13 @@ The following Smithy model:
     @sigv4(name: "service")
     @authorizer("foo")
     @authorizers(
-        foo: {scheme: sigv4, type: "aws", uri: "arn:foo"},
-        baz: {scheme: sigv4, type: "aws", uri: "arn:foo"})
+        foo: {scheme: sigv4, type: "aws", uri: "arn:foo"}
+        baz: {scheme: sigv4, type: "aws", uri: "arn:foo"}
+    )
     service Example {
-      version: "2019-06-17",
-      operations: [OperationA, OperationB],
-      resources: [ResourceA, ResourceB],
+      version: "2019-06-17"
+      operations: [OperationA, OperationB]
+      resources: [ResourceA, ResourceB]
     }
 
     // Inherits the authorizer of the service
@@ -1205,8 +1206,8 @@ The following Smithy model enables API Gateway's API key usage plans on the
     @authorizer("api_key")
     @authorizers(api_key: {scheme: "smithy.api#httpApiKeyAuth"})
     service Example {
-      version: "2019-06-17",
-      operations: [OperationA],
+      version: "2019-06-17"
+      operations: [OperationA]
     }
 
     operation OperationA {}

docs/source/1.0/guides/generating-cloudformation-resources.rst

@@ -116,8 +116,8 @@ generate one Resource Schema with the ``typeName`` of ``AWS:Queues:Queue``.
 
     @service(sdkId: "Queues", cloudFormationName: "Queues")
     service QueueService {
-        version: "2020-07-02",
-        resources: [Queue],
+        version: "2020-07-02"
+        resources: [Queue]
     }
 
 .. important::

docs/source/1.0/guides/model-linters.rst

@@ -187,13 +187,13 @@ Example:
 
     metadata validators = [{
         id: "FooReservedWords"
-        name: "ReservedWords",
+        name: "ReservedWords"
         configuration: {
             reserved: [
                 {
-                    words: ["Codename"],
-                    reason: "This is the internal project name.",
-                },
+                    words: ["Codename"]
+                    reason: "This is the internal project name."
+                }
             ]
         }
     }]
@@ -341,13 +341,13 @@ Example:
     $version: "1.0"
 
     metadata validators = [{
-        name: "StandardOperationVerb",
+        name: "StandardOperationVerb"
         configuration: {
-            verbs: ["Register", "Deregister", "Associate"],
-            prefixes: ["Batch"],
+            verbs: ["Register", "Deregister", "Associate"]
+            prefixes: ["Batch"]
             suggestAlternatives: {
-                "Make": ["Create"],
-                "Transition": ["Update"],
+                "Make": ["Create"]
+                "Transition": ["Update"]
             }
         }
     }]
@@ -676,7 +676,7 @@ example warns each time the word "meow" appears in documentation:
 
     metadata validators = [
         {
-            name: "ForbiddenDocumentation",
+            name: "ForbiddenDocumentation"
             configuration: {
                 forbid: ["meow"]
             }
@@ -695,9 +695,9 @@ example warns each time the word "meow" appears in documentation:
 
         metadata validators = [
             {
-                name: "EmitEachSelector",
-                id: "ForbiddenDocumentation",
-                message: "Documentation uses forbidden text",
+                name: "EmitEachSelector"
+                id: "ForbiddenDocumentation"
+                message: "Documentation uses forbidden text"
                 configuration: {
                     selector: "[trait|documentation*='meow']"
                 }

docs/source/1.0/guides/style-guide.rst

@@ -39,13 +39,15 @@ Smithy models SHOULD resemble the following example:
     structure MyStructure {
         /// Documentation about the member.
         @required
-        foo: String,
+        foo: String
     }
 
     // Example of creating custom traits.
     @trait(selector: "string")
     structure myTrait {}
 
+* Each statement should appear on its own line.
+
 
 File encoding
 -------------
@@ -93,10 +95,65 @@ Whitespace
 4. Members of an object are not horizontally aligned.
 
 
-Trailing commas
----------------
+Commas
+------
+
+Omit commas everywhere except in traits or node values defined on a
+single line.
+
+Do:
+
+.. code-block:: smithy
+
+    $version: "1.0"
+
+    metadata validators = [{
+        name: "StandardOperationVerb"
+        configuration: {
+            verbs: ["Get", "Delete", "Create", "Update"]
+            prefixes: ["Batch"]
+        }
+    }]
+
+    namespace smithy.example.namespace
 
-Include trailing commas to limit diff noise.
+    /// Gets a resource by ID.
+    @http(method: "GET", uri: "/message/{userId}")
+    operation GetMessage {
+        input: GetMessageInput
+        output: GetMessageOutput
+        errors: [
+            ValidationError
+            ResourceNotFoundError
+        ]
+    }
+
+Do not:
+
+.. code-block:: smithy
+
+    $version: "1.0"
+
+    metadata validators = [{
+        name: "StandardOperationVerb",
+        configuration: {
+            verbs: ["Get" "Delete" "Create" "Update"],
+            prefixes: ["Batch"],
+        },
+    },]
+
+    namespace smithy.example.namespace
+
+    /// Gets a resource by ID.
+    @http(method: "GET" uri: "/message/{userId}")
+    operation GetMessage {
+        input: GetMessageInput,
+        output: GetMessageOutput,
+        errors: [
+            ValidationError,
+            ResourceNotFoundError,
+        ],
+    }
 
 
 Naming

docs/source/1.0/spec/aws/amazon-apigateway.rst

@@ -199,14 +199,15 @@ An *authorizer* definition is a structure that supports the following members:
         @authorizer("arbitrary-name")
         @authorizers(
             "arbitrary-name": {
-                scheme: sigv4,
-                type: "request",
-                uri: "arn:foo:baz",
-                credentials: "arn:foo:bar",
-                identitySource: "mapping.expression",
-                identityValidationExpression: "[A-Z]+",
+                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"
         }

docs/source/1.0/spec/aws/aws-auth.rst

@@ -54,7 +54,7 @@ Trait value
         @sigv4(name: "foobaz")
         @restJson1
         service FooBaz {
-            version: "2018-03-17",
+            version: "2018-03-17"
         }
 
     .. code-tab:: json
@@ -109,7 +109,7 @@ operation MUST NOT be used as part of the request signature calculation:
 
         @unsignedPayload
         operation PutThings {
-            input: PutThingsInput,
+            input: PutThingsInput
             output: PutThingsOutput
         }
 
@@ -182,7 +182,7 @@ Trait value
         providerArns: ["arn:aws:cognito-idp:us-east-1:123:userpool/123"])
     @restJson1
     service FooBaz {
-        version: "2018-03-17",
+        version: "2018-03-17"
     }