A well-designed schema starts well before you open the schema editor. The decisions you make during planning, such as understanding your domain, aligning your team, and mapping relationships between concepts, determine whether your schema will serve you for years or constrain you within months. This guide walks through each stage of the process.
#Deconstruct your domain
Start by understanding the subject area your content will cover. Identify the key concepts in your domain and consider how they connect to each other.
Your research can begin online, but it should include conversations with subject matter experts (SMEs) and real users. The output of this process is a list of terms and definitions that you will use when building your schema. These concepts need to be clear and agreed upon before modeling begins. Ambiguous terminology leads to ambiguous models.
References
As you build your list, distinguish between object domains and attributes:
- An object domain is a thing that exists independently. For example,
Author or Book. It will likely become a model in your schema.
- An attribute is a characteristic of an object. For example,
name is an attribute of Author, not an object in its own right. If a concept can be answered with a specific value, it is probably an attribute. It will likely become a field in your model.
#Involve your stakeholders
Content modeling requires cross-functional input. Research gives you a starting point, but the perspectives of people across your organization, such as editors, developers, researchers, and business leaders, are what make a model genuinely usable by everyone who works with it.
#Who to involve
- UX researchers and BI professionals: UX researchers have detailed knowledge of user behavior and needs. BI professionals can identify business performance trends the model should support. Both help align the schema with real-world usage.
- Individual contributors: The people who work inside the CMS every day know what works and what doesn't. Editors know the pain points of content creation. Developers know the technical constraints. Sales and support teams know what customers actually need from the product.
- External experts: Depending on your subject domain, an outside expert can fill gaps that internal teams cannot cover.
#Why it matters
Collaborating across roles reduces silos, surfaces blind spots, and produces a model that serves everyone who works with it. The people who will use the schema every day should help design it.
#How to run discovery sessions
Prepare before each session. Write out your questions in advance and decide how you will capture the information. Recording sessions, with the interviewee's consent, is more reliable than notes alone.
One effective technique is card sorting. Write key concepts on cards and ask the interviewee to organize them into categories while explaining their reasoning. Bring blank cards so interviewees can add concepts you have not thought of yet.
After your sessions, compile what you gathered into three things:
- A list of terms and their definitions.
- A map of how those terms relate to each other.
- A clear separation of object domains from attributes.
You will use all three directly when building your domain model.
#Build a domain model
Bring your cross-functional team together to build a domain model, which is a high-level map of your business, its key objects, and how those objects relate to each other.
The domain model covers the full scope of the business, not just what will be published through the CMS. For a bookshop, that includes inventory, orders, promotions, staff management, and suppliers, not just books and authors. You need this full picture before deciding what belongs in the schema.
A practical way to run this session is with sticky notes or a shared whiteboard tool. Arrange your object domains spatially and draw connections between them. Since you have done your research beforehand, bring a first-draft sketch rather than starting from a blank canvas. This gives the team something to react to and refine rather than building from scratch.
The result should be a shared, agreed-upon picture of how your business operates. This becomes the reference for the next step, where you decide which parts of the domain model belong in your Hygraph schema.
#Build your schema
You can use Hygraph's schema editor to draft and iterate on your schema as you go. This lets you see what a content entry form will look like for editors at every step of the way.
Your schema is the portion of the domain model you bring into Hygraph.You need to bring in only those objects that represent content your editors will create and your users will interact with. Not every object from the domain model belongs in the schema.
Look at your domain model and select the object domains relevant to published content. These become models in Hygraph. The attributes of each object become fields on those models. Relationships between objects become reference fields.
For example, if you have an Author model, then name, bio, and picture would be fields on it. A relationship between Author and Book would be a two-way reference field, meaning you can navigate from a book to its author and from an author to their books.
Hygraph project schema
The result is a schema containing a set of models connected by references, where each model contains the fields that represent its attributes.
#Content templates and dynamic page composition
Content templates & dynamic page composition
Think of each model as a template. When you defined your models and fields during planning, you were deciding what those templates would contain. Now you build them out.
Hygraph's components are particularly useful here. A component is a predefined group of fields that can be reused across different models without duplicating field definitions.
Component fields can be:
- Basic: Embeds a single component type, allowing one or multiple instances.
- Modular: Allows editors to choose from a set of different component types when filling in the field.
Using a modular component field, you can create a model that behaves differently depending on what the editor selects. A Book model could have a modular component field for banners, where editors choose between a promotional banner and a new arrivals slider, or add no banner at all. A single model can have multiple possible content configurations.
#Classification using references
A common pattern for organizing and categorizing content in Hygraph is to create a dedicated model for each category type, create entries for each category value, and connect that model to the models that need categorizing using a two-way reference field.
For example, a Genre model with a name field and a description field can be connected to a Book model via a two-way reference. Editors assign one or more genres to each book entry. At the API level, you can query all books in a given genre, or query a book and retrieve its genres in the same request — because the relationship is defined in the schema.
This approach works well when category entries need their own rich content, such as descriptions, images, or related metadata. The same Genre model can be referenced by multiple other models, keeping classifications consistent without duplication.
If you need a hierarchical, centrally governed classification system that is shared across many models, consider using Hygraph's dedicated Taxonomies feature instead. Taxonomies are an enterprise feature and support up to six levels of hierarchy with advanced API filtering capabilities.
#Terminology reference
Content modeling literature uses different terminology than Hygraph. This table maps the common terms to their Hygraph equivalents.
| Content modeling term | Hygraph term |
|---|
| Content model | Schema |
| Object domain | Model |
| Content type | Model |
| Attribute | Field |
| Property | Field |
| Relationships | References, relations |
| Content instance | Entry |
#What's next