smithy-lang · srchase · Feb 24, 2020 · Feb 21, 2020 · Feb 24, 2020 · Feb 24, 2020
diff --git a/docs/source/spec/core.rst b/docs/source/spec/core.rst
@@ -5550,6 +5550,30 @@ Value type
         }
 
 
+.. _unstable-trait:
+
+``_unstable`` trait
+---------------
+
+Summary
+    Indicates a shape is unstable and MAY change in the future. This trait can
+    be applied to trait definitions to indicate that a trait is unstable or
+    experimental. If possible, code generators SHOULD use this trait to warn
+    when code generated from unstable features are used.
+Trait selector
+    ``*``
+
+Value type
+    Annotation trait
+
+.. tabs::
+
+    .. code-tab:: smithy
+
+        @unstable
+        string MyString
+
+
 .. _endpoint-traits:
 
 Endpoint Traits

diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/Prelude.java
@@ -87,6 +87,7 @@
 import software.amazon.smithy.model.traits.TitleTrait;
 import software.amazon.smithy.model.traits.TraitDefinition;
 import software.amazon.smithy.model.traits.UniqueItemsTrait;
+import software.amazon.smithy.model.traits.UnstableTrait;
 import software.amazon.smithy.model.traits.XmlAttributeTrait;
 import software.amazon.smithy.model.traits.XmlFlattenedTrait;
 import software.amazon.smithy.model.traits.XmlNameTrait;
@@ -193,6 +194,7 @@ public final class Prelude {
             TitleTrait.ID,
             TraitDefinition.ID,
             UniqueItemsTrait.ID,
+            UnstableTrait.ID,
             XmlAttributeTrait.ID,
             XmlFlattenedTrait.ID,
             XmlNameTrait.ID,

diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java b/smithy-model/src/main/java/software/amazon/smithy/model/traits/UnstableTrait.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.model.traits;
+
+import software.amazon.smithy.model.SourceLocation;
+import software.amazon.smithy.model.shapes.ShapeId;
+
+/**
+ * Marks a shape as unstable.
+ */
+public final class UnstableTrait extends BooleanTrait {
+    public static final ShapeId ID = ShapeId.from("smithy.api#unstable");
+
+    public UnstableTrait(SourceLocation sourceLocation) {
+        super(ID, sourceLocation);
+    }
+
+    public UnstableTrait() {
+        this(SourceLocation.NONE);
+    }
+
+    public static final class Provider extends BooleanTrait.Provider<UnstableTrait> {
+        public Provider() {
+            super(ID, UnstableTrait::new);
+        }
+    }
+}
diff --git a/.../main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java b/.../main/java/software/amazon/smithy/model/validation/validators/UnstableTraitValidator.java
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.model.validation.validators;
+
+import static java.lang.String.format;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.model.traits.UnstableTrait;
+import software.amazon.smithy.model.validation.AbstractValidator;
+import software.amazon.smithy.model.validation.ValidationEvent;
+
+/**
+ * Emits a validation event if a model contains shapes that are bound to unstable traits.
+ */
+public final class UnstableTraitValidator extends AbstractValidator {
+    @Override
+    public List<ValidationEvent> validate(Model model) {
+        Set<ShapeId> unstableTraits = model.getTraitShapes().stream()
+                .filter(trait -> trait.hasTrait(UnstableTrait.class))
+                .map(Shape::getId)
+                .collect(Collectors.toSet());
+
+        return model.shapes()
+                .flatMap(shape -> validateShape(shape, unstableTraits).stream())
+                .collect(Collectors.toList());
+    }
+
+    private List<ValidationEvent> validateShape(Shape shape, Set<ShapeId> unstableTraits) {
+        List<ValidationEvent> events = new ArrayList<>();
+        shape.getAllTraits().forEach((shapeId, trait) -> {
+            if (!unstableTraits.contains(trait.toShapeId())) {
+                return;
+            }
+            events.add(warning(shape, trait, format("This shape applies a trait that is unstable: %s",
+                    trait.toShapeId())));
+        });
+        return events;
+    }
+}
diff --git a/...del/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService b/...del/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService
@@ -42,6 +42,7 @@ software.amazon.smithy.model.traits.TimestampFormatTrait$Provider
 software.amazon.smithy.model.traits.TitleTrait$Provider
 software.amazon.smithy.model.traits.TraitDefinition$Provider
 software.amazon.smithy.model.traits.UniqueItemsTrait$Provider
+software.amazon.smithy.model.traits.UnstableTrait$Provider
 software.amazon.smithy.model.traits.XmlAttributeTrait$Provider
 software.amazon.smithy.model.traits.XmlFlattenedTrait$Provider
 software.amazon.smithy.model.traits.XmlNamespaceTrait$Provider

diff --git a/...el/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator b/...el/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator
@@ -33,4 +33,5 @@ software.amazon.smithy.model.validation.validators.TraitConflictValidator
 software.amazon.smithy.model.validation.validators.TraitTargetValidator
 software.amazon.smithy.model.validation.validators.TraitValueValidator
 software.amazon.smithy.model.validation.validators.UnstableFeatureValidator
+software.amazon.smithy.model.validation.validators.UnstableTraitValidator
 software.amazon.smithy.model.validation.validators.XmlNamespaceTraitValidator
diff --git a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude-traits.smithy
@@ -358,6 +358,10 @@ structure required {}
 @trait(selector: "list")
 structure uniqueItems {}
 
+/// Indicates that the shape is unstable and could change in the future.
+@trait()
+structure unstable {}
+
 /// The paginated trait indicates that an operation intentionally limits the number
 /// of results returned in a single response and that multiple invocations might be
 /// necessary to retrieve all results.

diff --git a/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java b/smithy-model/src/test/java/software/amazon/smithy/model/traits/UnstableTraitTest.java
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.smithy.model.traits;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.instanceOf;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.shapes.ShapeId;
+
+public class UnstableTraitTest {
+    @Test
+    public void loadsTrait() {
+        TraitFactory provider = TraitFactory.createServiceFactory();
+        Optional<Trait> trait = provider.createTrait(
+                ShapeId.from("smithy.api#unstable"), ShapeId.from("ns.qux#foo"), Node.from(true));
+
+        assertTrue(trait.isPresent());
+        assertThat(trait.get(), instanceOf(UnstableTrait.class));
+        assertThat(trait.get().toNode(), equalTo(Node.from(true)));
+    }
+}
diff --git a/...ources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors b/...ources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.errors
@@ -0,0 +1 @@
+[WARNING] ns.foo#MyString: This shape applies a trait that is unstable: ns.foo#fooTrait | UnstableTrait
diff --git a/...esources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json b/...esources/software/amazon/smithy/model/errorfiles/validators/unstable-trait-validator.json
@@ -0,0 +1,31 @@
+{
+  "smithy": "0.5.0",
+  "shapes": {
+    "ns.foo#MyString": {
+      "type": "string",
+      "traits": {
+        "ns.foo#fooTrait": { },
+        "ns.foo#barTrait": { }
+      }
+    },
+    "ns.foo#fooTrait": {
+      "type": "structure",
+      "members": { },
+      "traits": {
+        "smithy.api#unstable": { },
+        "smithy.api#trait": {
+          "selector": "*"
+        }
+      }
+    },
+    "ns.foo#barTrait": {
+      "type": "structure",
+      "members": { },
+      "traits": {
+        "smithy.api#trait": {
+          "selector": "*"
+        }
+      }
+    }
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		[WARNING] ns.foo#MyString: This shape applies a trait that is unstable: ns.foo#fooTrait \| UnstableTrait