Add enumDefault trait

Author: JordonPhillips

designs/enum-shapes.md

@@ -81,12 +81,12 @@ structure GetFooInput {
 }
 ```
 
-To account for this, enums MAY define a default member by making the
-`@enumValue` of the member "":
+To account for this, enums MAY define a default member by setting the
+`@enumDefault` trait on a member:
 
 ```
 enum Suit {
-    @enumValue(string: "")
+    @enumDefault
     UNKNOWN
 
     @enumValue(string: "diamond")
@@ -121,6 +121,10 @@ structure GetFooInput {
 }
 ```
 
+#### enums must define at least one member
+
+Every enum shape MUST define at least one member.
+
 ### intEnum shape
 
 An intEnum is used to represent an enumerated set of integer values. The
@@ -159,11 +163,11 @@ structure GetFooInput {
 ```
 
 intEnums MAY define a member to represent the default value of the shape by
-making the `@enumValue` of the member 0:
+setting the `@enumDefault` trait on a member:
 
 ```
 intEnum FaceCard {
-    @enumValue(int: 0)
+    @enumDefault
     UNKNOWN
 
     @enumValue(int: 1)
@@ -198,6 +202,10 @@ default dispatch to the integer shape when an intEnum is encountered. This
 both makes adding enums backward compatible, and allows implementations that
 do not support enums at all to ignore them.
 
+#### intEnums must define at least one member
+
+Every intEnum shape MUST define at least one member.
+
 ### Smithy taxonomy updates
 
 Both enum and intEnum are considered simple shapes though they have members.

smithy-model/src/main/java/software/amazon/smithy/model/shapes/EnumShape.java

@@ -22,6 +22,7 @@
 import java.util.Optional;
 import java.util.function.Consumer;
 import software.amazon.smithy.model.SourceException;
+import software.amazon.smithy.model.traits.EnumDefaultTrait;
 import software.amazon.smithy.model.traits.EnumDefinition;
 import software.amazon.smithy.model.traits.EnumTrait;
 import software.amazon.smithy.model.traits.EnumValueTrait;
@@ -57,7 +58,11 @@ public Map<String, String> getEnumValues() {
         if (enumValues == null) {
             Map<String, String> values = new LinkedHashMap<>(members.size());
             for (MemberShape member : members()) {
-                values.put(member.getMemberName(), member.expectTrait(EnumValueTrait.class).getStringValue().get());
+                if (member.hasTrait(EnumDefaultTrait.ID)) {
+                    values.put(member.getMemberName(), "");
+                    continue;
+                }
+                values.put(member.getMemberName(), member.expectTrait(EnumValueTrait.class).expectStringValue());
             }
             enumValues = MapUtils.orderedCopyOf(values);
         }
@@ -282,7 +287,7 @@ public Builder addMember(MemberShape member) {
                         "Enum members may only target `smithy.api#Unit`, but found `%s`", member.getTarget()
                 ), getSourceLocation());
             }
