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.
- 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
- 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
itemTypesfield of thefilterinput filter used by theitemsquery
- 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
authorNamein 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.)
{
__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.)