GraphQL features a type system (see https://graphql.org/learn/schema/) which is independent of a particular implementation language. Types are written in a special formal language, the Schema Definition Language (SDL). The set of types defined with this SDL is then collectively called the GraphQL schema.

The schema essentially defines what data can be queried from the GraphQL server. Therefore, the GraphQL schema is one way to restrict the information a possible client can retrieve from the Headless Server. Another way would be to use a different CoreMedia CMS user with a different set of rights.

Each query is validated against the schema before query execution, any query that fails this validation is rejected by the Headless Server.

A GraphQL schema for a subset of the CoreMedia Blueprint content model is defined in the file content-schema.graphql. In this schema file, the GraphQL query root type Query is defined and contains a field content of the GraphQL type ContentRoot. This root object supports CoreMedia CMS content repository access. It is implemented by the Spring bean content of the equally named Java class ContentRoot. Further content fields can be added to the GraphQL schema. These must then be implemented either by a @fetch directive (see section Section 4.3, “The @fetch Directive”), or by subclassing the ContentRoot class. In the latter case, an instance of the new subclass must replace the ContentRoot instance in the Spring configuration. The GraphQL type ContentRoot is bound to the Spring controller class ContentRootController by the Spring-GraphQL annotation @QueryMapping.

The query root type is extensible by adding a Spring controller with the Spring-GraphQL annotation @QueryMapping and a method named correspondingly to the query name. These controllers are also used for the eCommerce integration and the metadata root.

A GraphQL schema for the Headless Server may be split into several files. So, additional GraphQL types and interfaces can either be added to the schema by extending the file content-schema.graphql, or by adding more GraphQL schema resource files to the classpath. The preferred way of adding schema extensions is a Spring bean of type Resource along with the qualifier annotation @Qualifier("graphqlSchemaResource"). During startup, the Headless Server collects all beans with that qualifier and merges them together, yielding the complete schema.

  @Bean
  @Qualifier("graphqlSchemaResource")
  public Resource mySchemaResource() throws IOException {
    PathMatchingResourcePatternResolver loader = new PathMatchingResourcePatternResolver();
    return Arrays.stream(loader.getResources("classpath*:graphql/my-path/my-schema-extension.graphql"))
            .findFirst()
            .orElseThrow(() -> new IOException("GraphQl schema resource graphql/my-path/my-schema-extension.graphql' not found."));
}

Further adapters (Section 4.8, “Adapter”), model mappers (Section 4.5, “Model Mapper”), filter predicates (Section 4.6, “Filter Predicates”), or GraphQL scalar types can be defined as Spring beans in CaasConfig.java, or by adding a new Spring configuration class.

All these extensions can be made within the headless-server-base module within the blueprint workspace. However, a better practice is to add a new Maven module with its own Spring configuration and schema resource as a Spring bean. This separates your extensions from future changes within the headless-server-base module. The eCommerce integration module described in Chapter 7, eCommerce Extension may serve as an example.