Selectors¶

Matching traits¶

We can match shapes based on traits using an attribute selector. The following selector finds all structure shapes with the error trait trait:

structure[trait|error]

The trait| is called a namespace prefix. This particular prefix tells the selector that we are interested in a trait applied to the current shape, and that that specific trait is time.

We can match string shapes that have a specific trait value:

structure[trait|error=client]

Matching on trait values only works for traits that have a scalar value (e.g., strings, numbers, and booleans). We can also match case-insensitvely on the value by appending " i" before the closing bracket:

structure[trait|error=CLIENT i]

Fully-qualified trait names are also supported:

string[trait|smithy.example#customTrait=foo]

Matching on shape ID¶

Attribute selectors can be used to match the shape ID. The following example matches a single resource shape with an ID of smithy.example#Foo:

resource[id='smithy.example#Foo']

Notice that the value of an attribute selector can be quoted. The example above uses single quotes, but double quotes work too.

Smithy provides several attributes in the id namespace to make matching on a shape ID easier. The following example finds all shapes that are in the "smithy.example" namespace:

resource[id|namespace=smithy.example]

Though not as clear, matching shapes in a specific namespace can also be achieved using the ^= comparator against id:

resource[id^=smithy.example#]

The following example matches all member shapes that have a member name of "key":

resource[id|member=key]

Though not as clear, matching members with a member name of "key" can also be achieved using the $= comparator against id:

resource[id$="$key"]

Available attributes¶

Directed neighbors¶

The > neighbor selector is an undirected edge traversal. Sometimes a directed edge traversal is necessary to match the appropriate shapes. For example, the following selector returns the "bound", "input", "output", and "errors" relationships of each operation:

operation > *

A directed edge traversal can be performed using the -[ token followed by a comma separated list of relationships, followed by ]->. The following selector matches all structure shapes referenced as operation input or output.

operation -[input, output]->

The :test function can be used to check if a shape has a named relationship. The following selector matches all resource shapes that define an identifier:

resource:test(-[identifier]->)

Relationships¶

The table below lists the labeled directed relationships from each shape.

:each¶

The :each function is used to map over the current shape with multiple selectors and returns all of the shapes returned from each selector. The :each function accepts a variadic list of selectors each separated by a comma (",").

The following selector matches all string and number shapes:

:each(string, number)

Each can be used inside of neighbors too. The following selector matches all members that target a string or number:

member > :each(string, number)

The following :each selector matches all shapes that are either targeted by a list member or targeted by a map member:

:each(list > member > *, map > member > *)

The following selector matches all list and map shapes that target strings:

:each(:test(list > member > string), :test(map > member > string))

Because none of the selectors in the :each function are intended to change the current node, this can be reduced to the following selector:

:test(:each(list > member > string, map > member > string))

:test¶

The :test function is used to test if a shape is contained within any of the provided predicate selector return values without changing the current shape.

The following selector is used to match all string and number shapes:

:test(string, number)

The :test function is much more interesting when used to test if a shape contains a neighbor in addition to other filtering. The following example matches all shapes that are bound to a resource and have no documentation:

:test(-[bound, resource]->) :not([trait|documentation])

:not¶

The :not function is used to filter out shapes. This function accepts a list of selector arguments, and the shapes returned from each predicate are filtered out from the result set.

The following selector matches every shape except strings:

:not(string)

The following selector matches every shape except strings and floats:

:not(string, float)

The following example matches all shapes except for strings that are targeted by a list member:

:not(list > member > string)

The :test function can be used to test a shape, potentially traversing its neighbors, without changing the return value of the test. The following example does not match any list shape that has a string member:

:not(:test(list > member > string))

Successive :not functions can be used to filter shapes using several predicates. The following example does not match strings or shapes with the sensitive trait trait:

:not(string):not([trait|sensitive])

Multiple selectors can be provided to :not to find shapes that do not match all of the provided predicates. The following selector finds all string shapes that do not have both the length and pattern traits:

string:not([trait|length], [trait|pattern])

The following example matches all structure members that target strings in which the member does not have the length trait and the shape targeted by the member does not have the length trait:

structure > member
    :test(> string:not([trait|length]))
    :test(:not([trait|length]))

:of¶

The :of function is used to match members based on their containers (i.e., the shape that defines the member). The :of function accepts one or more selector arguments. Each selector receives the containing shape of the member, and if any of the selectors return returns 1 or more shapes, the member is matched.

The following example matches all structure members:

member:of(structure)

The following example matches all structure and list members:

member:of(structure, list)