Core: the GraphQL API and how its schema is built

This document covers the part of linked-data-store-core that serves GraphQL: how LDS builds the schema it serves from the schema file of the model, how a request is read and answered, and how a field reads documents from persistence. It is for developers and maintainers who change this code. How the same schema file becomes JSON Schema and the specification is in the model. How the handlers are put on their paths is in the application.

What this part is for

The GraphQL API reads documents. It has a query type and nothing else: no mutation and no subscription. Documents are written through REST (the REST handlers, the write path).

The schema that LDS serves is not the schema file. The file names the entity types (the types with @domain), their fields and their links (the fields with @link). LDS builds the rest from it when it starts:

  • a Query type with two fields for every entity type, <Entity>ById and <Entity>;
  • a field on the target of every link that goes the other way (a reverse link);
  • relay connections (<Type>Connection, <Type>Edge, PageInfo) for lists of links, with the arguments first, after, last and before;
  • when search is on, a Search field with its types;
  • a data fetcher for every field that reads from persistence.

The code is in the package io.descoped.lds.graphql and the packages under it. The package jsonSchema belongs to the model and is not described here. The module does not export these packages. It opens io.descoped.lds.graphql.graphiql, which holds the GraphiQL page. The libraries are graphql-java and graphql-java-extended-scalars (graphql-java.version and graphql-java-extended-scalars.version in the root POM).

Layout

The request

Class Responsibility
GraphqlHttpHandler The Undertow handler at /graphql. Reads the query, the variables and the operation name from a GET or a POST, executes the query and writes the answer as JSON.
GraphQLContext An interface of LDS (not the class of graphql-java with the same name): the exchange and the time of the query. The fetchers get it from the context of graphql-java, under the key GraphQLContext.class.
GraphQLUndertowContext The implementation. Works out the time of the query from the parameter snapshot, the variable __snapshot or the clock.
graphiql/graphiql.html (a resource) The GraphiQL page served at /graphiql.

Building the schema (schemas, schemas.visitors, directives)

Class Responsibility
GraphQLSchemaBuilder parseSchema makes a graphql-java schema of the schema file. getGraphQL makes the served schema of that, in a fixed order of passes.
TypeTraverser The walk over a schema that every pass uses. LDS has its own; see The walk, the type map and the builders.
TypeCollectingVisitor Collects the named types met on a walk into a map, in the order met.
SchemaElements The builders LDS uses for types, fields and directives, the order of the parts of a type, and three helpers (name, value, defaultValue).
DateTimeScalar The scalar DateTime of LDS.
TypeReferencerVisitor Replaces the type of a field, the interfaces of an object and the members of a union by references by name.
ReverseLinkNameVisitor Gives every @link without a reverseName a name for its reverse link.
ReverseLinkBuildingVisitor Adds the reverse link field to the target of every link. computePath gives the path of a link field in its document; getLinkDirective reads @link of a field.
QueryBuildingVisitor Adds <Entity>ById and <Entity> to the Query type for every type with @domain.
AddSearchTypesVisitor Adds TypeFilters, SearchResult and the field Search.
AddConnectionVisitor Turns a paged list of links into a relay connection and makes the connection, edge and PageInfo types.
RegistrySetupVisitor Gives every link field its data fetcher and every interface and union its type resolver.
DomainDirective, LinkDirective, ReverseLinkDirective The definitions of @domain, @link and @reverseLink as LDS serves them, and readers of their arguments. Each holds a GraphQLDirective; a directive of graphql-java cannot be extended.

Reading documents (fetcher)

Class Responsibility
PersistenceFetcher <Entity>ById: one document by its id.
PersistenceLinkFetcher A single link: reads the document the link points at.
PersistenceLinksFetcher A list of links that is not paged: reads the document of every link.
ConnectionFetcher The base of the connection fetchers. Reads first, after, last, before and the time of the query, and makes a Range of them (ConnectionParameters.getRange). toEdge makes an edge of a document.
PersistenceRootConnectionFetcher <Entity>: the documents of an entity type.
PersistenceLinksConnectionFetcher A paged list of links: the documents the links of one document point at.
PersistenceReverseLinksConnectionFetcher A reverse link: the documents that link to one document.
QueryConnectionFetcher, QueryConnectionCursor Search: asks the search index, then reads every hit from persistence. The cursor is a position in the result.

The example used in this document

The requests below were sent to LDS started from the built runtime, in memory, on port 19111, with the example model linked-data-store-server/schemas/schema.graphql:

GraphQL
directive @domain(searchable: Boolean) on OBJECT
directive @link(pagination: Boolean, reverseName: String) on FIELD_DEFINITION

type Person @domain {
  name: String!
  born: DateTime
  address: Address
  employer: Company @link(reverseName: "employees")
  friends: [Person] @link
}

type Address {
  street: String
  city: String!
}

type Company @domain {
  name: String!
  founded: DateTime
  about: [Text]
}

type Text {
  languageCode: String
  languageText: String!
}

type Query {
  x: String
}

scalar Date
scalar DateTime
scalar Time

The descriptions and the comment of the file are left out here. These documents were written through REST, all with the valid time timestamp=2020-01-01T00:00:00Z unless another time is given:

Entity Id Document
Company acme {"name":"Acme","founded":"1999-05-01T08:00:00Z","about":[{"languageCode":"en","languageText":"Makes anvils and rockets"}]}
Company globex {"name":"Globex","founded":"2001-09-09T09:09:09.120+02:00"}
Company future {"name":"Future Ltd"}, valid from 2030-01-01
Person kari {"name":"Kari","employer":"/Company/acme"}
Person per {"name":"Per","employer":"/Company/acme","address":{"street":"Storgata 1","city":"Oslo"}}
Person anne {"name":"Anne"}
Person early {"name":"Early","employer":"/Company/future"}
Person ola {"name":"Ola","born":"1980-02-03T04:05:06.123456Z","employer":"/Company/acme","friends":["/Person/kari", "/Person/per","/Person/anne"]}
Person ola valid from 2022-01-01: {"name":"Ola Nordmann","born":"1980-02-03T04:05:06.123456Z", "employer":"/Company/globex","friends":["/Person/kari"]}

