Grafbase Spec

This document defines the directives and types that have special treatment in the Grafbase gateway. They are meant to be used as building blocks for extension directives. The gateway will automatically detect them and inject the right data in their stead.

Here after is the full definition:


"""
String specifying a selection set over the arguments which should be provided at runtime.
"""
scalar InputValueSet

"""
String specifying a selection set over the response data which should be provided at runtime.
"""
scalar FieldSet

# Template family
"String template rendered at runtime with URL escaping."
scalar UrlTemplate
"String template rendered at runtime with JSON escaping."
scalar JsonTemplate

Import me with:


extend schema @link(url: "https://specs.grafbase.com/grafbase", import: ["FieldSet"])

InputValueSet


"""
String specifying a selection set over the arguments which should be provided at runtime.
"""
scalar InputValueSet

The InputValueSet scalar is used to inject arguments into a directive. It's a String that defines a selection set such as "ids filter { age }" on the field arguments with a special case "*" that will inject all the arguments as shown in the following example:


# Extension SDL
directive @myDirective(input: InputValueSet) on FIELD_DEFINITION

# ---
# Subgraph SDL
type Query {
  # Receives all arguments
  users(ids: [ID!], filter: Filter): [User!] @myDirective(input: "*")

  # Which is equivalent to the following
  users(ids: [ID!], filter: Filter): [User!] @myDirective(input: "ids filter")

  # Fine-grained selection
  users(ids: [ID!], filter: Filter): [User!]
    @myDirective(input: "filter { age }")
}

input Filter {
  name: String
  age: Int
}

type User {
  id: ID!
}

Contrary to field selection sets used in operations, there is a relaxed rule for leaves: one can select "filter" without specifying any sub-selection despite being an input object. The whole Filter input object will be provided in that case.

InputValueSet can be used in any extension directive definitions, but outside of FIELD_DEFINITION location, any non-null InputValueSet value will raise an error:


# Valid
type User @myDirective {
  id: ID!
}
# Valid
type User @myDirective(input: null) {
  id: ID!
}
# Invalid, will raise an error.
type User @myDirective(input: "*") {
  id: ID!
}

FieldSet


"""
String specifying a selection set over the response data which should be provided at runtime.
"""
scalar FieldSet

The FieldSet scalar is used to inject response data into a directive. It's a String that defines a field selection set such as "id name" on the current object or interface:


# Extension SDL
directive @myDirective(fields: FieldSet) on FIELD_DEFINITION

# ---
# Subgraph SDL
type User {
  id: ID!
  name: String
  pets(limit: Int!): [Pet!]
  catLoverFriends: [User!]
    @myDirective(fields: "id pets(limit: 10) { ... on Cat { id } }")
}

union Pet = Cat | Dog

type Dog {
  id: ID!
}

type Cat {
  id: ID!
}

Except named fragments, FieldSet accepts any valid field selection set with field arguments or inline fragments. The gateway will do its best to re-use existing operation fields if they match, but will request anything additional.

FieldSet can be used in any extension directive definitions, but outside of FIELD_DEFINITION, OBJECT and INTERFACE locations, any non-null FieldSet value will raise an error:


# Valid
union Pet = Cat | Pet @myDirective
# Valid
union Pet = Cat | Pet @myDirective(fields: null)
# Invalid, will raise an error.
union Pet = Cat | Pet @myDirective(fields: "... on Cat { id }")

Templates


"String template rendered at runtime with URL escaping."
scalar UrlTemplate

"String template rendered at runtime with JSON escaping."
scalar JsonTemplate

Templates are rendered by the gateway before being sent over to the extension. We support two variants of templates:

UrlTemplate: for URLs, values will be URL-encoded. Complex values such as objects or lists will be first serialized to JSON and then URL-encoded.
JsonTemplate: for JSON, values will be rendered as their serialized JSON value.

The following variables are accessible in the template:

args: the arguments of the field

We use a subset of Mustache template syntax:

values: {{val}}
nested fields: {{object.field}}
current object: {{.}}
nested block such {{#object}} {{field}} {{/object}} scope the content to the parent value. So field refers to object.field. Furthermore if used on a list such as {{#objects}} {{field}} {{/objects}} will render field for all the objects in the list.
We have custom blocks -last and -first which only render for the last element and the first element of a list respectively. But more importantly, we support their opposite: ^-last and ^-first rendering for all but the last and but the first respectively, which most notably allows building JSON lists:


{{#objects}} {{field}} {{^-last}},{{/-last}} {{/objects}}

Here after are a few examples using UrlTemplate and JsonTemplate:


# Extension SDL
directive @myDirective(url: UrlTemplate, json: JsonTemplate) on FIELD_DEFINITION

# ---
# Subgraph SDL
type Query {
  # user(id: "1") -> "/users/1"
  user(id: ID!): User @myDirective(url: "/users/{{ args.id }}")

  # users(ids: ["1", "2"]) -> "/users?ids=%5B%221%22%2C%222%22%5D"
  users(ids: [ID!]): [User!] @myDirective(url: "/users?ids={{ args.ids }}")

  # users(ids: ["1", "2"]) -> "/users?ids=1,2"
  users(ids: [ID!]): [User!]
    @myDirective(
      url: "/users?ids={{#args.ids}}{{.}}{{^-last}},{{/-last}}{{/args.ids}}"
    )

  # users(filter: { name: "Alice" }) -> `{"name":"Alice"}`
  users(ids: [ID!], filter: Filter): [User!]
    @myDirective(json: "{{ args.filter }}")

  # users(filter: { name: "Alice" }) -> `"Alice"`
  users(ids: [ID!], filter: Filter): [User!]
    @myDirective(url: "{{ args.filter.name }}")
}

input Filter {
  name: String
  age: Int
}

type User {
  id: ID!
}