-            if (!member.hasTrait(EnumValueTrait.ID)) {
+            if (!member.hasTrait(EnumValueTrait.ID) && !member.hasTrait(EnumDefaultTrait.ID)) {
                 member = member.toBuilder()
                         .addTrait(EnumValueTrait.builder().stringValue(member.getMemberName()).build())
                         .build();
@@ -328,6 +333,40 @@ public Builder addMember(String memberName, String enumValue, Consumer<MemberSha
             return addMember(builder.build());
         }
 
+        /**
+         * Adds the default member to the builder.
+         *
+         * @param memberName Member name to add.
+         * @return Returns the builder.
+         */
+        public Builder addDefaultMember(String memberName) {
+            return addDefaultMember(memberName, null);
+        }
+
+        /**
+         * Adds the default member to the builder.
+         *
+         * @param memberName Member name to add.
+         * @param memberUpdater Consumer that can update the created member shape.
+         * @return Returns the builder.
+         */
+        public Builder addDefaultMember(String memberName, Consumer<MemberShape.Builder> memberUpdater) {
+            if (getId() == null) {
+                throw new IllegalStateException("An id must be set before setting a member with a target");
+            }
+
+            MemberShape.Builder builder = MemberShape.builder()
+                    .target(UnitTypeTrait.UNIT)
+                    .id(getId().withMember(memberName))
+                    .addTrait(new EnumDefaultTrait());
+
+            if (memberUpdater != null) {
+                memberUpdater.accept(builder);
+            }
+
+            return addMember(builder.build());
+        }
+
         /**
          * Removes a member by name.
          *

smithy-model/src/main/java/software/amazon/smithy/model/shapes/IntEnumShape.java

@@ -22,6 +22,7 @@
 import java.util.Optional;
 import java.util.function.Consumer;
 import software.amazon.smithy.model.SourceException;
+import software.amazon.smithy.model.traits.EnumDefaultTrait;
 import software.amazon.smithy.model.traits.EnumValueTrait;
 import software.amazon.smithy.model.traits.UnitTypeTrait;
 import software.amazon.smithy.utils.BuilderRef;
@@ -53,7 +54,11 @@ public Map<String, Integer> getEnumValues() {
         if (enumValues == null) {
             Map<String, Integer> values = new LinkedHashMap<>(members.size());
             for (MemberShape member : members()) {
-                values.put(member.getMemberName(), member.expectTrait(EnumValueTrait.class).getIntValue().get());
+                if (member.hasTrait(EnumDefaultTrait.ID)) {
+                    values.put(member.getMemberName(), 0);
+                    continue;
+                }
+                values.put(member.getMemberName(), member.expectTrait(EnumValueTrait.class).expectIntValue());
             }
             enumValues = MapUtils.orderedCopyOf(values);
         }
@@ -235,6 +240,40 @@ public Builder addMember(String memberName, int enumValue, Consumer<MemberShape.
             return addMember(builder.build());
         }
 
+        /**
+         * Adds the default member to the builder.
+         *
+         * @param memberName Member name to add.
+         * @return Returns the builder.
+         */
+        public Builder addDefaultMember(String memberName) {
+            return addDefaultMember(memberName, null);
+        }
+
+        /**
+         * Adds the default member to the builder.
+         *
+         * @param memberName Member name to add.
+         * @param memberUpdater Consumer that can update the created member shape.
+         * @return Returns the builder.
+         */
+        public Builder addDefaultMember(String memberName, Consumer<MemberShape.Builder> memberUpdater) {
+            if (getId() == null) {
+                throw new IllegalStateException("An id must be set before setting a member with a target");
+            }
+
+            MemberShape.Builder builder = MemberShape.builder()
+                    .target(UnitTypeTrait.UNIT)
+                    .id(getId().withMember(memberName))
+                    .addTrait(new EnumDefaultTrait());
+
+            if (memberUpdater != null) {
+                memberUpdater.accept(builder);
+            }
+
+            return addMember(builder.build());
+        }
+
         /**
          * Removes a member by name.
          *

smithy-model/src/main/java/software/amazon/smithy/model/shapes/NamedMembers.java

@@ -19,7 +19,7 @@
 import java.util.Map;
 import java.util.Optional;
 
-interface NamedMembers {
+public interface NamedMembers {
 
     /**
      * Gets the members of the shape, including mixin members.

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

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2022 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 java.util.Collections;
+import software.amazon.smithy.model.SourceLocation;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.shapes.EnumShape;
+import software.amazon.smithy.model.shapes.IntEnumShape;
+import software.amazon.smithy.model.shapes.ShapeId;
+
+/**
+ * Indicates that an enum member is the default value member.
+ *
+ * On an {@link IntEnumShape} this implies the enum value is 0. On an
+ * {@link  EnumShape} this implies the enum value is an empty string.
+ */
+public class EnumDefaultTrait extends AnnotationTrait {
+    public static final ShapeId ID = ShapeId.from("smithy.api#enumDefault");
+
+    public EnumDefaultTrait(ObjectNode node) {
+        super(ID, node);
+    }
+
+    public EnumDefaultTrait(SourceLocation location) {
+        this(new ObjectNode(Collections.emptyMap(), location));
+    }
+
+    public EnumDefaultTrait() {
+        this(Node.objectNode());
+    }
+
+    public static final class Provider extends AnnotationTrait.Provider<EnumDefaultTrait> {
+        public Provider() {
+            super(ID, EnumDefaultTrait::new);
+        }
+    }
+}

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

@@ -186,9 +186,11 @@ public boolean canConvertToMember(boolean withSynthesizedNames) {
     public static EnumDefinition fromMember(MemberShape member) {
         EnumDefinition.Builder builder = EnumDefinition.builder().name(member.getMemberName());
 
-        EnumValueTrait valueTrait = member.expectTrait(EnumValueTrait.class);
-        if (valueTrait.getStringValue().isPresent()) {
-            builder.value(valueTrait.getStringValue().get());
+        Optional<String> traitValue = member.getTrait(EnumValueTrait.class).flatMap(EnumValueTrait::getStringValue);
+        if (member.hasTrait(EnumDefaultTrait.class)) {
+            builder.value("");
+        } else if (traitValue.isPresent()) {
+            builder.value(traitValue.get());
         } else {
             throw new IllegalStateException("Enum definitions can only be made for string enums.");
         }

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

@@ -17,6 +17,7 @@
 
 import java.util.Optional;
 import software.amazon.smithy.model.SourceException;
+import software.amazon.smithy.model.node.ExpectationNotMetException;
 import software.amazon.smithy.model.node.Node;
 import software.amazon.smithy.model.node.NumberNode;
 import software.amazon.smithy.model.node.ObjectNode;
@@ -25,6 +26,9 @@
 import software.amazon.smithy.utils.SmithyBuilder;
 import software.amazon.smithy.utils.ToSmithyBuilder;
 
+/**
+ * Sets the value for an enum member.
+ */
 public final class EnumValueTrait extends AbstractTrait implements ToSmithyBuilder<EnumValueTrait> {
     public static final ShapeId ID = ShapeId.from("smithy.api#enumValue");
 
@@ -43,14 +47,48 @@ private EnumValueTrait(Builder builder) {
         }
     }
 
+    /**
+     * Gets the string value if a string value was set.
+     *
+     * @return Optionally returns the string value.
+     */
     public Optional<String> getStringValue() {
         return Optional.ofNullable(string);
     }
 
+    /**
+     * Gets the string value.
+     *
+     * @return Returns the string value.
+     * @throws ExpectationNotMetException if the string value was not set.
+     */
+    public String expectStringValue() {
+        return getStringValue().orElseThrow(() -> new ExpectationNotMetException(
+                "Expected string value was not set.", this
+        ));
+    }
+
+    /**
+     * Gets the int value if an int value was set.
+     *
+     * @return Returns the set int value.
+     */
     public Optional<Integer> getIntValue() {
         return Optional.ofNullable(integer);
     }
 
+    /**
+     * Gets the int value.
+     *
+     * @return Returns the int value.
+     * @throws ExpectationNotMetException if the int value was not set.
+     */
+    public int expectIntValue() {
+        return getIntValue().orElseThrow(() -> new ExpectationNotMetException(
+                "Expected integer value was not set.", this
+        ));
+    }
+
     public static final class Provider extends AbstractTrait.Provider {
         public Provider() {
             super(ID);

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

@@ -27,6 +27,7 @@
 import software.amazon.smithy.model.shapes.IntEnumShape;
 import software.amazon.smithy.model.shapes.MemberShape;
 import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.model.traits.EnumDefaultTrait;
 import software.amazon.smithy.model.traits.EnumValueTrait;
 import software.amazon.smithy.model.validation.AbstractValidator;
 import software.amazon.smithy.model.validation.ValidationEvent;
@@ -52,15 +53,25 @@ public List<ValidationEvent> validate(Model model) {
     private void validateEnumShape(List<ValidationEvent> events, EnumShape shape) {
         Set<String> values = new HashSet<>();
         for (MemberShape member : shape.members()) {
+            if (member.hasTrait(EnumDefaultTrait.ID)) {
+                continue;
+            }
             Optional<String> value = member.expectTrait(EnumValueTrait.class).getStringValue();
             if (!value.isPresent()) {
                 events.add(error(member, member.expectTrait(EnumValueTrait.class),
                         "The enumValue trait must use the string option when applied to enum shapes."));
-            } else if (!values.add(value.get())) {
-                events.add(error(member, String.format(
-                        "Multiple enum members found with duplicate value `%s`",
-                        value.get()
-                )));
+            } else {
+                if (!values.add(value.get())) {
+                    events.add(error(member, String.format(
+                            "Multiple enum members found with duplicate value `%s`",
+                            value.get()
+                    )));
+                }
+                if (value.get().equals("")) {
+                    events.add(error(member, "enum values may not be empty because an empty string is the "
+                            + "default value of enum shapes. Instead, use `smithy.api#enumDefault` to set an "
+                            + "explicit name for the default value."));
+                }
             }
             validateEnumMemberName(events, member);
         }
@@ -69,6 +80,9 @@ private void validateEnumShape(List<ValidationEvent> events, EnumShape shape) {
     private void validateIntEnumShape(List<ValidationEvent> events, IntEnumShape shape) {
         Set<Integer> values = new HashSet<>();
         for (MemberShape member : shape.members()) {
+            if (member.hasTrait(EnumDefaultTrait.ID)) {
+                continue;
+            }
             if (!member.hasTrait(EnumValueTrait.ID)) {
                 events.add(missingIntEnumValue(member, member));
             } else if (!member.expectTrait(EnumValueTrait.class).getIntValue().isPresent()) {
@@ -81,6 +95,11 @@ private void validateIntEnumShape(List<ValidationEvent> events, IntEnumShape sha
                             value
                     )));
                 }
+                if (value == 0) {
+                    events.add(error(member, "intEnum values may not be set to 0 because 0 is the "
+                            + "default value of intEnum shapes. Instead, use `smithy.api#enumDefault` to set an "
+                            + "explicit name for the default value."));
+                }
             }
             validateEnumMemberName(events, member);
         }