An answer is shown formatted below; LDS sends it on one line. A query without variables is sent as application/graphql, the query itself as the body, formatted. A query whose answer names a line and a column of the query, and a query with variables, is sent as JSON.

How the schema is built

Where it starts

The constructor of UndertowApplication reads graphql.enabled and graphql.schema. When GraphQL is enabled and the path of a schema file is given, it does this:

  1. parseSchemaFile reads the file into a TypeDefinitionRegistry. The path is tried as a resource of the class path first and as a file after that.
  2. GraphQLSchemaBuilder.parseSchema makes a graphql-java schema of the registry.
  3. new GraphQLSchemaBuilder(namespace, persistence, searchIndex).getGraphQL(schema) makes the served schema. The namespace is namespace.default. The search index is null when search is off.
  4. GraphQL.newGraphQL(schema).build() makes the engine, and GraphqlHttpHandler is put at /graphql and the GraphiQL page at /graphiql.

The file was parsed once before, for the specification (the model). The log of a start tells the passes at INFO. These are its lines about GraphQL, with the time and the thread left out:

Text
... GraphQLToJsonConverter - Managed domains: /Company /Person
... UndertowApplication - Creating specification using GraphQL schema: schemas/schema.graphql
... SearchIndexConfigurator - GraphQL Search is disabled. Skipping search index initialisation
... UndertowApplication - Initializing GraphQL Web API ...
... GraphQLSchemaBuilder - Collecting types into type map
... GraphQLSchemaBuilder - Computing reverse links
... GraphQLSchemaBuilder - Creating root "Query" fields
... GraphQLSchemaBuilder - Replacing all type with references
... GraphQLSchemaBuilder - Transforming paginated links to relay connections
... GraphQLSchemaBuilder - Resolving type references

With search on, the line Creating root "Query" search field and search types comes after Creating root "Query" fields.

GraphQLSchemaBuilder writes the types at DEBUG ("Final schema:") when the connections are made, before the last two passes, and the state after two earlier passes at TRACE ("Computing reverse links:", "Query:"). The logger is io.descoped.lds.graphql.schemas.GraphQLSchemaBuilder.

parseSchema

parseSchema builds the runtime wiring: the order of the parts of a type (SchemaElements.ORDER), the scalars DateTime (DateTimeScalar.INSTANCE), Date and Time (ExtendedScalars.Date, ExtendedScalars.Time), and the EchoingWiringFactory of graphql-java, so that the file needs no fetchers. Then graphql-java checks the file. What it refuses stops the start of LDS:

The schema file The exception that ends the start
uses @domain and does not declare directive @domain SchemaProblem{errors=['A' [@1:1] tried to use an undeclared directive 'domain']}
has no Query type SchemaProblem{errors=[A schema MUST have a 'query' operation defined]}
uses an argument that its own declaration of the directive does not have (@link(pagination: false) with directive @link on FIELD_DEFINITION) SchemaProblem{errors=['b' [@3:18] use an unknown argument 'pagination' on directive 'link']}
declares a scalar other than Date, DateTime and Time SchemaProblem{errors=[There is no scalar implementation for the named 'Unused' scalar type]}

Each row was seen by starting LDS with such a file. The schema file must have a Query type, but LDS does not use it: getGraphQL makes its own. A Query type without fields is accepted. graphql-java does not build a schema with an empty Query, so withFieldInEmptyQuery gives it a field _empty: String in a copy of the registry.

The passes of getGraphQL

getGraphQL works on one map from type name to type, the type map. Every pass is a walk with TypeTraverser over the values of that map, and most passes put changed copies of types back into it. The order matters: each pass reads what the earlier ones wrote.

Pass Visitor What it does
1 none Takes the types of the parsed schema, sorted by name. Removes Query, the types whose name starts with __ and the scalars that no type and no directive uses (typesInUse).
2 TypeCollectingVisitor Collects every named type that can be reached into the type map, in the order met.
3 TypeReferencerVisitor, then GraphQLTypeResolvingVisitor of graphql-java Replaces types inside types by references by name, then resolves the references against the type map.
4 ReverseLinkNameVisitor A @link field without reverseName gets one: reverse, then the name of the entity type, then the names of the fields on the way from the entity type to the link, each with a capital first letter. Person.friends gets reversePersonFriends. The way is the one the walk took to the field (computeName reads the parents of the field in the walk), so for a link in a type without @domain (an embedded type) the name follows from where the walk met that type first. See Not finished and known to be wrong.
5 ReverseLinkBuildingVisitor For every @link field, adds a field to the target type (to every member, when the target is a union). Its name is the reverseName, its type is [<Source>!]!, and it has @reverseLink(mappedBy: <path>, pagination: true). The path is that of the link field in its document: $.friends[], $.employer.
6 QueryBuildingVisitor For every object type with @domain, adds <Name>ById(id: ID!): <Name>! with @link(pagination: false) and <Name>: [<Name>!]! with @link(pagination: true) to the Query builder.
7 AddSearchTypesVisitor Only when there is a search index. Adds the enum TypeFilters and the union SearchResult, both of every type with @domain, and the field Search(query: String!, filter: [TypeFilters]): [SearchResult!]! with the applied directive search.
8 none Builds Query and puts it into the type map.
9 TypeReferencerVisitor References again, now also in Query and the new fields.
10 AddConnectionVisitor A field with @link, @reverseLink or search whose type is a list, and whose pagination is not false, keeps its name and becomes (first: Int, after: String, last: Int, before: String): <Target>Connection. The visitor makes <Target>Connection and <Target>Edge once for each target, and PageInfo once. It takes a type of that name from the type map when there is one, and makes it only when there is none.
11 none Collects the directive definitions of the served schema: domain, link and reverseLink of LDS, and every other directive the schema file defines that is not one of graphql-java. The three of LDS come from a Set.of, so their order in the served schema is not fixed: the introspection showed them in another order after another start.
12 GraphQLTypeResolvingVisitor Resolves the references again.
13 RegistrySetupVisitor Sets the data fetchers and the type resolvers in a code registry. See Which fetcher a field gets.
14 none Builds the GraphQLSchema: Query as the query type, every other type of the map as an additional type, the directives of pass 11 and the code registry.

