Skip to content

Add a root meta-trait to declare root shapes#3079

Draft
JordonPhillips wants to merge 1 commit into
mainfrom
root-trait
Draft

Add a root meta-trait to declare root shapes#3079
JordonPhillips wants to merge 1 commit into
mainfrom
root-trait

Conversation

@JordonPhillips
Copy link
Copy Markdown
Contributor

This adds a new root meta-trait. This trait marks a trait as a rooting trait. Any shape marked by a rooting trait is considered to be a root shape. Root shapes are shapes that are always considered to be referenced.

Currently, service shapes and traits are considered to be root shapes. A new metadata trait is being added that will also define new root shapes

Beyond that, this trait is a necessary prerequisite for using Smithy to define schemas and use-cases that are not bound to the context of a service API.

For example, imagine a theoretical jsonSchema trait that uses Smithy to define a plain JSONSchema definition that isn't tied to OpenAPI. We wouldn't want those shapes to be considered unreferenced because that might mean they get filtered away inappropriately and it would mean the unreferenced shape linter would start producing a huge amount of noise.

Or for a more near-term example that still tied to services, this could be used with events:

$version: "2.0"

namespace aws.api

@root
@trait(selector: "structure")
structure event
$version: "2.0"

metadata shapeClosures = [
    {
        id: "serviceEvents"
        selector: "[trait|aws.api#event] ~>"
    }
]

namespace com.example

@event
structure ObjectDeleted {
    @required
    bucket: String

    @required
    key: String

    @required
    timestamp: Timestamp
}

The downside to this is that it can become more work to keep the sizes of projections down. You'll need to do more to filter out things that you don't want. I see the excludeShapesByTrait transform getting a lot more usage, for example.

This is a draft because it was a bit of a brain blast and I want to discuss this quite a bit more offline with folks before moving forward.


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

This adds a new `root` meta-trait. This trait marks a trait as a rooting
trait. Any shape marked by a rooting trait is considered to be a root
shape. Root shapes are shapes that are always considered to be
referenced.

Currently, service shapes and traits are considered to be root shapes. A
new metadata trait is being added that will also define new root shapes.

Beyond that, this trait is a necessary prerequisite for using Smithy to
define schemas and use-cases that are not bound to the context of a
service API.

For example, imagine a theoretical `jsonSchema` trait that uses Smithy
to define a plain JSONSchema definition that isn't tied to OpenAPI. We
wouldn't want those shapes to be considered unreferenced because that
might mean they get filtered away inappropriately and it would mean
the unreferenced shape linter would start producing a huge amount of
noise.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant