Add error support to examples trait

docs/source/1.0/spec/core/documentation-traits.rst

@@ -202,6 +202,10 @@ Each ``example`` trait value is a structure with the following members:
       - Provides example output parameters for the operation. Each key is
         the name of a top-level output structure member, and each value is the
         value of the member.
+    * - error
+      - :ref:`examples-ErrorExample-structure`
+      - Provides an error shape ID and example error parameters for the
+        operation.
 
 The values provided for the ``input`` and ``output`` members MUST be
 compatible with the shapes and constraints of the corresponding structure.
@@ -215,7 +219,8 @@ These values use the same semantics and format as
         @readonly
         operation MyOperation {
             input: MyOperationInput,
-            output: MyOperationOutput
+            output: MyOperationOutput,
+            errors: [MyOperationError]
         }
 
         apply MyOperation @examples([
@@ -237,9 +242,48 @@ These values use the same semantics and format as
                     status: "PENDING",
                 }
             },
+            {
+                title: "Error example for MyOperation",
+                input: {
+                    foo: 1,
+                },
+                error: {
+                    shapeId: MyOperationError,
+                    content: {
+                        message: "Invalid 'foo'",
+                    }
+                }
+            },
         ])
 
 
+.. _examples-ErrorExample-structure:
+
+``ErrorExample`` structure
+==========================
+
+The ``ErrorExample`` structure defines an error example using the following
+members:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 10 10 80
+
+    * - Property
+      - Type
+      - Description
+    * - shapeId
+      - :ref:`shape-id`
+      - The shape ID of the error in this example. This shape ID MUST be of
+        a structure shape with the error trait. The structure shape MUST be
+        bound as an error to the operation this example trait is applied to.
+    * - content
+      - ``document``
+      - Provides example error parameters for the operation. Each key is
+        the name of a top-level error structure member, and each value is the
+        value of the member.
+
+
 .. smithy-trait:: smithy.api#externalDocumentation
 .. _externalDocumentation-trait:
 

smithy-model/src/main/java/software/amazon/smithy/model/traits/ExamplesTrait.java