The Query builder is a field of GraphQLSchemaBuilder, so one instance builds one schema.

The definitions of @domain, @link and @reverseLink in the served schema are those of LDS, whatever the file declares:

GraphQL
directive @domain(searchable: Boolean = true) on OBJECT
directive @link(pagination: Boolean = true, reverseName: String) on FIELD_DEFINITION
directive @reverseLink(mappedBy: String, pagination: Boolean = true) on FIELD_DEFINITION

They are written in DomainDirective, LinkDirective and ReverseLinkDirective, and the introspection of the running LDS ({ __schema { directives { name locations args { name type { name } defaultValue } } } }) showed the same.

The walk, the type map and the builders

LDS has three classes of its own where graphql-java has something close. They are kept, because what the passes write follows from them.

TypeTraverser.depthFirst walks the roots it is given depth first, in the order given, and shows an element to the visitor before its children. The directives of an element are among its children; the applied directives are not. An element that was entered before, under any of the roots, is not entered again: the visitor gets visitBackRef. The same holds for a list or non-null type that wraps the same type as a list or non-null type that was entered before: what it wraps is not walked from there. The names of the reverse links, the mappedBy paths and the JSON Schema of a type follow from the order of this walk and from where it stops. The SchemaTraverser of graphql-java walks in another way and gives another result.

TypeCollectingVisitor puts every named type it meets into a LinkedHashMap, so the map keeps the order met. Two different types with one name stop it with an AssertException ("All types within a GraphQL schema must have unique names..."). getGraphQL uses the map it returns as the type map, and the later passes put into the same map.

SchemaElements gives the builders. A builder from it orders the parts of a type by name (ORDER), which is the order the introspection of the served schema shows. Directives stay in the order given. newObject(existing), newInterface(existing), newUnionType(existing) and newFieldDefinition(existing) start a copy from what the element holds now (its interfaces, its members, its type), not from the references it was built with. withDirective puts a directive on a field in the place of the one with the same name and drops the applied directive of that name. name(element) is null for a list and a non-null type. value(argument) and defaultValue(argument) give the value of an argument of a directive as a Java value.

Which fetcher a field gets

RegistrySetupVisitor looks at every field that has @link, @reverseLink or the search directive, after the connections are made. A type whose name ends in Connection is taken for a connection (isConnection).

The field The fetcher
has the search directive QueryConnectionFetcher
a connection, on Query PersistenceRootConnectionFetcher(entity)
a connection with @reverseLink PersistenceReverseLinksConnectionFetcher with the entity type of the nodes, the mappedBy path and the name of the type that holds the field
another connection PersistenceLinksConnectionFetcher with the name of the type that holds the field, the path from computePath and the name of the node type
a list that is not a connection, with @reverseLink none. The visitor logs ManyToOne: is not supported for reverse links at WARN.
another list that is not a connection PersistenceLinksFetcher(field, target)
not a list, on Query PersistenceFetcher(entity)
not a list, elsewhere PersistenceLinkFetcher(field, target). When the target is a union the target is the pattern of its members, (Cat|Dog).

For a list that is not a connection on Query the visitor has a branch that sets PersistenceLinkFetcher. LDS makes no such field: the list of an entity type on Query is always paged.

Every other field has the default fetcher of graphql-java, which reads the field from the map of its parent. So the scalar fields and the embedded objects (address, about) come from the document that a fetcher above them read.

Every interface and every union gets a type resolver. It reads the entry __graphql_internal_document_key of the map (a DocumentKey) and answers the object type with the name of the entity type of that key.

What is served for the example model

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    __schema {
      queryType {
        fields {
          name
          args {
            name
          }
          type {
            kind
            name
            ofType {
              name
            }
          }
        }
      }
    }
  }'
JSON
{
  "data": {
    "__schema": {
      "queryType": {
        "fields": [
          {
            "name": "Company",
            "args": [
              {"name": "after"},
              {"name": "before"},
              {"name": "first"},
              {"name": "last"}
            ],
            "type": {
              "kind": "OBJECT",
              "name": "CompanyConnection",
              "ofType": null
            }
          },
          {
            "name": "CompanyById",
            "args": [
              {"name": "id"}
            ],
            "type": {
              "kind": "NON_NULL",
              "name": null,
              "ofType": {"name": "Company"}
            }
          },
          {
            "name": "Person",
            "args": [
              {"name": "after"},
              {"name": "before"},
              {"name": "first"},
              {"name": "last"}
            ],
            "type": {
              "kind": "OBJECT",
              "name": "PersonConnection",
              "ofType": null
            }
          },
          {
            "name": "PersonById",
            "args": [
              {"name": "id"}
            ],
            "type": {
              "kind": "NON_NULL",
              "name": null,
              "ofType": {"name": "Person"}
            }
          }
        ]
      }
    }
  }
}

The field x of the Query of the file is gone. The introspection ({ __schema { types { kind name } } }) showed these types beside those of the introspection itself: the objects Address, Company, CompanyConnection, CompanyEdge, PageInfo, Person, PersonConnection, PersonEdge, Query and Text, and the scalars Boolean, DateTime, ID, Int and String. Date and Time are left out because no field uses them.

Person has got reversePersonFriends, and friends is a connection. Company has got employees, the reverseName of Person.employer:

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    __type(name: "Person") {
      fields {
        name
        args {
          name
        }
        type {
          kind
          name
          ofType {
            name
          }
        }
      }
    }
  }'
