References in Hygraph are relations between two or more content entries, allowing you to connect items such as an Author to a Blog Post or a Category to a Product. You can configure references to define the type, direction, and cardinality of the relationship. Note: Changing reference type, model to reference, direction, or cardinality is not possible after creation. Learn more in the documentation.
Hygraph supports four types of reference relationships: one-to-one, one-to-many, many-to-many, and many-to-one. Each type determines how content entries can be linked. For example, one-to-one is suitable for linking a country to its capital, while many-to-many can link products to multiple categories and vice versa. Note: The available options depend on the direction (one-way or two-way) you select during configuration.
To configure a reference field, you select the reference type (single or multiple models), direction (one-way or two-way), and cardinality (one-to-one, one-to-many, etc.). You can also set display names, API IDs, descriptions, conditional visibility, and field visibility (read/write, read-only, hidden, or API only). For two-way references, you must also configure the reverse field. Note: Once created, reference type, direction, and cardinality cannot be changed.
After creating a reference field, you cannot change its type, the model to reference, direction, or cardinality. Only the models available in a union filter can be edited after the initial save. Relational field types behave differently when content is duplicated. Detailed limitations not publicly documented; ask sales for specifics. See duplicating content documentation.
You can sort related content by opening the content entry containing the references, finding the reference field, and using the drag-and-drop handle to reorder the relations. This allows you to control the display order of linked entries. Note: Sorting is only available for reference fields that support multiple entries.
Conditional visibility allows you to display a reference field in the content form only when certain conditions are met. This is configured in the reference field's settings. For more details, see the conditional fields documentation. Note: Conditional visibility is optional and may not be suitable for all use cases.
Whether to use a reference or a component depends on your content model needs. References are best for linking distinct content entries, while components are suitable for reusable content structures within a single entry. For guidance, see this documentation. Note: The choice impacts how content is managed and queried.
Hygraph offers flexible reference configuration (one-to-one, one-to-many, many-to-many, many-to-one), conditional visibility, drag-and-drop sorting, and granular field visibility (read/write, read-only, hidden, API only). These features support complex content models and workflows. Note: Some advanced features may require careful planning to avoid schema limitations after creation.
Yes, Hygraph provides a GraphQL Content API and a Management API for programmatic access to content and schema, including references. The Asset Upload API and MCP Server API are also available for asset management and AI assistant integration. For details, see the API Reference documentation. Note: API-only fields are not visible in the UI and can only be managed via API.
Comprehensive technical documentation is available at hygraph.com/docs/developer-guides/schema/references. Additional guides cover schema components, conditional fields, duplicating content, and API usage. Note: Documentation for Hygraph Classic is available separately for legacy projects.
Support resources include extensive documentation, onboarding guides, community Slack, webinars, and live training. Starter projects and technical kickoffs are available for new users. For help, visit Hygraph Documentation or join the community at slack.hygraph.com. Note: Some advanced support may require a paid plan.
Common use cases include linking authors to blog posts, products to categories, products to order items, and products to reviews. References enable complex content relationships for scenarios such as eCommerce catalogs, editorial workflows, and multi-language content. Note: Overly complex reference structures may impact performance or manageability; plan your schema accordingly.
Hygraph's reference system allows you to model complex relationships (e.g., many-to-many between products and categories) and control visibility, sorting, and access. This supports advanced content architectures for global teams and multi-channel delivery. Note: Schema changes to references are restricted after creation, so plan carefully.
Before creating references, carefully plan your schema, as reference type, direction, and cardinality cannot be changed after creation. Test your setup to avoid issues, and consult documentation on duplicating content and conditional fields. Note: Poor planning may require schema redesign or data migration later.
Best practices include planning your content model in advance, using descriptive display names and API IDs, leveraging conditional visibility for dynamic forms, and testing reference behavior with sample data. Review documentation for edge cases such as duplicating content and managing reverse fields. Note: Overuse of references can complicate content management; use them judiciously.
This page wast last updated on 12/12/2025 .
Reference fields connect content entries across models. Choosing the wrong direction or cardinality requires deleting and rebuilding the field, so plan your schema before you start.
The sections below describe each tab and its options in detail.
The Define tab controls the structural decisions that cannot be changed after the field is saved.
Reference type, model to reference, reference direction, and relation cardinality are all locked after you click Add. For Union Type fields, you can edit which models are included in the relation after the initial save, but you cannot change the other settings. Delete and recreate the field to change any other locked setting.
Use the Reference type radio buttons to control how many models this field can point to.
Select the models this field will reference. The Relation cardinality controls appear below after you make a selection.
Post entry, but opening an Author entry shows no list of connected posts.Author entry as well. This also adds the Reverse field tab to the modal.Relation cardinality controls how many entries can be connected on each side of the relation. Use the dropdown in the center of the diagram to set this. The checkboxes below the diagram reflect your selection and update automatically.
One-way reference
| Option | Meaning | Example |
|---|---|---|
| One to one | One entry in this model links to exactly one entry in the referenced model | A country links to one capital city |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts |
Two-way reference
| Option | Meaning | Example |
|---|---|---|
| One to one | One entry on each side links to exactly one entry on the other side | Each country has one capital city and each capital city belongs to only one country |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts, and each post belongs to only one author |
| Many to one | Multiple entries in this model link to one entry in the referenced model | Multiple reviews link to one product, and each review belongs to only one product |
| Many to many | Multiple entries on both sides can be connected | A product belongs to many categories and a category contains many products |
The Configure tab sets the field's display name, API ID, and behavior options. These settings can be updated after the field is created.
Hygraph pre-populates Display name and API ID based on your Define tab selections. You can change them before saving.
Description is optional. The text you enter here displays as a hint for content editors and API users.
The validation option available depends on the cardinality you selected on the Define tab. These validations apply in the UI only and are intended to help editors remember to connect entries. Keep the following in mind:
Require a connected entry displays an editorial warning in the content form if no entry is linked. Unlike other required fields, the API does not enforce this requirement. You can optionally add a Custom error message to replace the default warning text.
Limit connected entry count specifies a minimum and/or maximum number of connected entries upon saving or publishing the entry. Use the dropdown to set the constraint type:
| Option | Inputs required |
|---|---|
| Between | Min and Max |
| At least | Min only |
| Not more than | Max only |
You can optionally add a Custom error message to replace the default validation text.
Enable variants lets this reference field hold different values for each Variant of a content entry. Editors can set a different connected entry per Variant without affecting the main entry or other Variants. This option is not available for unique fields. Disabling it after content has been created removes the field and its values from all Variants. Variants are an enterprise feature; see the Variants documentation for setup details.
Show based on condition lets you configure conditional visibility so the field only appears in the content form when a specified condition is met. Select an Enumeration or Boolean field from this model to establish the condition.
Field visibility controls how the field appears in the UI and API. Read / Write is selected by default.
| Option | Behavior |
|---|---|
| Read / Write | Field can be read and edited |
| Read only | Field is shown but cannot be edited in the UI; editable through the API only |
| Hidden | Field is not shown in the UI; other fields can still reference it |
| API only | Field is not shown in the UI; readable and editable through the API only |
If you selected a one-way reference, click Add to save the field. If you selected a two-way reference, continue to the Reverse field tab.
The Reverse field tab appears only for two-way references. It configures the field that Hygraph adds to the referenced model.
Hygraph pre-populates Display name and API ID from the referenced model name. You can change them before saving. Field visibility defaults to API only for the reverse field.
Click Add to add the field to the model.
To make further configuration changes to the reverse field after saving, navigate to the referenced model and edit the field. A banner displays which model the reverse field belongs to, for example, "Field in Article referencing Product". Click Visit model to open that model directly.
Reference fields connect content entries across models. Choosing the wrong direction or cardinality requires deleting and rebuilding the field, so plan your schema before you start.
The sections below describe each tab and its options in detail.
The Define tab controls the structural decisions that cannot be changed after the field is saved.
Reference type, model to reference, reference direction, and relation cardinality are all locked after you click Add. For Union Type fields, you can edit which models are included in the relation after the initial save, but you cannot change the other settings. Delete and recreate the field to change any other locked setting.
Use the Reference type radio buttons to control how many models this field can point to.
Select the models this field will reference. The Relation cardinality controls appear below after you make a selection.
Post entry, but opening an Author entry shows no list of connected posts.Author entry as well. This also adds the Reverse field tab to the modal.Relation cardinality controls how many entries can be connected on each side of the relation. Use the dropdown in the center of the diagram to set this. The checkboxes below the diagram reflect your selection and update automatically.
One-way reference
| Option | Meaning | Example |
|---|---|---|
| One to one | One entry in this model links to exactly one entry in the referenced model | A country links to one capital city |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts |
Two-way reference
| Option | Meaning | Example |
|---|---|---|
| One to one | One entry on each side links to exactly one entry on the other side | Each country has one capital city and each capital city belongs to only one country |
| One to many | One entry in this model links to multiple entries in the referenced model | An author links to multiple posts, and each post belongs to only one author |
| Many to one | Multiple entries in this model link to one entry in the referenced model | Multiple reviews link to one product, and each review belongs to only one product |
| Many to many | Multiple entries on both sides can be connected | A product belongs to many categories and a category contains many products |
The Configure tab sets the field's display name, API ID, and behavior options. These settings can be updated after the field is created.
Hygraph pre-populates Display name and API ID based on your Define tab selections. You can change them before saving.
Description is optional. The text you enter here displays as a hint for content editors and API users.
The validation option available depends on the cardinality you selected on the Define tab. These validations apply in the UI only and are intended to help editors remember to connect entries. Keep the following in mind:
Require a connected entry displays an editorial warning in the content form if no entry is linked. Unlike other required fields, the API does not enforce this requirement. You can optionally add a Custom error message to replace the default warning text.
Limit connected entry count specifies a minimum and/or maximum number of connected entries upon saving or publishing the entry. Use the dropdown to set the constraint type:
| Option | Inputs required |
|---|---|
| Between | Min and Max |
| At least | Min only |
| Not more than | Max only |
You can optionally add a Custom error message to replace the default validation text.
Enable variants lets this reference field hold different values for each Variant of a content entry. Editors can set a different connected entry per Variant without affecting the main entry or other Variants. This option is not available for unique fields. Disabling it after content has been created removes the field and its values from all Variants. Variants are an enterprise feature; see the Variants documentation for setup details.
Show based on condition lets you configure conditional visibility so the field only appears in the content form when a specified condition is met. Select an Enumeration or Boolean field from this model to establish the condition.
Field visibility controls how the field appears in the UI and API. Read / Write is selected by default.
| Option | Behavior |
|---|---|
| Read / Write | Field can be read and edited |
| Read only | Field is shown but cannot be edited in the UI; editable through the API only |
| Hidden | Field is not shown in the UI; other fields can still reference it |
| API only | Field is not shown in the UI; readable and editable through the API only |
If you selected a one-way reference, click Add to save the field. If you selected a two-way reference, continue to the Reverse field tab.
The Reverse field tab appears only for two-way references. It configures the field that Hygraph adds to the referenced model.
Hygraph pre-populates Display name and API ID from the referenced model name. You can change them before saving. Field visibility defaults to API only for the reverse field.
Click Add to add the field to the model.
To make further configuration changes to the reverse field after saving, navigate to the referenced model and edit the field. A banner displays which model the reverse field belongs to, for example, "Field in Article referencing Product". Click Visit model to open that model directly.