@@ -100,12 +100,14 @@ public static final class Example implements ToNode, ToSmithyBuilder<Example> {
         private final String documentation;
         private final ObjectNode input;
         private final ObjectNode output;
+        private final ErrorExample error;
 
         private Example(Builder builder) {
             this.title = Objects.requireNonNull(builder.title, "Example title must not be null");
             this.documentation = builder.documentation;
             this.input = builder.input;
             this.output = builder.output;
+            this.error = builder.error;
         }
 
         /**
@@ -136,11 +138,19 @@ public ObjectNode getOutput() {
             return output;
         }
 
+        /**
+         * @return Gets the error example.
+         */
+        public Optional<ErrorExample> getError() {
+            return Optional.ofNullable(error);
+        }
+
         @Override
         public Node toNode() {
             ObjectNode.Builder builder = Node.objectNodeBuilder()
                     .withMember("title", Node.from(title))
-                    .withOptionalMember("documentation", getDocumentation().map(Node::from));
+                    .withOptionalMember("documentation", getDocumentation().map(Node::from))
+                    .withOptionalMember("error", getError().map(ErrorExample::toNode));
 
             if (!input.isEmpty()) {
                 builder.withMember("input", input);
@@ -154,7 +164,7 @@ public Node toNode() {
 
         @Override
         public Builder toBuilder() {
-            return new Builder().documentation(documentation).title(title).input(input).output(output);
+            return new Builder().documentation(documentation).title(title).input(input).output(output).error(error);
         }
 
         public static Builder builder() {
@@ -169,6 +179,7 @@ public static final class Builder implements SmithyBuilder<Example> {
             private String documentation;
             private ObjectNode input = Node.objectNode();
             private ObjectNode output = Node.objectNode();
+            private ErrorExample error;
 
             @Override
             public Example build() {
@@ -194,6 +205,79 @@ public Builder output(ObjectNode output) {
                 this.output = output;
                 return this;
             }
+
+            public Builder error(ErrorExample error) {
+                this.error = error;
+                return this;
+            }
+        }
+    }
+
+    public static final class ErrorExample implements ToNode, ToSmithyBuilder<ErrorExample> {
+        private final ShapeId shapeId;
+        private final ObjectNode content;
+
+        public ErrorExample(Builder builder) {
+            this.shapeId = builder.shapeId;
+            this.content = builder.content;
+        }
+
+        public static ErrorExample fromNode(ObjectNode node) {
+            return builder()
+                    .shapeId(node.expectStringMember("shapeId").expectShapeId())
+                    .content(node.expectObjectMember("content"))
+                    .build();
+        }
+
+        /**
+         * @return Gets the error shape id for the example.
+         */
+        public ShapeId getShapeId() {
+            return shapeId;
+        }
+
+        /**
+         * @return Gets the error object.
+         */
+        public ObjectNode getContent() {
+            return content;
+        }
+
+        @Override
+        public Node toNode() {
+            return ObjectNode.objectNodeBuilder()
+                    .withMember("shapeId", shapeId.toString())
+                    .withMember("content", content)
+                    .build();
+        }
+
+        @Override
+        public SmithyBuilder<ErrorExample> toBuilder() {
+            return builder().content(content).shapeId(shapeId);
+        }
+
+        public static Builder builder() {
+            return new Builder();
+        }
+
+        public static final class Builder implements SmithyBuilder<ErrorExample> {
+            private ShapeId shapeId;
+            private ObjectNode content = Node.objectNode();
+
+            @Override
+            public ErrorExample build() {
+                return new ErrorExample(this);
+            }
+
+            public Builder shapeId(ShapeId shapeId) {
+                this.shapeId = shapeId;
+                return this;
+            }
+
+            public Builder content(ObjectNode content) {
+                this.content = content;
+                return this;
+            }
         }
     }
 
@@ -213,12 +297,15 @@ public ExamplesTrait createTrait(ShapeId target, Node value) {
         }
 
         private static Example exampleFromNode(ObjectNode node) {
-            return Example.builder()
+            Example.Builder builder = Example.builder()
                     .title(node.expectStringMember("title").getValue())
                     .documentation(node.getStringMember("documentation").map(StringNode::getValue).orElse(null))
                     .input(node.getMember("input").map(Node::expectObjectNode).orElseGet(Node::objectNode))
-                    .output(node.getMember("output").map(Node::expectObjectNode).orElseGet(Node::objectNode))
-                    .build();
+                    .output(node.getMember("output").map(Node::expectObjectNode).orElseGet(Node::objectNode));
+
+            node.getObjectMember("error").map(ErrorExample::fromNode).map(builder::error);
+
+            return builder.build();
         }
     }
 }

smithy-model/src/main/java/software/amazon/smithy/model/validation/validators/ExamplesTraitValidator.java

@@ -17,6 +17,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.node.ObjectNode;
 import software.amazon.smithy.model.shapes.OperationShape;
@@ -53,9 +54,11 @@ private List<ValidationEvent> validateExamples(Model model, OperationShape shape
                     events.addAll(input.accept(validator));
                 });
             } else if (!example.getInput().isEmpty()) {
-                events.add(error(shape, trait, String.format("Input parameters provided for operation with no "
-                                                             + "input structure members: `%s`", example.getTitle())));
+                events.add(error(shape, trait, String.format(
+                        "Input parameters provided for operation with no input structure members: `%s`",
+                        example.getTitle())));
             }
+
             if (shape.getOutput().isPresent()) {
                 model.getShape(shape.getOutput().get()).ifPresent(output -> {
                     NodeValidationVisitor validator = createVisitor(
@@ -67,6 +70,20 @@ private List<ValidationEvent> validateExamples(Model model, OperationShape shape
                         "Output parameters provided for operation with no output structure members: `%s`",
                         example.getTitle())));
             }
+
+            if (example.getError().isPresent()) {
+                ExamplesTrait.ErrorExample errorExample = example.getError().get();
+                Optional<Shape> errorShape = model.getShape(errorExample.getShapeId());
+                if (errorShape.isPresent() && shape.getErrors().contains(errorExample.getShapeId())) {
+                    NodeValidationVisitor validator = createVisitor(
+                            "error", errorExample.getContent(), model, shape, example);
+                    events.addAll(errorShape.get().accept(validator));
+                } else {
+                    events.add(error(shape, trait, String.format(
+                        "Error parameters provided for operation without the `%s` error: `%s`",
+                            errorExample.getShapeId(), example.getTitle())));
+                }
+            }
         }
 
         return events;

smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy

@@ -231,7 +231,17 @@ structure Example {
 
     input: Document,
 
-    output: Document
+    output: Document,
+
+    error: ExampleError,
+}
+
+@private
+structure ExampleError {
+    @idRef(selector: "structure[trait|error]")
+    shapeId: String,
+
+    content: Document,
 }
 
 /// Indicates that a structure shape represents an error.

smithy-model/src/test/java/software/amazon/smithy/model/traits/ExamplesTraitTest.java

@@ -37,7 +37,10 @@ public void loadsTrait() {
                         .withMember("title", Node.from("qux"))
                         .withMember("documentation", Node.from("docs"))
                         .withMember("input", Node.objectNode().withMember("a", Node.from("b")))
-                        .withMember("output", Node.objectNode().withMember("c", Node.from("d"))));
+                        .withMember("output", Node.objectNode().withMember("c", Node.from("d")))
+                        .withMember("error", Node.objectNode()
+                                .withMember(Node.from("shapeId"), Node.from("smithy.example#FooError"))
+                                .withMember(Node.from("content"), Node.objectNode().withMember("e", Node.from("f")))));
 
         Optional<Trait> trait = provider.createTrait(
                 ShapeId.from("smithy.api#examples"), ShapeId.from("ns.qux#foo"), node);

smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/examples-trait-validator.errors

@@ -1,5 +1,7 @@
 [ERROR] ns.foo#Operation2: Input parameters provided for operation with no input structure members: `Testing 3` | ExamplesTrait
 [ERROR] ns.foo#Operation2: Output parameters provided for operation with no output structure members: `Testing 3` | ExamplesTrait
+[ERROR] ns.foo#Operation2: Error parameters provided for operation without the `ns.foo#OperationError` error: `Testing 3` | ExamplesTrait
 [ERROR] ns.foo#Operation: Example input of `Testing 2`: Missing required structure member `foo` for `ns.foo#OperationInput` | ExamplesTrait
 [WARNING] ns.foo#Operation: Example output of `Testing 2`: Invalid structure member `additional` found for `ns.foo#OperationOutput` | ExamplesTrait
 [ERROR] ns.foo#Operation: Example output of `Testing 2`: Missing required structure member `bam` for `ns.foo#OperationOutput` | ExamplesTrait
+[WARNING] ns.foo#Operation: Example error of `Testing 1`: Invalid structure member `extra` found for `ns.foo#OperationError` | ExamplesTrait

smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/examples-trait-validator.json

@@ -9,6 +9,11 @@
             "output": {
                 "target": "ns.foo#OperationOutput"
             },
+            "errors": [
+                {
+                    "target": "ns.foo#OperationError"
+                }
+            ],
             "traits": {
                 "smithy.api#readonly": {},
                 "smithy.api#examples": [
@@ -19,6 +24,13 @@
                         },
                         "output": {
                             "bam": "value2"
+                        },
+                        "error": {
+                            "shapeId": "ns.foo#OperationError",
+                            "content": {
+                                "bat": "baz",
+                                "extra": "field"
+                            }
                         }
                     },
                     {
@@ -33,6 +45,17 @@
                 ]
             }
         },
+        "ns.foo#OperationError": {
+            "type": "structure",
+            "members": {
+                "bat": {
+                    "target": "ns.foo#String"
+                }
+            },
+            "traits": {
+                "smithy.api#error": "client"
+            }
+        },
         "ns.foo#OperationInput": {
             "type": "structure",
             "members": {
@@ -69,7 +92,13 @@
                             "foo": "baz"
                         },
                         "output": {
-                            "foo": "baz"
+                            "bam": "baz"
+                        },
+                        "error": {
+                            "shapeId": "ns.foo#OperationError",
+                            "content": {
+                                "bat": "baz"
+                            }
                         }
                     }
                 ]