JSON
{
  "data": {
    "__type": {
      "fields": [
        {
          "name": "address",
          "args": [],
          "type": {
            "kind": "OBJECT",
            "name": "Address",
            "ofType": null
          }
        },
        {
          "name": "born",
          "args": [],
          "type": {
            "kind": "SCALAR",
            "name": "DateTime",
            "ofType": null
          }
        },
        {
          "name": "employer",
          "args": [],
          "type": {
            "kind": "OBJECT",
            "name": "Company",
            "ofType": null
          }
        },
        {
          "name": "friends",
          "args": [
            {"name": "after"},
            {"name": "before"},
            {"name": "first"},
            {"name": "last"}
          ],
          "type": {
            "kind": "OBJECT",
            "name": "PersonConnection",
            "ofType": null
          }
        },
        {
          "name": "name",
          "args": [],
          "type": {
            "kind": "NON_NULL",
            "name": null,
            "ofType": {"name": "String"}
          }
        },
        {
          "name": "reversePersonFriends",
          "args": [
            {"name": "after"},
            {"name": "before"},
            {"name": "first"},
            {"name": "last"}
          ],
          "type": {
            "kind": "OBJECT",
            "name": "PersonConnection",
            "ofType": null
          }
        }
      ]
    }
  }
}

A connection type has edges: [<Target>Edge!]! and pageInfo: PageInfo!. An edge has cursor: String! and node: <Target>!. PageInfo has hasNextPage: Boolean! and hasPreviousPage: Boolean! and no cursors.

DateTimeScalar

DateTimeScalar is the scalar DateTime. It writes a value with DateTimeFormatter.ISO_OFFSET_DATE_TIME, so the fraction of a second has the digits the value has. It reads a value with the DateTime of graphql-java-extended-scalars. That scalar writes three digits always, which is why LDS does not use it to write. Date and Time are the scalars of the library.

Shell
curl -s -i http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "ola") {
      name
      born
      employer {
        name
        founded
      }
    }
  }'
HTTP
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 154
Date: Fri, 20 Nov 2026 15:39:02 GMT

{
  "data": {
    "PersonById": {
      "name": "Ola Nordmann",
      "born": "1980-02-03T04:05:06.123456Z",
      "employer": {
        "name": "Globex",
        "founded": "2001-09-09T09:09:09.12+02:00"
      }
    }
  }
}

founded is stored as 2001-09-09T09:09:09.120+02:00 and comes out with .12.

A request

Reading the request

GraphqlHttpHandler.handleRequest moves the request to a worker thread (exchange.dispatch) and then reads it by its method.

Request What is read
GET The query parameters query, operationName and variables. variables is a JSON object as text. A parameter given twice is an IllegalArgumentException (more than one "query" parameter).
POST with a content type that holds application/(.*\+)?graphql The whole body is the query. This is tested first.
POST with a content type that holds application/(.*\+)?json The body is a JSON object. query is the query. variables is read when it is there and not null. operationName is read when it is there. The query parameters query, variables and operationName of the address are not read for a POST.
POST with another content type, or none 415, no body.
OPTIONS 200, no body, with the header Allow for GET, POST and OPTIONS.
another method 405, no body.

The two patterns (IS_GRAPHQL, IS_JSON) are searched for in the Content-Type header, in the case it is written. So application/json; charset=utf-8 and application/vnd.x+json are JSON, application/jsonx and x-application/json are taken for JSON too, application/graphql+json is taken for GraphQL text, and APPLICATION/JSON is answered 415. All of these were sent to the running LDS.

The body is read in the charset of the request (exchange.getRequestCharset()). The handler then makes a GraphQLUndertowContext of the exchange and the input and puts it into the context of graphql-java under the key GraphQLContext.class.

Shell
curl -s -G http://localhost:19111/graphql \
  --data-urlencode 'query=query A($id: ID!) { PersonById(id: $id) { name } } query B($id: ID!) { CompanyById(id: $id) { name } }' \
  --data-urlencode 'variables={"id":"acme"}' --data-urlencode 'operationName=B'
JSON
{
  "data": {
    "CompanyById": {"name": "Acme"}
  }
}
Shell
curl -s -i http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{ CompanyById(id: "acme") { name } }'
HTTP
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 40
Date: Fri, 20 Nov 2026 15:39:03 GMT

{
  "data": {
    "CompanyById": {"name": "Acme"}
  }
}

The time of the query

Every read is an as-of read at one instant, which this part calls the snapshot. GraphQLUndertowContext.getSnapshot(queryParameters, variables, clock) takes the first of these that gives a time:

  1. the query parameter snapshot of the request (SNAPSHOT_QUERY_NAME), for GET and for POST;
  2. the variable __snapshot (SNAPSHOT_VARIABLE_NAME);
  3. now, from Clock.systemUTC().

The value is read with ZonedDateTime.parse. A value that cannot be parsed gives nothing, and the next source is tried. More than one snapshot parameter and a __snapshot that is not a string are IllegalArgumentException. The snapshot is computed once, when the context is made, and every fetcher of the request uses it.

Shell
curl -s 'http://localhost:19111/graphql?snapshot=2021-06-01T00:00:00Z' -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "ola") {
      name
      employer {
        name
      }
      friends {
        edges {
          cursor
        }
      }
    }
  }'
JSON
{
  "data": {
    "PersonById": {
      "name": "Ola",
      "employer": {"name": "Acme"},
      "friends": {
        "edges": [
          {"cursor": "anne"},
          {"cursor": "kari"},
          {"cursor": "per"}
        ]
      }
    }
  }
}
Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/json' \
  -d '{
    "query": "{ PersonById(id: \"ola\") { name employer { name } } }",
    "variables": {"__snapshot": "2021-06-01T00:00:00Z"}
  }'
JSON
{
  "data": {
    "PersonById": {
      "name": "Ola",
      "employer": {"name": "Acme"}
    }
  }
}

A link is resolved as of the same instant. A link to a document that does not exist at the snapshot (a dangling link) gives null, and the same link gives the document at a time when it exists:

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "early") {
      name
      employer {
        name
      }
    }
  }'; echo
curl -s 'http://localhost:19111/graphql?snapshot=2031-01-01T00:00:00Z' -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "early") {
      name
      employer {
        name
      }
    }
  }'
JSON
{
  "data": {
    "PersonById": {"name": "Early", "employer": null}
  }
}

{
  "data": {
    "PersonById": {
      "name": "Early",
      "employer": {"name": "Future Ltd"}
    }
  }
}

The answer and the status codes

