#Content modeling in Hygraph
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:
| Type | Use for |
|---|---|
| Single line text | Short strings: titles, names, slugs |
| Multi line text | Longer plain text without formatting |
| Rich text | Formatted content with headings, links, embeds |
| Markdown | Markdown-formatted content |
| Integer | Whole numbers |
| Float | Decimal numbers |
| Boolean | True/false values |
| Date | Date without time |
| Date and time | Date with time |
| Color | Hex color values |
| Location | Geo coordinates |
| JSON | Arbitrary JSON data |
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:
| Modifier | Description |
|---|---|
| Required | The field must have a value before an entry can be saved |
| Unique | No two entries in the same model can share the same value for this field |
| List | The field stores multiple values of the same type rather than a single value |
| Localized | The field stores a separate value per locale |
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:
| Type | Description |
|---|---|
| Basic component | Embeds a single component type. Can allow one or multiple instances. |
| Modular component | Allows editors to choose from a set of different component types when filling in the field. |
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.
| Field | Type | Description |
|---|---|---|
id | String | A unique identifier for each entry |
createdAt | DateTime | When the entry was first created |
updatedAt | DateTime | When the entry was last modified |
publishedAt | DateTime | When the entry was last published |
createdBy | User | The user who created the entry |
updatedBy | User | The user who last modified the entry |
publishedBy | User | The user who last published the entry |
documentInStages | [model] | Query the current document in other stages |
#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.