directive @sdl

The executables argument defines GraphQL executable documents that are loaded with the schema.

At a minimum, during schema deployment, executable documents are validated against the schema. This can be used to ensure that GraphQL operations used by client applications will continue to be valid with the newly deployed schema. In this case, client applications should load their GraphQL executable documents from the same files provided to executables.

GraphQL executable documents optionally can be persisted by the schema so that clients use a persisted document identifier in the request instead of providing the contents of the document. See StepZen_ExecutableDocument.persist.

Specifies the schema definition files (SDL) to be included as part of the schema.

File paths provided are relative to the folder containing the file with the @sdl directive. Only subfolders are supported for relative file paths.

The visibility argument defines the visibility of interface and object fields that are included into the schema through the files argument in the same @sdl instance.

Visibility allows control of what fields are seen by GraphQL requests, introspection and by other directives and can be used to create a cleaner schema for applications, by hiding internal or unused fields.

A common use is to hide Query fields referenced in @materializer so that details of how a graph is assembled is hidden, for example hiding Query.orders that is used in:

extend Customer {
  orders: [Order] @materializer(query:"orders")
}

so that orders are only accessible through an instance of a Customer object.

If a field is hidden by expose: false or by default, then:

• it cannot be selected by a GraphQL request

• it cannot be referenced by directives in:

  • the same file as the @sdl instance declaring it as hidden

  • any file that includes (through @sdl(files:) the same file as the @sdl directive instance declaring it as hidden

• it is not visible through GraphQL introspection except when making a request with an admin api key

Hidden fields are visible to directives within the files included (directly or indirectly) by @sdl(files:) argument for the @sdl instance that declared the field as hidden.

Once hidden, a field cannot be exposed by outer @sdl(visibility:) values.

For example, this schema file (weather/atom.graphql) exposes a single Query field Query.forecast that is defined in nws.graphql (or files it includes through @sdl(files:)):

extend schema
  @sdl(
    files: "nws.graphql"
    visibility: {expose: true, types: "Query", fields: "forecast"}
  )

Any other Query fields (for example Query._location) defined in nws.graphql (or files it includes through @sdl(files:)) are hidden because they do not match the regular expression in fields.

Note that Query._location is visible to directives within nws.graphql (or files it includes through @sdl(files:)), thus the visibility is for uses outside of that @sdl instance, but not within the set of files it includes.

If weather/atom.graphql is itself included in a schema through @sdl(files:) then Query._location will remain hidden even if there is a visibility pattern that matches it, once a field is hidden, it remains hidden.

If visibility argument is present with at least one visibility pattern:

• By default, when no visibility patterns apply to a field:

  • fields in root operation types (Query, Mutation and, Subscription) are hidden (effectively expose: false)

  • fields in other interface and object types are visible (effectively expose: true)

• Fields that match the regular expressions in types and fields are hidden with expose: false and visible with expose: true

If visibility argument is not present or has no patterns then no visibility patterns are applied, and all fields defined through the files included by files are exposed.

Patterns can be supplied for clarity even if they match the defaults and thus are superfluous, for example this makes it clear that Query and Mutation fields starting with underscore are not intended to be visible.

[
  {expose:true types: "Query|Mutation" fields:"[a-z].*"}
  {expose:false types: "Query|Mutation" fields:"_.*"}
]

Use of regular expressions support use of naming schemes, such as using a _ prefix to indicate a fields or types are internal to a set of schema files.

Note, a single namespace for fields within a type still exists, so if any schema field defines a field Query.q then no other file in the schema can define a field of the same name, regardless of if Query.q is visible or not.