The handler executes with GraphQL.execute, turns the result into JSON (ExecutionResult.toSpecification) and sends it with status 200 and Content-Type: application/json. An error that graphql-java reports is in errors of a 200 answer: a query that cannot be parsed, a field the schema does not have, an exception in a fetcher.

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/json' \
  -d '{"query": "{ PersonById(id: \"ola\") { nmae } }"}'
JSON
{
  "errors": [
    {
      "message": "Validation error (FieldUndefined@[PersonById/nmae]) : Field 'nmae' in type 'Person' is undefined",
      "locations": [
        {"line": 1, "column": 27}
      ],
      "extensions": {"classification": "ValidationError"}
    }
  ]
}

<Entity>ById is declared non-null, so an id that has no document at the snapshot is an error of graphql-java, and data is null for the whole request:

Shell
curl -s -i http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "nobody") {
      name
    }
  }'
HTTP
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 473
Date: Fri, 20 Nov 2026 15:39:03 GMT

{
  "errors": [
    {
      "message": "The field at path '/PersonById' was declared as a non null type, but the code involved in retrieving data has wrongly returned a null value.  The graphql specification requires that the parent field be set to null, or if that is non nullable that it bubble up null to its parent and so on. The non-nullable type is 'Person' within parent type 'Query'",
      "path": ["PersonById"],
      "extensions": {"classification": "NullValueInNonNullableField"}
    }
  ],
  "data": null
}

The handler catches nothing. An exception while the request is read leaves the handler, and Undertow answers 500 with no body and logs UT005071: Undertow request failed with the stack trace:

Shell
curl -s -i http://localhost:19111/graphql -H 'Content-Type: application/json' -d '{}'
HTTP
HTTP/1.1 500 Internal Server Error
Connection: keep-alive
Content-Length: 0
Date: Fri, 20 Nov 2026 15:39:03 GMT

The same answer was seen for a GET without query, a body that is not JSON, text after the JSON document, an empty body, a body that is a JSON array, query that is null or a number, variables that is a text or an array, two query, two variables or two operationName parameters, variables of a GET that are not JSON, two snapshot parameters and a __snapshot that is a number. See Not finished and known to be wrong. An operationName that is a number in a JSON body is read as none, and the query is answered.

Two limits of graphql-java apply, both as errors of a 200 answer. A query of more than 15000 tokens is not parsed ("More than 15,000 'grammar' tokens have been presented. To prevent Denial Of Service attacks, parsing has been cancelled."). A request that asks for __schema or __type more than once is refused ("This request is not asking for introspection in good faith - Query.__type is present too often!"). LDS sets no limit of its own.

The handler is behind the handlers every request passes (the application). An OPTIONS request with Origin and Access-Control-Request-Method is answered by the CORS handler (204) and does not reach GraphqlHttpHandler.

GraphiQL

UndertowApplication serves the folder io/descoped/lds/graphql/graphiql of the class path at /graphiql, with graphiql.html as the welcome file.

Shell
curl -s -i http://localhost:19111/graphiql
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:19111/graphiql/
curl -s http://localhost:19111/graphiql/ | grep -o 'unpkg.com/[^"]*'
Text
HTTP/1.1 302 Found
Connection: keep-alive
Location: http://localhost:19111/graphiql/
Content-Length: 0
Date: Fri, 20 Nov 2026 15:39:03 GMT

200 text/html
unpkg.com/es6-promise@4.2.5/dist/es6-promise.js
unpkg.com/whatwg-fetch
unpkg.com/react@16/umd/react.production.min.js
unpkg.com/react-dom@16/umd/react-dom.production.min.js
unpkg.com/graphiql@0.12.0/graphiql.css
unpkg.com/graphiql@0.12.0/graphiql.min.js

The page loads its scripts from unpkg.com when it is opened, so the browser needs access to that host. It reads query, variables and operationName from its own address, and posts JSON to /graphql under the same prefix. Opened in a browser, the page sent an introspection query and then the query that was run, both as POST. With {"__snapshot":"2021-06-01T00:00:00Z"} as its variables the answer was as of that time. /graphiql/graphiql.html is not served: the path is an exact one, and the request is answered 400 Unsupported namespace: "graphiql".

How a field reads documents

The pattern

A fetcher gets the snapshot from the GraphQLContext of LDS and reads through RxJsonPersistence (the persistence interface). Every read opens a read-only transaction (createTransaction(true)) and closes it when the read is done. The methods of persistence return a Maybe or a Flowable, a reactive stream. A data fetcher of this part returns a value, so the fetcher waits for the stream on the worker thread of the request: blockingGet() on a Maybe, toList().blockingGet() on a Flowable. The range of a connection goes to the provider with the call.

A document becomes a Map (JsonDocument.toMap). The fetchers that feed other fetchers add the entry __graphql_internal_document_key with the DocumentKey of the document. The fetchers below need it to know which document they are in, and the type resolvers need it to name the entity type.

Fetcher Reads with Adds the document key
PersistenceFetcher readDocument(tx, snapshot, namespace, entity, id) yes
PersistenceLinkFetcher readDocument, with the entity type and the id taken from the link by the pattern /(?<type>TARGET)/(?<id>.*) yes
PersistenceLinksFetcher readDocument for each link that matches /TARGET/(?<id>.*) no
PersistenceRootConnectionFetcher readDocuments(tx, snapshot, namespace, entity, range), then hasPrevious and hasNext with the ids of the first and the last edge yes
PersistenceLinksConnectionFetcher readTargetDocuments once for every concrete type of the target (the members of a union, the implementations of an interface), merged with Flowable.merge yes
PersistenceReverseLinksConnectionFetcher readSourceDocuments with the id of the document, the mappedBy path and the entity type of the nodes yes
QueryConnectionFetcher SearchIndex.search(query, filter, from, size), then readDocument for every hit yes

The namespace is the one the builder was made with, namespace.default. QueryConnectionFetcher reads a hit from the namespace of its key.

Pages

ConnectionParameters.getRange makes the Range that persistence gets:

  • first given: Range.firstBetween(first, after, before). first wins when last is given too.
  • otherwise last given: Range.lastBetween(last, after, before).
  • neither: Range.between(after, before).

