Content Manager Schemas and the Public Content API

The Semantic Type Modeling feature exposes Schemas and their fields, as defined in Content Manager, to the Public Content API so that you can query them and use them. In order to use them effectively, you, the web developer, must know what the Schemas are and what fields they contain.

Schemas and fields

When a Content Manager user creates a Schema and defines its content and metadata fields, the Schema and its fields become available to the Public Content API. You can then construct GraphQL queries that explore and retrieve Components and Pages based on those Schemas.

Unlike the rest of the Public Content API, which is an agreed-upon, fixed interface between two parties, this part of the API is dynamic and subject to change. If a Schema changes in Content Manager and the change gets published, this can affect your API calls. There are several ways in which you can mitigate the fact that the API is not fixed:
Coordinate with Content Manager Schema creators
Ideally, you will want to communicate with the people creating your Schemas, and to learn the names of the available Schemas and their fields from them. You can also help them avoid giving bad names to their Schemas (see below).
Use API introspection
Use any of a variety of open source software tools (such as the one found at https://www.graphql-code-generator.com) to generate a full data model directly from the GraphQL schema, using the Public Content API endpoint to do so. The full data model contains all the GraphQL types (including types defined through Content Manager Schemas), as well as the code needed to request and deserialize those types for you in whatever language you need. As a result, you no longer need to write raw GraphQL queries. This process, called introspection, makes building web applications far quicker.

Naming conventions

Semantic Type Modeling may change Schema names and Schema field names to enforce naming conventions in the API. Specifically:
Schema names
In the Public Content API, Schema names are exposed as a type name in two contexts:
  • as a query field
  • as an enumeration value in the itemTypes field of the filter input filter used by the items query
When used as a query field, the type name is written in upper camel case. For example, a Schema called "News Article" in Content Manager is called NewsArticle when used as a query field.
When used as an enmueration value, the type name is written in snake case (in all caps with underscores for spaces), as an item type. For example, a Schema called "News Article" in Content Manager is called NEWS_ARTICLE when used as an enumeration value for itemTypes.
The following query illustrates both naming conventions:
items(filter:{itemTypes:[NEWS_ARTICLE]}) {
  edges {
    node {
      ...on NewsArticle {
        metadata {
          authorName
          lastModifiedDate
        }
      }
    }
  }
Schema field names
In the Public Content API, Schema field names are written in lower camel case. For example, a Schema field called "Author Name" in Content Manager is called authorName in the API.

Naming conflicts

It is possible for two Schemas in Content Manager to have the same name, provided that they live in different Content Manager folders. But this would lead to a conflict in the Public Content API, which must have unique names for types. To prevent such naming conflicts, you can ask the Content Manager users to always make Schema names unique (which is good practice anyway).

If this type of naming conflict is nevertheless encountered, it is resolved by adding the name of the Content Manager parent folder, followed by an underscore, as a prefix to the type name in order to remove the ambiguity. For example, given two Schemas in Content Manager, both called "Press Release", one in a folder called "Schemas" and another in a folder called "Structures", the corresponding types in the API are called Schemas_PressRelease and Structures_PressRelease, respectively. (If even the parent folder names have the same name, further ancestor folders are added as needed.)

Another type of naming conflict can occur when users who create Schemas gives a Schema a name that is already the name of a predefined type in the core Public Content API. To prevent such naming conflicts, you can supply the users with a list of predefined types, and tell them to avoid those. To obtain such a list, disable Semantic Type Modeling in the Content Service (by editing application.properties) and then run the following GraphQL query:
{
  __schema {
    types {
      name
    }
  }
}

The query result is the list of type names that the Schema creators should avoid.

If this type of naming conflict is nevertheless encountered, it is resolved in the same way as for the same-name naming conflict, that is, by adding the name of the folder, followed by an underscore, as a prefix to the type name in order to remove the ambiguity.

Another conflict can occur with schema field names. If you define a schema with a field name that is already a property of a Page or Component, it will be hidden. For example, imagine you add a Schema field named updatedData. This property already exists in a Component, so defining a field in your Schema with this name will cause it to be hidden. (We will fix this in future by adding a prefix or suffix.)