# Reference

Imagine you run an online clothing store. For each product, you want to note which brand it belongs to. If the brand "DailyWear" has dozens of products, you end up typing the same brand name, logo, and description into every single product. And when the brand description changes, you have to fix every one of those dozens by hand.

A reference removes this repetition. You create the brand information once, on its own, and each product simply links to that brand. Instead of re-entering the same information every time, you link to information that lives in one place. That is what a reference is. Edit the brand description once, and the change applies all at once to every product linked to that brand.

This page covers what a reference is, the kind of link that connects one *Content* to another *Content*, what happens when you link them, and how *Content* connect to one another.

## Why you link instead of copying {#pointing-versus-copying}

There are two ways to think about recording brand information on each product.

One is **copying**. Every time you create a product, you type the brand name "DailyWear" and the brand description directly into that product. A hundred products hold a hundred copies of the same text. When the brand description changes, you have to find and fix all hundred copies, and if you miss even one, that product shows a different description.

The other is **linking**. You create the brand "DailyWear" as a single *Content* on its own, and each product just links to that brand *Content*. The information lives in only one place: the brand. Edit the description in that one place, and every product linked to the brand follows the same new description.

A reference is this "linking." The *Field* that holds the link is called **Content Reference** in the content studio. Add one **Content Reference** *Field* to the product *Content Type*, and in that box you choose a brand *Content* to link. To put it another way: instead of copying the brand information into each product by hand, you draw a single arrow that says "this product's brand is that DailyWear over there."

## What a link looks like {#what-a-link-looks-like}

When you link a product to a brand, it takes the following shape. Several products link to the same single brand.

```
Product "Stainless Tumbler 500ml" ──link──▶
Product "Insulated Mini Tumbler 350ml" ──link──▶   Brand "DailyWear"
Product "Foldable Travel Bottle 600ml" ──link──▶
```

You create the brand "DailyWear" just once, and both the tumblers and the bottle all link to this one place. Edit the brand description once in the DailyWear *Content*, and all three products above follow the new description.

Links can be made not only between *Content*, but also from *Content* to *Media* (an uploaded file such as an image or video). Attaching a main photo to a product is an example. This page covers connecting *Content* to one another. How to attach *Media* is covered in [Media](/getting-started/core-concepts/content/media.md).

## What comes along with a link {#what-comes-along-with-a-link}

Once a product has a brand linked to it, you can pull in the linked brand information together with the product information. When you show the tumbler product on screen, the name and description of the brand "DailyWear" linked to it come along in one go. Even though you never copied the brand information into the product, it follows the link and reads the values from the one place where the brand lives.

So you only ever keep the brand information in one place: the brand *Content*. Each time you read the product, the brand information as it stands at that moment comes along through the link. Edit the brand, and the next time you read the product, the edited content follows.

> The exact format of how far the linked *Content* is pulled in together, and which request retrieves it, is covered in the [API reference](/api/reference/cma.md). In the content studio, you only need to set up the link.

## Deciding which kinds can be linked {#deciding-which-kinds-can-be-linked}

A **Content Reference** *Field* lets you set a restriction: "only certain *Content* may be linked in this box." For a product's brand box, you do not want just any *Content* coming in, because a review or a notice should not be linked into the brand slot by mistake.

So you can decide that only *Content* created from the "Brand" *Content Type* may be linked in this box. With that in place, the choices in the brand box are limited to brands, and other kinds of *Content* will not link. You can also allow several *Content Type* to be linked together. For example, a single box can allow both "Brand" and "Partner," so that either one can be linked.

You set this restriction in the detailed settings of the **Content Reference** *Field*. Turn on **Accept only specified Content Type** under **Validations**, then choose "Brand" as the allowed *Content Type*.

![Detailed settings screen for a product's brand box (Content Reference Field). Under validation, the reference Content Type option is turned on and "Brand" is selected](/_img/en-US/getting-started/core-concepts/common/images/reference-01-refer-content-type.webp)

This restriction is checked when you save or publish. If you link a *Content* that is not one of the allowed *Content Type*, saving is blocked, and if a linked *Content* is deleted in the meantime and can no longer be found, that is caught by the check as well. It is a safeguard that keeps wrongly made links from piling up.

## Linking several items in one box {#linking-several-items-in-one-box}

Linking a single brand to a product is often enough. But sometimes you want to link several items in one box. For example, in a "Products that go well with this one" box, you want to connect several related products together.

For this, set the **Content Reference** *Field* to **Use as list type**. Then you can link several *Content* in one box, such as linking a tumbler, a bottle, and a vacuum flask all into the "Products that go well together" box. When using the list type, you can apply the same restriction on which kinds can be linked.

## Adding a brand-link box to "Product" {#adding-a-brand-link-box-to-product}

To let a product link to a brand, add a **Content Reference** kind of *Field* to the "Product" *Content Type*. How to add a *Field* is covered in [Content modeling](/getting-started/core-concepts/content/content-modeling.md). On the screen where you choose the *Field* kind, pick **Content Reference**, then set the "kinds that can be linked" described above to "Brand."

You need something to link to before you can make the connection, so prepare the brand side first.

1. Create the "Brand" *Content Type*. Add *Field* such as the brand name and the description.
2. Create one brand *Content*, "DailyWear," from the "Brand" *Content Type*.
3. Add a **Content Reference** *Field* to the "Product" *Content Type* and set the kinds that can be linked to "Brand."
4. Open the product "Stainless Tumbler 500ml" and click **Edit**.
5. Click **Add Existing Content** in the brand box. The **Select Content** window opens.
6. Choose "DailyWear" from the list and link it.

The **Select Content** window shows only the "Brand" you set as the kind that can be linked. The restriction you set earlier applies here directly.

![The Content picker window opened by clicking Add existing Content in the brand box on the product edit screen. The list filtered to "Brand" shows "DailyWear"](/_img/en-US/getting-started/core-concepts/common/images/reference-02-content-picker.webp)

Now the tumbler product is linked to the brand "DailyWear." When you choose "DailyWear" in the same box from other products too, several products end up linked together to one brand.

## Things to know when working with links {#things-to-know-when-working-with-links}

**If a linked *Content* disappears, it is caught by the check.** If you delete a brand *Content* that a product has linked, the product's brand box ends up linking a *Content* that can no longer be found. In that state, saving or publishing the product is blocked by the check. Link a different brand again, or, if that box is not required, clear it and then try again.

**Linking does not merge the two *Content* into one.** The product and the brand remain as separate *Content*. Delete the product and the brand *Content* stays as it is; edit the brand and the product *Content* itself stays unchanged. The only thing that changes is the value read along through the link.

## What to do next {#what-to-do-next}

- [Content modeling](/getting-started/core-concepts/content/content-modeling.md): covers how to add a **Content Reference** *Field* to the "Product" *Content Type*.
- [Media](/getting-started/core-concepts/content/media.md): covers how to attach *Media*, such as a main photo, to a product.
- [Status and publishing](/getting-started/core-concepts/common/states-and-versions.md): covers the step of publishing a linked *Content* to make it visible externally.
- [API reference](/api/reference/cma.md): reference this when you work directly in a program with the request format for retrieving linked *Content* together and the structure of the `Refer` element that holds the link.