Add aws.api#clientOptional trait

This trait helps existing AWS services transition from the more relaxed
semantics they've previously had around nullability to a future where
nullability can be relied on for things like code generation and
deserialization.

smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/AwsClientNullableIndex.java

@@ -0,0 +1,51 @@
+/*
+ * 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.aws.traits;
+
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.knowledge.NullableIndex;
+import software.amazon.smithy.model.shapes.MemberShape;
+
+/**
+ * Checks if a member is nullable by taking into account the
+ * {@link ClientOptionalTrait} and base logic of NullableIndex.
+ *
+ * <p>This index extends from {@link NullableIndex} so that code generators
+ * that need to conditionally honor the {@link ClientOptionalTrait} can
+ * choose which specific NullableIndex they use during codegen.
+ */
+public final class AwsClientNullableIndex extends NullableIndex {
+
+    public AwsClientNullableIndex(Model model) {
+        super(model);
+    }
+
+    public static AwsClientNullableIndex of(Model model) {
+        return model.getKnowledge(AwsClientNullableIndex.class, AwsClientNullableIndex::new);
+    }
+
+    /**
+     * Checks if the given member should be generated as optional by an AWS client
+     * that respects the {@link ClientOptionalTrait} and the base rules of Smithy's
+     * {@link NullableIndex}.
+     *
+     * @param member Member to check.
+     * @return Returns true if the shape should be optional in generated clients.
+     */
+    public boolean isMemberOptional(MemberShape member) {
+        return member.hasTrait(ClientOptionalTrait.class) || super.isMemberOptional(member);
+    }
+}

smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/ClientOptionalTrait.java

@@ -0,0 +1,43 @@
+/*
+ * 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.aws.traits;
+
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.model.traits.AnnotationTrait;
+
+/**
+ * Indicates that a structure member should be treated as optional in
+ * generated AWS clients, ignoring any required or default traits.
+ */
+public final class ClientOptionalTrait extends AnnotationTrait {
+    public static final ShapeId ID = ShapeId.from("aws.api#clientOptional");
+
+    public ClientOptionalTrait(ObjectNode node) {
+        super(ID, node);
+    }
+
+    public ClientOptionalTrait() {
+        this(Node.objectNode());
+    }
+
+    public static final class Provider extends AnnotationTrait.Provider<ClientOptionalTrait> {
+        public Provider() {
+            super(ID, ClientOptionalTrait::new);
+        }
+    }
+}

smithy-aws-traits/src/main/resources/META-INF/services/software.amazon.smithy.model.traits.TraitService

@@ -1,6 +1,7 @@
 software.amazon.smithy.aws.traits.ArnTrait$Provider
 software.amazon.smithy.aws.traits.ArnReferenceTrait$Provider
 software.amazon.smithy.aws.traits.auth.CognitoUserPoolsTrait$Provider
+software.amazon.smithy.aws.traits.ClientOptionalTrait$Provider
 software.amazon.smithy.aws.traits.ControlPlaneTrait$Provider
 software.amazon.smithy.aws.traits.DataPlaneTrait$Provider
 software.amazon.smithy.aws.traits.DataTrait$Provider

smithy-aws-traits/src/main/resources/META-INF/smithy/aws.api.json

@@ -210,6 +210,15 @@
                 },
                 "smithy.api#documentation": "Configures endpoint discovery for the service."
             }
+        },
+        "aws.api#clientOptional": {
+            "type": "structure",
+            "traits": {
+                "smithy.api#trait": {
+                    "selector": "structure > member"
+                },
+                "smithy.api#documentation": "Indicates that a structure member SHOULD be unconditionally generated as optional in clients regardless of if the member is required or has a default value. This trait allows documentation generators to indicate that a member is required by the service, even if it is not reflected in generated client code."
+            }
         }
     }
 }

smithy-aws-traits/src/test/java/software/amazon/smithy/aws/traits/AwsClientNullableIndexTest.java

