Document a UUID scalar
A service defines a UUID scalar and wants clients to discover the UUID rules.
GraphQL · Directive
@specifiedBy
@specifiedBy documents a custom scalar by attaching a URL for its specification. The URL should explain the scalar’s format, serialization, and coercion rules.
How it works
Apply @specifiedBy to a custom scalar in SDL to publish the URL of its human-readable specification. That document should define the scalar’s data format, serialization, and coercion rules so compatible tools and systems can understand its behavior.
Syntax
directive @specifiedBy(url: String!) on SCALARParameters
| Name | Type | Description |
|---|---|---|
url | String! | URL of the custom scalar’s human-readable specification. |
Key points
- It is a built-in SDL directive for documenting scalar behavior.
- A custom scalar can publish its specification URL through this directive.
- The referenced document must be readable by people, not just machine-oriented metadata.
- Compatible systems should follow the rules described by the linked specification.
Common mistakes
- Do not attach the directive to built-in scalars such as String, Int, Float, Boolean, or ID.
- The URL should describe the scalar’s format and conversion rules, not merely point to an arbitrary page.
Example: Specify a UUID scalar
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")Declares a custom UUID scalar and associates it with a human-readable specification URL.
When to use it
Publish custom format rules
A team publishes a custom date-time format and needs to associate that contract with its scalar.
Support schema introspection
Schema tooling exposes scalar metadata through introspection.
Interview questions
QWhat is @specifiedBy used for?
@specifiedBy is a built-in type-system directive for documenting a custom scalar. Its required url argument identifies the scalar’s specification, and the directive can be introspected.
Follow-up: What should the target document contain? It should be human-readable and define the scalar’s format, serialization, and coercion rules.
QWhat is the directive’s signature and location?
Its SDL signature is directive @specifiedBy(url: String!) on SCALAR. Therefore, it accepts one required non-null String argument and can be applied only to scalar definitions.
Follow-up: Can it annotate a field? No. Its location is SCALAR, so it describes the scalar type rather than an individual field use.
QWhy does the URL matter to clients and tools?
A service should provide a specification URL when defining a custom scalar. Tools aware of that URL can use the documented rules to conform to the scalar’s behavior.
Follow-up: What should happen when no URL is supplied? The directive is not required for every scalar by the signature, but a service should provide one for a custom scalar specification.
Related
custom scalarspecifiedByURLscalardirectivestype system definition language