#References

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.

#Add a reference field

Go to Schema and select the model you want to update.
From the Field types sidebar, select Reference.
On the Define tab, set the reference type, model to reference, reference direction, and relation cardinality. These settings cannot be changed after saving.
On the Configure tab, set the display name, API ID, and any behavior options.
If you selected a two-way reference, configure the reverse field on the Reverse field tab.
Click Add.

The sections below describe each tab and its options in detail.

#Define tab

The Define tab controls the structural decisions that cannot be changed after the field is saved.

Define tab settings cannot be changed after saving

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.

#Reference type

Use the Reference type radio buttons to control how many models this field can point to.

Allow only one model to be referenced: The field returns content from one model. One-way or two-way reference direction is available.
Allow multiple models to be referenced (Union Type): The field returns content from multiple models. Only two-way reference direction is available; one-way is disabled.

#Model to reference

Select the models this field will reference. The Relation cardinality controls appear below after you make a selection.

#Reference direction

One-way reference: The field is queryable only from the model where you add it. The referenced model has no reverse field.
- For example, a Post referencing an Author one-way means editors can select an author from the Post entry, but opening an Author entry shows no list of connected posts.
Two-way reference: Hygraph adds a reverse field to the referenced model, making the relation queryable from both sides.
- For example, a Post referencing an Author two-way means editors can see connected posts from the Author entry as well. This also adds the Reverse field tab to the modal.

#Relation cardinality

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

#Configure tab

The Configure tab sets the field's display name, API ID, and behavior options. These settings can be updated after the field is created.

#Display name and API ID

Hygraph pre-populates Display name and API ID based on your Define tab selections. You can change them before saving.

#Description

Description is optional. The text you enter here displays as a hint for content editors and API users.

#Validation

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:

Unlike other required fields, the API does not enforce these validations. Content can be saved or published via the API regardless of validation state.
If a referenced entry is deleted, or disconnected from the other side of a two-way reference, Hygraph removes the link automatically but does not display an error. For example, if an Article requires a linked Product and someone deletes that Product, the Article loses the connection silently with no error shown.
If an editor removes a connected entry from the content form, the warning appears and blocks publishing until the requirement is met.
An entry that exists as a draft but has not been published still counts as connected.

One to one and Many to one

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.

One to many and Many to many

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

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

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

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.

#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.

#What's next

Fetch relations: Learn how to query connected entries via the Content API.
Create references: Learn how to connect entries to one another directly from the content editor.
Duplicate content: See how relational field types behave when content entries are duplicated.
Components or references: Understand when to use a component versus a reference for related content.