@@ -0,0 +1,55 @@
+/*
+ * 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.aws.traits;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.StringShape;
+import software.amazon.smithy.model.shapes.StructureShape;
+import software.amazon.smithy.model.traits.DefaultTrait;
+import software.amazon.smithy.model.traits.RequiredTrait;
+
+public class AwsClientNullableIndexTest {
+    @Test
+    public void takesClientOptionalIntoAccount() {
+        StringShape str = StringShape.builder().id("smithy.example#Str").build();
+        StructureShape struct = StructureShape.builder()
+                .id("smithy.example#Struct")
+                .addMember("foo", str.getId(), b -> b.addTrait(new ClientOptionalTrait())
+                        .addTrait(new DefaultTrait())
+                        .build())
+                .addMember("bar", str.getId(), b -> b.addTrait(new ClientOptionalTrait())
+                        .addTrait(new RequiredTrait())
+                        .build())
+                .addMember("baz", str.getId(), b -> b.addTrait(new ClientOptionalTrait()).build())
+                .addMember("bam", str.getId(), b -> b.addTrait(new RequiredTrait()).build())
+                .addMember("boo", str.getId(), b -> b.addTrait(new DefaultTrait()).build())
+                .build();
+
+        Model model = Model.builder().addShapes(str, struct).build();
+        AwsClientNullableIndex nullableIndex = AwsClientNullableIndex.of(model);
+
+        assertThat(nullableIndex.isMemberOptional(struct.getMember("foo").get()), is(true));
+        assertThat(nullableIndex.isMemberOptional(struct.getMember("bar").get()), is(true));
+        assertThat(nullableIndex.isMemberOptional(struct.getMember("baz").get()), is(true));
+        assertThat(nullableIndex.isMemberOptional(struct.getMember("bam").get()), is(false));
+        assertThat(nullableIndex.isMemberOptional(struct.getMember("boo").get()), is(false));
+    }
+
+}

smithy-aws-traits/src/test/java/software/amazon/smithy/aws/traits/ClientOptionalTraitTest.java

@@ -0,0 +1,47 @@
+/*
+ * 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.aws.traits;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.model.shapes.StructureShape;
+
+public class ClientOptionalTraitTest {
+
+    private Model getModel() {
+        return Model.assembler()
+                .discoverModels(getClass().getClassLoader())
+                .addImport(getClass().getResource("client-optional-trait.smithy"))
+                .assemble()
+                .unwrap();
+    }
+
+    @Test
+    public void loadsTrait() {
+        Model model = getModel();
+        StructureShape struct = model.expectShape(ShapeId.from("smithy.example#Foo"), StructureShape.class);
+
+
+
+        assertThat(struct.getMember("baz").get().hasTrait(ClientOptionalTrait.class), is(true));
+        assertThat(struct.getMember("bar").get().hasTrait(ClientOptionalTrait.class), is(true));
+        assertThat(struct.getMember("bam").get().hasTrait(ClientOptionalTrait.class), is(true));
+    }
+}

smithy-aws-traits/src/test/resources/software/amazon/smithy/aws/traits/client-optional-trait.smithy

@@ -0,0 +1,19 @@
+$version: "2.0"
+
+namespace smithy.example
+
+use aws.api#clientOptional
+
+structure Foo {
+    @required
+    @clientOptional
+    baz: String
+
+    @default
+    @clientOptional
+    bar: String
+
+    // this is fine, but unnecessary
+    @clientOptional
+    bam: String
+}

smithy-model/src/main/java/software/amazon/smithy/model/knowledge/NullableIndex.java

@@ -50,13 +50,20 @@ public final boolean isNullable(ToShapeId shape) {
         Model m = Objects.requireNonNull(model.get());
         Shape s = m.expectShape(shape.toShapeId());
         MemberShape member = s.asMemberShape().orElse(null);
-
         // Non-members should always be considered optional.
-        if (member == null) {
-            return true;
-        }
+        return member == null || isMemberOptional(member);
+    }
 
+    /**
+     * Checks if a member is optional.
+     *
+     * @param member Member to check.
+     * @return Returns true if the member is optional.
+     */
+    public boolean isMemberOptional(MemberShape member) {
+        Model m = Objects.requireNonNull(model.get());
         Shape container = m.expectShape(member.getContainer());
+
         switch (container.getType()) {
             case STRUCTURE:
                 // Structure members are nullable by default; non-null when marked as @default / @required.