Referenced Content

Referenced content allows content items to be stored independently and linked together using references.

In many cases, your content will reference other content.

For example, consider a blog site. It may have many articles, each of which refers to the author who wrote them.

In one part of your application, such as on an individual article page, an author is queried in the context of an article. However your application may also list all the articles by a single author. Since both articles and authors can be the main "subject" in different contexts, it doesn't make sense to store either as a nested property of the other.

Instead, both items should be stored independently in Compose and configured to reference one another.

Defining Content References

You can configure a property in a type schema to reference other content, either a single item or multiple items.

Single item references are established by including a $ref field directly on a property configuration object. The value of the $ref field should be the type schema alias of the target content.

Multiple item references are similar, except the $ref field should be configured beneath the items property of the array.

The following example shows both:

• An article type schema that contains a singular reference to an author

• An author type schema that contains an array reference to many articles

article

{
    "$schema": "https://umbracocompose.com/v1/schema",
    "allOf": [
        { "$ref": "https://umbracocompose.com/v1/node" }
    ],
    "properties": {
        "title": {
            "type": "string"
        },
        "author": {
            "type": "object",
            "$ref": "author"
        }
    }
}

author

Ingestion

Ingesting a reference to a content item is done in much the same way as ingesting any other property. The value of the reference property should simply be the id of the content item which is being referred to. In the case of array references, it should instead be an array of all such ids.

For example, to store two articles and their author according to the type schemas defined above, send the following to the Ingestion API:

[
    {
        "id": "1",
        "type": "article",
        "data": {
            "title": "Top 5 Tips & Tricks for Umbraco Compose",
            "author": "3"
        }
    },
    {
        "id": "2",
        "type": "article",
        "data": {
            "title": "Why You'll Never Use Anything Else After Compose!",
            "author": "3"
        }
    },
    {
        "id": "3",
        "type": "author",
        "data": {
            "name": "John C. Ompose",
            "articles": ["1", "2"]
        }
    }
]

References don't need to go both directions. If you only wish to use the relationship in one direction, then you may wish to save some overhead by only configuring the reference in that direction.

For example, if your application never needs to show a list of all articles by an author, then you might choose to omit the articles property (and therefore reference) from an author.

Retrieval

Retrieving referenced content instances via GraphQL can be done with a fragment. It is up to your query to handle any possible referenced types.

For the article/author scenario, a sample GraphQL query might look like the following.

query {
  content {
    items {
      ... on Article {
        title
        author {
          items {
            ... on Author {
              name
            }
          }
        }
      }
    }
  }
}