Documentation Center

Semantic Content Models

To process content in JSON format that has been published to Content Delivery using data publishing, you can create your own Semantic Content Model for GraphQL, and customize JSON content transformation. Specifically, you define your own schemas in a text file using GraphQL Schema Definition Language (GraphQL SDL). Semantic Content Models let you change the structure of the published content, or create a custom endpoint that retrieves only some fields of the JSON data fragment.

Semantic Content Modeling extends the core GraphQL API offered through the Public Content API by adding new content types, and fields within those types, that mirror the Schemas used on the Content Manager side. Content Manager defines the underlying information architecture of the content; Semantic Content Modeling makes this architecture available on the delivery and presentation side. As a result, the choices that web content editors make within Content Manager determine how websites are built and what types they work with. By defining a Schema in Content Manager, the editor effectively also defines a content type that is exposed in GraphQL. Specifically, this means that:
  • Components can be given a content type and requested through the Public Content API.
  • The Public Content API is a dynamic, changing API, but its core queries remain consistent; Semantic Content Modeling simply extends the content type system to reflect what is created within the Content Manager.

Using Semantic Content Modeling makes the API both abstract and dynamic. Rather than being an immutable contract between parties, as is typical for APIs, the Public Content API enhanced with Semantic Content Modeling changes as Content Manager Schemas are added, removed or modified. The benefit of this approach is that web developers can work with the same concepts and abstractions as the content authors and authoring tools. Schemas are now used to drive the content types exposed by GraphQL to the web developer --types that make sense for their context. When building a website for a specific sector, it makes sense to work with content types and content that reflect that sector, as opposed to abstract Components.

Semantic Content Modeling also gives implementers a simple IDE for browsing the new generated content types and building queries to retrieve data. The content structure designed by web content editors is immediately available to web developers. As the website develops, types become more rigid and less likely to change. Additionally, implementers can use development tools, through introspection of the Public Content API schema, to auto-generate the complete data model of the web application. Because such tools offer complete code generation, web developers don't need to write raw GraphQL queries; instead, they can query and work directly with the content types originally defined in Content Manager.

Semantic Content Modeling lets the implementer access everything they need in a single request, as opposed to having to perform multiple requests to get further data, such as Component resolving, rich text fields, or metadata.