Description
I think the following two PRs introduce behavior that is not documented well:
These prompted the following questions.
1. Should @internal shapes automatically be filtered out by all tooling?
The documentation for the @internal trait reads:
Shapes marked with the internal trait are meant only for internal use. Tooling can use the internal trait to filter out shapes from models that are not intended for external customers.
As an example, a service team may wish to use a version of a model that includes features that are only available to internal customers within the same company, whereas clients for external customers could be built from a filtered version of the model.
(emphasis mine)
#1658 adds a protocol test to exclude returning enum values that have been marked with the @internal trait.
However, my reading of the documentation is that @internal is just a marker trait that carries no semantics — it is up to tooling to decide whether to filter out @internal-tagged shapes or not. Therefore, I would have expected that the user first needs to define a projection that explicitly filtered out @internal shapes for a server SDK to be built that would pass that protocol test; if the @internal shapes are not filtered out, then a server SDK should still include them in the validation error message.
2. Does @tags["internal"] imply @internal?
Both PRs above add tests such that enum values tagged (i.e. using the @tags trait or the tags property on the @enum trait) with the string "internal" are not included in the validation error message.
This seems to imply that @tags["internal"] implies @internal. However, I don't see this documented. I was under the impression that tags for a shape lived in a completely separate data plane that would not interact with that of Smithy traits, and that they would just boil down to a bag of string values whose meaning is entirely for user-defined tooling to decide.
3. Does the tags property on the @enum trait imply @tags?
The answer to this is obviously yes, but I think that the docs for the property:
Attaches a list of tags that allow the enum value to be categorized and grouped.
could be clearer, perhaps by having the word tags link to the trait @tags. As written, one could interpret the tags for an enum value to be completely independent of those defined using @tags.