1. You’re right, and I don’t understand the rationale for those tests either.
2. No, the internal tag is an old convention used only inside Amazon. You don’t need to special case it. The related tests should also be reevaluated.
3. The tags property of the enum trait is independent of the tags trait, since the enum trait doesn’t introduce members. You need to run model transforms to convert this trait to an enum shape. We could say it’s similar to that tags trait.

Thanks for the prompt reply!

The tags property of the enum trait is independent of the tags trait, since the enum trait doesn’t introduce members. You need to run model transforms to convert this trait to an enum shape. We could say it’s similar to that tags trait.

This is technically correct, but said model transform is part of the core Smithy library, which all code generators should apply, provided as changeStringEnumsToEnumShapes in ModelTransformer.java. This eventually delegates to ChangeShapeType.java which calls EnumShape.fromStringShape, where we see that the tags property on @enum gets converted to the @tags trait on enum shape:

https://github.com/awslabs/smithy/blob/f02f5ddcc7c585f8335683688dcbe9d5a2f7ebb9/smithy-model/src/main/java/software/amazon/smithy/model/shapes/EnumShape.java#L230-L232

So the end-user reading the documentation will just see them as equivalent when synthesizing their IDL v1 model.

We have revisited the changes made related to this. Answering your questions below with related changes we plan to make.

1. The motivation for those changes: Services may have in-progress features (operations, members, etc.) in development/private-beta, that they do not want available in their public client SDKs. They can mark these as "internal" and have a projection that filters it out and client SDKs are built from that. The server needs to implement those features, so would use the full model (i.e., including "internal" parts of the model). If the feature is adding a new enum value (marked "internal", for now) and a customer makes a request with existing public operation where this enum is an input member, and uses an invalid value, we don't want the validation message to "leak" the "internal" enum value. We will update the docs to mention this use.

2. Does @tags["internal"] imply @internal?

In general, no. But since we can't use @internal trait on the enum trait, using internal tag is the only way to indicate the same on enum trait. So as a special case, when converting string enum to enum shape, we will add @internal trait, so where needed (like SSDK validation message use case above) logic can rely on just @internal trait and not on internal tag.

3. Does the tags property on the @enum trait imply @tags?

So the end-user reading the documentation will just see them as equivalent when synthesizing their IDL v1 model.

Kind of. Depends on the context of the end-user, like if you are in the context of transforming the string enum to enum shape. We will update the javadocs on the related transform/codegen classes. We are also missing docs on this transform here which we will fix. We will add some clarification to the enum trait docs for this.

Based on these, in regards to the protocol tests referenced, we will change them so that:

• avoid leaking @internal enum members from enum shape - general case for internal enum in validation message
• avoid leaking internal tagged enum values from enum trait - special case for enum trait
• remove logic related to internal tagged members on enum shape

These changes are being made in
#1739
#1740
#1746

Thanks! That makes sense.

One last question. We have a rather old PR open in smithy-rs to migrate entirely to EnumShape (i.e., never use EnumTrait in the codebase). At the moment we have to handle both separately, which causes branching and deprecation warnings (the EnumTrait class is marked as deprecated). That PR opts to always internally apply the changeStringEnumsToEnumShapes transform as initially suggested by the Smithy team and just handle EnumShape thereafter. Would you suggest then that we don't do that and have the user add the transform to their smithy-build.json explicitly? If we do unconditionally apply the transform, then the answer to the last two questions:

• Does @tags["internal"] imply @internal?
• Does the tags property on the @enum trait imply @tags?

would always be "yes" to the eyes of a smithy-rs user by virtue of how the transform works.

I don't think this discussion changes the recommendation to apply the changeStringEnumsToEnumShapes in the codegen and just handle EnumShape. It does mean yes to the questions in the eyes of smithy-rs user, and that sounds fine.

Closing as this discussion seems resolved and 1.31.0 contains the latest updates to enum upgrades.