A negative first or last is an IllegalArgumentException ("The page size must not be negative: 'first'=-1"), which graphql-java reports in errors. The cursor of an edge is the id of its document (DocumentKey.id()), so after and before take ids.

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    Person(first: 2, after: "early") {
      edges {
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
    }
  }'
JSON
{
  "data": {
    "Person": {
      "edges": [
        {"cursor": "kari"},
        {"cursor": "ola"}
      ],
      "pageInfo": {"hasNextPage": true, "hasPreviousPage": true}
    }
  }
}

PersistenceRootConnectionFetcher always asks persistence for hasPrevious and hasNext. The two link connection fetchers ask only when the query selects pageInfo/hasPreviousPage or pageInfo/hasNextPage, by reading one document before the first edge and one after the last. An empty page has both false.

A reverse link reads the documents that hold the link, at the snapshot:

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    CompanyById(id: "acme") {
      name
      employees {
        edges {
          cursor
          node {
            name
          }
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
      }
    }
  }'
JSON
{
  "data": {
    "CompanyById": {
      "name": "Acme",
      "employees": {
        "edges": [
          {
            "cursor": "kari",
            "node": {"name": "Kari"}
          },
          {
            "cursor": "per",
            "node": {"name": "Per"}
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "hasPreviousPage": false
        }
      }
    }
  }
}

QueryConnectionFetcher turns the range into a position and a size (IndexBasedRange.fromRange), with MAX_SEARCH_LIMIT, 10, as the size when the query gives none:

  • first given: from the position of after, or 0; size first.
  • last given: up to the position of before, or 10; size last.
  • neither: from the position of after, or 0, up to the position of before, or 10.

It calls SearchIndex.search(query, filter, from, size) and waits for the answer. filter is the set of names of entity types of the argument, or null. Every hit is a DocumentKey; the fetcher reads the document of the key at the snapshot and leaves out a hit that has no document at that time, with the line Cound not find document for key ... at ERROR in the log. The cursor of an edge is from plus the number of edges before it, written as qc:<position> in base64url without padding (QueryConnectionCursor). hasPreviousPage is from > 0, and hasNextPage is from + size < total hits. With no edges both are false.

What a search finds is decided by the provider (search). The Solr provider finds a document by the texts of its fields named languageText. What search covers is under review.

The requests below were sent to LDS with search on and the index of the tests of core, io.descoped.lds.core.search.TestSearchIndex (provider id testSearchIndex). It finds a document by any text in it and applies neither the filter nor the page. LDS does not find that provider on the class path by itself; it was registered with a file META-INF/services/io.descoped.lds.api.search.SearchIndexProvider in a folder added to the class path. The model had the entity types Cat, Dog, Owner and Car. Solr was not run for this document.

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    Search(query: "the") {
      edges {
        cursor
        node {
          __typename
          ... on Cat {
            name
          }
          ... on Dog {
            name
          }
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
    }
  }'
JSON
{
  "data": {
    "Search": {
      "edges": [
        {
          "cursor": "cWM6MA",
          "node": {"__typename": "Cat", "name": "Felix the cat"}
        },
        {
          "cursor": "cWM6MQ",
          "node": {"__typename": "Dog", "name": "Fido the dog"}
        },
        {
          "cursor": "cWM6Mg",
          "node": {"__typename": "Cat", "name": "Tom the cat"}
        },
        {
          "cursor": "cWM6Mw",
          "node": {"__typename": "Dog", "name": "Rex the dog"}
        }
      ],
      "pageInfo": {"hasNextPage": false, "hasPreviousPage": false}
    }
  }
}
Shell
printf 'cWM6MQ==' | base64 -d
Text
qc:1

Configuration

The keys are read in UndertowApplication and SearchIndexConfigurator. The files and the rule for environment variables are in the application.

Key Default Meaning
graphql.enabled true true puts /graphql and /graphiql in place, when graphql.schema is not empty. With false, or with an empty graphql.schema, both paths are answered as a namespace that does not exist: 400 Unsupported namespace: "graphql".
graphql.schema empty in core, schemas/schema.graphql in the server The path of the schema file. It is the model too (the model).
graphql.search.enabled false true loads the search provider and adds the Search field.
search.index.provider empty in core, solr in the server The id of the search provider. An id that no provider has stops the start: No search index provider found for providerId: testSearchIndex.
namespace.default ns The namespace every fetcher reads from.
http.prefix / With /api, GraphQL is at /api/graphql and the page at /api/graphiql. /graphql is then 404.

Rules to keep

These rules hold for this part, beside the invariants of the project.

  • Keep TypeTraverser, TypeCollectingVisitor and SchemaElements. What the passes write follows from the order of the walk and from how a type is built. The SchemaTraverser of graphql-java walks differently.
  • Keep the order of the passes. See The passes of getGraphQL. A pass reads what the earlier passes wrote into the type map.
  • What LDS makes of a schema file is pinned. GraphQLSchemaGoldenTest compares the served schema, the JSON Schema and the specification of ten schema files with the files in src/test/resources/graphql-golden. A difference is a change of what LDS serves or stores. It is understood before an expected file is changed.
  • DateTime keeps the fraction the value has. Do not replace DateTimeScalar by the scalar of graphql-java-extended-scalars.
  • Streams stay streams. A read of persistence is a Flowable or a Maybe that the provider fills on demand. A fetcher may wait for it. Do not add a blocking call to the persistence interface and do not replace a stream by a call that returns a whole list (see Streaming on RxJava 3).
  • No spliced identifiers. An id, a cursor and a search text come from the request. They go to persistence and to the search index as arguments.
  • Time. Versions are compared as UTC instants. This part does not meet the rule yet; see Not finished and known to be wrong.
  • Tests. A new test class is JUnit 6 with AssertJ. A class that takes its server from TestServerListener is TestNG.

Tests

The tests are in linked-data-store-core/src/test/java/io/descoped/lds/graphql.

Test What it holds
schemas/GraphQLSchemaGoldenTest Builds the schema as the application does, without and with a search index, for ten schema files, and compares four texts for each with the files in src/test/resources/graphql-golden: .plain.schema.txt, .search.schema.txt, .jsonschema.txt and .specification.txt. CanonicalText writes the texts; a schema text names the fetcher of every field. Three more tests: the directives a file defines stay defined (syn-two-directives), a list of links to an interface is refused with a ClassCastException (syn-link-to-interface), and an argument the directive does not declare is refused (syn-undeclared-arg).
schemas/TypeTraverserTest, schemas/TypeCollectingVisitorTest, schemas/SchemaElementsTest The walk and where it stops, the order of the collected types, the builders.
schemas/DateTimeScalarTest The fraction of a second out, the values in.
directives/DirectivesTest, schemas/visitors/QueryVisitorsTest The definitions of the directives, the fields of Query.
schemas/visitors/AddConnectionVisitorTest, schemas/visitors/ReverseLinkBuildingVisitorTest Connections and reverse links on small schemas.
GraphqlHttpHandlerTest GET with query, variables and operationName; the content types of POST; a body or variables with something after the JSON document.
GraphQLUndettowContextTest The rules of the snapshot.
fetcher/PersistenceLinksFetcherTest, fetcher/QueryConnectionFetcherTest, fetcher/QueryConnectionCursorTest A list of links that is not paged, the position and the size that search makes of a range, the cursor of search.
GraphQLIntegrationTest Queries against LDS in the JVM (TestServerListener) with the model gqlschema/schema.graphql and the search provider testSearchIndex: links to abstract types, CORS on /graphql, search, linked documents.

GraphQLSchemaGoldenTest, TypeTraverserTest, TypeCollectingVisitorTest, SchemaElementsTest, DateTimeScalarTest, DirectivesTest, QueryVisitorsTest and PersistenceLinksFetcherTest are JUnit 6 with AssertJ. The others are TestNG.

Not finished: the paging of the fetchers that read persistence has no test that runs. fetcher/PersistenceRootConnectionFetcherTest is disabled as a class, and testForwardPagination and testBackwardPagination, the only tests of fetcher/PersistenceLinksConnectionFetcherTest, are disabled, all with @Ignore and a note that they hang. schemas/GraphQLSchemaBuilderTest has a main method and no test.

The command for a single test class has the form ./mvnw test -pl linked-data-store-core -Dtest=GraphQLSchemaGoldenTest. ./mvnw verify -pl linked-data-store-core -am builds and tests core and what it needs, and ./mvnw verify javadoc:javadoc is what CI runs. The build needs JDK 27 and Docker. The commands were not run when this document was written.

Not finished and known to be wrong

Everything below was seen by running LDS in memory, or is read from the code where that is said.

In the request handler

Not finished: GraphqlHttpHandler answers a request it cannot read with 500 and no body, and the reason is only in the log. That is so for a missing query, a query that is not a text, a body that is not JSON or not a JSON object, text after the JSON document, an empty body, a parameter given twice, variables that are not a JSON object, two snapshot parameters and a __snapshot that is not a string.

Not finished: the content type of a POST is matched in the case it is written, and anywhere in the header. APPLICATION/JSON is answered 415, and application/jsonx is read as JSON.

Not finished: a POST body is read in ISO-8859-1 when the content type names no charset, because that is what exchange.getRequestCharset() gives. A letter outside ASCII in a query sent as application/json is then read wrongly. With application/json; charset=utf-8 it is read rightly.

Not finished: the GraphiQL page sends its queries as application/json without a charset (graphQLFetcher in graphiql.html), so a letter outside ASCII in a query typed in the page is read wrongly. Seen in a browser: { PersonById(id: "åse") { name } } sent from the page did not find the document åse, and { PersonById(id: "ola") { name } } found ola.

Not finished: the answer to OPTIONS has Allow: GET twice.

Not finished: a snapshot that cannot be parsed is not refused. The query is answered as of the variable __snapshot when that is a time, and as of now otherwise. A date and time without an offset (2021-06-01T00:00:00) and a date alone (2021-06-01) are not parsed. A + written as it is in the address is read as a space, so ?snapshot=2021-06-01T02:00:00+02:00 is answered as of now, and %2B is needed.

Not finished: GraphQLUndertowContext does not turn the instant of the snapshot into UTC, and the REST handler does. With the memory provider a snapshot with an offset is compared by its local date and time. snapshot=2022-01-01T00:30:00%2B01:00 is 2021-12-31T23:30Z; GraphQL answered with the version of 2022-01-01 and REST, with the same value as timestamp, with the version of 2020-01-01.

In the schema builder

Not finished: a link to an interface stops the start, for a single link and for a list. ReverseLinkBuildingVisitor.addReverseField casts the target to GraphQLObjectType and throws a ClassCastException. A link to a union works.

Not finished: a type is taken for a connection when its name ends in Connection (RegistrySetupVisitor, ReverseLinkBuildingVisitor.computePath). An entity type named InternetConnection stops the start with a NullPointerException in RegistrySetupVisitor.visitConnectionLink, with links that point at it and without. A type without @domain and without links may have such a name: a model with the embedded type WifiConnection started and was read.

Not finished: the names of the types LDS makes are not kept free. AddConnectionVisitor does not make a type whose name is in the type map already, and uses the one that is there. Beside an entity type B, a type BConnection or BEdge of the schema file stops the start with the same NullPointerException in visitConnectionLink, with a list of links to B and without, because B has its list on Query. An entity type named PageInfo that a list of links points at stops it with an AssertException ("All types within a GraphQL schema must have unique names...") when the schema is built. With an entity type named PageInfo and no links LDS starts, and the field pageInfo of every connection has that entity type as its type: hasNextPage is refused as an undefined field. With search on, a type named TypeFilters or SearchResult stops the start with IllegalArgumentException ("type map already contains TypeFilters", or "... SearchResult") in AddSearchTypesVisitor.getQuery.

Not finished: the name of a reverse link is not checked against the fields the target has. ReverseLinkBuildingVisitor puts the reverse field on the target with field, which replaces a field of the same name. Two links to one target with the same reverseName (A.c and B.c, both reverseName: "owners") leave one field owners, which gave the documents of B only. A reverseName that is the name of a field of the target (reverseName: "name") replaced that field: name of the target was a connection in the served schema.

Not finished: when the exception comes from getGraphQL, the main thread ends and the process stays, without a server. This was seen for every case above that stops the start. When it comes from parseSchema, the process ends.

Not finished: the argument searchable of @domain has no effect. AddSearchTypesVisitor.isSearchable is deprecated and not called. A type with @domain(searchable: false) is in TypeFilters and in SearchResult.

Not finished: a field with @reverseLink(pagination: false) gets no fetcher and is always null. A @reverseLink field written in the schema file is also a property of the JSON Schema of its entity type (the model).

Not finished: links in a type without @domain (an embedded type) work for a single link only. A list of links there fails with Cannot invoke "io.descoped.lds.api.persistence.DocumentKey.id()" because "key" is null, because the map of the embedded object has no document key. The reverse fields LDS adds for such links are connections of the embedded type (HomeConnection) and find nothing: the source of a reverse link is the type that holds the link field, and mappedBy is the path inside that type.

Not finished: what LDS makes of a link in a type without @domain follows from the order of the walk, which is the order of the names of the types. In a model with Address { city: City @link }, Zone { city: City @link } and the entity type Person { home: Address zone: Zone }, City got the fields reverseCity (Address is walked before Person, so no entity type is among the parents of the field) and reversePersonZoneCity (Zone is met first below Person). The path that PersistenceLinksConnectionFetcher gets for a list of links in such a type is computed in the same way; the expected file syn-embedded.plain.schema.txt of GraphQLSchemaGoldenTest has $.reverseZipArea[].edges[][].node.area[] for Zip.area.

Not finished: LinkDirective.getPagination and ReverseLinkDirective.getPagination return the default in both branches. ReverseLinkDirective.REVERSE_LINK_DIRECTIVE is not used. JsonSchemaBuilder is an empty class. EmptyPersistence is used by the main of GraphQLSchemaBuilderTest only. GraphQLContext has a TODO about its name, which is that of a class of graphql-java.

Not finished: PersistenceLinkFetcher does not check that the link field is there. A document without the field gives an error and null for the field:

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/json' \
  -d '{
    "query": "{ PersonById(id: \"anne\") { name employer { name } } }"
  }'
JSON
{
  "errors": [
    {
      "message": "Exception while fetching data (/PersonById/employer) : Cannot invoke \"java.lang.CharSequence.length()\" because \"this.text\" is null",
      "locations": [
        {"line": 1, "column": 33}
      ],
      "path": ["PersonById", "employer"],
      "extensions": {"classification": "DataFetchingException"}
    }
  ],
  "data": {
    "PersonById": {"name": "Anne", "employer": null}
  }
}

Not finished: with last, or with before alone, PersistenceRootConnectionFetcher and PersistenceReverseLinksConnectionFetcher give the edges with the last id first, and hasNextPage and hasPreviousPage are computed as if the first edge had the lowest id:

Shell
curl -s http://localhost:19111/graphql -H 'Content-Type: application/graphql' \
  -d '{
    Person(last: 2) {
      edges {
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
    }
  }'
JSON
{
  "data": {
    "Person": {
      "edges": [
        {"cursor": "per"},
        {"cursor": "ola"}
      ],
      "pageInfo": {"hasNextPage": true, "hasPreviousPage": true}
    }
  }
}

Not finished: a connection of links does not page with the memory provider. after and before are not applied, and pageInfo is true and true when there is an edge. Ola has three friends at this time, and anne is the first:

Shell
curl -s 'http://localhost:19111/graphql?snapshot=2021-06-01T00:00:00Z' -H 'Content-Type: application/graphql' \
  -d '{
    PersonById(id: "ola") {
      friends(first: 1, after: "anne") {
        edges {
          cursor
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
        }
      }
    }
  }'
JSON
{
  "data": {
    "PersonById": {
      "friends": {
        "edges": [
          {"cursor": "anne"}
        ],
        "pageInfo": {"hasNextPage": true, "hasPreviousPage": true}
      }
    }
  }
}

The memory and PostgreSQL providers answer readTargetDocuments through RxJsonPersistenceBridge.readTargetDocuments, which sorts the links and takes the limit and does not apply after and before. Neo4j was not run for this document.

Not finished: a connection of links to a union gives wrong pages. PersistenceLinksConnectionFetcher gives every member type the whole limit, merges, takes the limit again and sorts after that. With the links fido, rex (two Dog) and tom (a Cat), pets(first: 2) gave fido, tom and pets(last: 2) gave rex, fido. The two reads for pageInfo are made with the name of the union as the entity type, and no link holds that name: with the memory provider hasNextPage and hasPreviousPage were false for every page, also for pets(first: 1) of three.

Not finished: PersistenceLinksFetcher gives documents without the document key. A connection below a document from a list that is not paged fails with the same "key" is null error. A link in the list whose document does not exist gives a null element. A list that is not paged and points at a union finds nothing: the pattern is made of the name of the union, and a link holds the name of an entity type. pets: [Pet] @link(pagination: false) with two links in the document gave "pets":[].

Not finished: in QueryConnectionFetcher the edge at the after cursor is given again (the position of the cursor is the start, not the position after it). last without before counts back from 10 and not from the number of hits, and a last above that end gives a start below zero: Search(last: 20) asked the index from position -10, and the first cursor was qc:-10. first has no upper limit. The text of query goes to the search provider as it is.

Not finished: TestSearchIndex is in the main code of core and in provides of module-info.java, but not in META-INF/services of the main resources. LDS runs on the class path, where it is then not found.

Not finished: PageInfo has no startCursor and no endCursor.

Not finished: with the memory provider, a document whose id begins with a letter outside ASCII (åse) is read by <Entity>ById and is not in the list <Entity>. REST shows the same for GET /ns/Person, so the cause is below this part.

Not finished: the GraphiQL page is GraphiQL 0.12.0 with React 16, loaded from unpkg.com when the page is opened. whatwg-fetch is loaded without a version.