Once you have a clear picture of your content model conceptually, you need to know how to express it in Hygraph. This page covers the schema building blocks available to you: what each one is, what it does, and when to use it.

Content modeling with Hygraph

#Models

A model is the core building block of your schema. It defines the structure of a single kind of entry. Article, Author, Product, and Category are all examples of models.

In Hygraph, every model you create automatically generates the corresponding GraphQL queries and mutations in your Content API. You do not write any API code manually; instead, the schema editor generates it as you build.

Think of a model as analogous to a database table. The model defines the structure and individual content entries are the rows.

#Fields

Fields define what data a model stores. Each field has a type that determines both the kind of data it accepts and how it appears in the content editor. A Single line text field renders as a text input; an Asset picker field renders as a file uploader; a Boolean field renders as a toggle.

Hygraph provides the following scalar field types:

For the complete field type reference including configuration options, see Field types.

#Field modifiers

Every field supports a set of modifiers that change how it behaves:

Modifiers can be combined. A localized, required Single line text field, for example, must have a value in each locale where you save that localization. When publishing, you can select which locales to include; the default locale is always required.

For the full modifier reference, see Field configuration.

#References

References connect models to each other. A reference field on a Product model that points to a Product Categories model creates a relationship between the two. You can navigate from a product to its category and query both in a single API call.

Hygraph supports two-way references, which means the relationship is visible from both sides. When you create a reference from Product to Product Categories, a reverse field is automatically available on Product Categories that lists all products associated with that category.

References can be configured to allow one or many related entries, and they can be restricted to a single model or open to multiple model types (using a union reference).

References

#Components

A component is a reusable group of fields. Unlike a model, a component cannot exist as a standalone entry. It is always embedded within a model or another component.

Components are useful when the same group of fields appears across multiple models. An SEO component containing a meta title, meta description, and canonical URL field, for example, can be added to every model that needs it. Update the component definition once and it updates everywhere.

Hygraph supports two types of component fields:

Modular components are particularly powerful for page-building patterns, where editors can compose a page from a defined set of blocks, such as a hero, a feature list, a testimonial. No developer support is required to create a separate model for each page layout.

Components

#Enumerations

An enumeration (enum) defines a fixed set of allowed values for a field. At the API level, GraphQL enums provide schema-level validation. A field typed to an enum can only contain one of the defined values.

Enums work well for status values (DRAFT, PUBLISHED, ARCHIVED), sort orders (NAME_ASC, PRICE_DESC), or any other field where the set of valid values is known in advance and should be enforced.

#Taxonomies

Taxonomies let you define hierarchical, centrally managed vocabularies that classify content across multiple models. Each taxonomy is a tree of nodes arranged in a parent-child hierarchy, supporting up to six levels of depth. For example: Root → Category → Subcategory → Topic

Once defined, a taxonomy is applied to a model as a taxonomy field. Editors select a node from the hierarchy when creating or updating a content entry. At the API level, a taxonomy field exposes two values:

• value: The taxonomy node assigned to the entry.
• path: An array of the full hierarchy path up to the assigned node.

This path-based structure enables advanced GraphQL filtering using operators like descendants_of, making taxonomies well suited to faceted navigation, personalized content feeds, and search filtering.

#System artifacts

Hygraph automatically generates a set of models, fields, and capabilities that every project includes by default.

#Asset model

The Asset model stores uploaded files: images, videos, audio files, and PDFs. Every project has one automatically.

Hygraph includes a built-in image transformation API that lets you crop, resize, and reposition images at query time by passing transformation parameters in the URL or GraphQL query, rather than storing multiple variants.

#User model

Every Hygraph project member is a User. The user model is managed automatically and is connected to every content entry and asset, so you can always identify who created, updated, or published a piece of content.

User data is also available through the Content API, so you can query author names and avatars alongside content if your application needs it.

#System fields

Hygraph adds the following fields to every model automatically. You do not need to define them.

#Modeling for content reuse

If you plan to deliver content across multiple platforms, such as a website, a mobile app, a third-party integration, keep your models free of presentational information.

A model named Hero with fields like backgroundGradient and buttonAlignment is tightly coupled to a specific frontend layout. A model named FeaturedArticle with fields like headline, summary, and coverImage describes content, not presentation. The second approach works across any platform, whereas the first only works for one.

This principle is called semantic modeling: model what a piece of content is, not how it should look. Hygraph's API delivers the data; the frontend decides what to do with it.

If you are building for a single channel and your editors need to work independently on page layouts, structuring models closer to your frontend component structure is a reasonable trade-off. Just be aware that it reduces content reusability.

#Access controls

Once your schema is defined, you can configure fine-grained permissions for every model and field. Permissions control what content editors can see and edit in the UI, and what API tokens can read or write through the Content API.

For example, you can create an editor role that can update Article entries but cannot publish them, or an API token scoped to read-only access on a subset of models.

For the full permissions reference, see Roles and permissions.

#What's next

• Plan your content model: A practical guide to research, domain modeling, and schema design before you start building.
• Field types: Complete reference for all field types and their configuration options.
• Field configuration: Reference for field modifiers, validations, and appearance settings.
• Content modeling walkthrough: See all of these concepts applied in a complete schema walkthrough.