A well-designed schema is one your editors, developers, and business stakeholders can all work with confidently. These best practices cover the decisions that have the most impact on the quality and longevity of your schema.

#Plan before you build

The most common cause of schema problems is starting in the schema editor too early. Before adding a single model, you should have:

• A clear picture of your business domain and the content it produces
• A list of object domains and their attributes, agreed on as a team
• A rough domain model showing how those objects relate to each other

Building without this foundation leads to models that reflect how content is currently stored rather than how it should be structured — and restructuring later is expensive once editors have created content against the schema.

For a guided walkthrough, see Plan your content model.

#Model content semantically

Model what a piece of content is, not how it will look on a specific frontend.

A model named HeroBanner with fields like backgroundGradient and ctaButtonColor is tightly coupled to a single frontend layout. A model named FeaturedArticle with fields like headline, summary, and coverImage describes content. The second approach works across any website, mobile app, or third-party integration, without requiring schema changes.

This matters most if you plan to deliver content to more than one channel. Even if you are starting with a single channel, semantic models are easier to extend and maintain over time.

#Keep models focused

Each model should represent one clear concept. If you find yourself adding a field that does not belong to the core concept a model represents, that is a signal to either create a new model or use a component.

Models that try to serve too many purposes create confusion for editors, produce bloated API responses, and make the schema harder to reason about. A LandingPage model with 40 fields is almost always a sign that several concepts have been collapsed into one.

#Use components for repeated field groups

If the same group of fields appears on more than one model, make it a component. Examples include:

• SEO metadata (metaTitle, metaDescription, canonicalUrl)
• Address fields (street, city, country, postalCode)
• Call-to-action blocks (headline, bodyText, buttonLabel, buttonUrl)

Defining these once as components means you update them in one place. If you later need to add an ogImage field to your SEO component, it propagates to every model that uses it automatically.

Use modular components when editors need to compose content from a variable set of building blocks. For example, a page that can contain any combination of hero sections, feature grids, and testimonials.

#Define relationships explicitly

Avoid duplicating data across models. If two models share a concept, use a reference field rather than adding author fields to both models. For example, both a Product and a BlogPost refer to an Author.

Explicit relationships have several benefits:

• Modifying an author's name or photo updates it wherever the author is referenced
• You can query related content in a single API call
• The schema accurately reflects how your business domain is structured

When setting up a two-way reference, think carefully about whether the relationship is one-to-one, one-to-many, or many-to-many, before creating the field.

#Establish naming conventions early

Inconsistent naming creates confusion for editors and makes the API harder to work with. Agree on a naming convention before building and apply it consistently. A few patterns worth deciding on upfront:

• Field naming: Stick to camelCase, which is the Hygraph default for API IDs.
• Boolean fields: Prefix with is or has to make the meaning clear (isPublished, hasFeaturedImage).
• Reference fields: Name them after the model they point to, in singular or plural depending on cardinality (author for one, authors for many).
• Model names: Use singular nouns (Article, not Articles).

Naming conventions are especially important in larger projects where multiple developers and editors work on the schema over time.

#Design for editorial usability

A schema that is technically correct but difficult to use will slow down content creation and lead to errors. When adding fields to a model, consider:

• Field order: Put the most important fields at the top of the form. Editors fill forms top to bottom.
• Required fields: Only mark a field as required if an entry genuinely cannot be published without it. Over-requiring fields creates friction.
• Field descriptions: Use the description option on fields to explain what is expected, especially for fields where the purpose is not obvious from the name.
• Enumerations over free text: Where a field has a fixed set of valid values, use an enumeration rather than a text field. This prevents inconsistent data entry and reduces editorial errors.

#Plan for growth

A schema that works for your current content volume may not work at scale. A few things to consider:

• Avoid deeply nested structures: Deep nesting creates complex queries and can affect API performance. If you find yourself nesting components inside components inside components, reconsider the structure.
• Use environments to test schema changes: Before making structural changes to a live schema, test them in a separate environment to verify the impact on queries and editorial workflow.
• Revisit the schema periodically: As the business changes, the schema should change with it. A periodic review against current business goals catches misalignment before it becomes a problem.

#Dos and don'ts

Use this as a quick-reference checklist when reviewing a schema.

#Dos

#Don'ts

#What's next

• Plan your content model: A practical guide to research, stakeholder involvement, and schema design.
• Content modeling walkthrough: See these principles applied in a complete schema walkthrough.