Cross-space references

Cross-space references (formerly known as References across spaces) allow you to link content across multiple spaces. Using cross-space references, you can create reusable content and update multiple spaces with the same piece of content. To accommodate referencing across multiple spaces, the ResourceLink field type has been added. The ResourceLink field carries references to entities in separate spaces. All ResourceLink fields are configured in the ContentType definitions as usual fields and accept the allowedResources validation rule. This validation restricts the entities that can be linked by the field.

Supported field properties: localized, required, omitted and disabled.

Contentful Resource Names

With cross-space references, the Contentful Resource Name (crn) API identifier is used.

A crn is a formatted string used to describe an object in the API domain. It uses a shared syntax that can be resolved across Contentful services. Currently, crn is only used in the context of cross-space references to recognize a Contentful space, environment, or entry.

The respective syntax templates are:

crn:contentful:::content:spaces/<:spaceId> crn:contentful:::content:spaces/<:spaceId>/environments/<:environmentId> crn:contentful:::content:spaces/<:spaceId>/entries/<:entryId> crn:contentful:::content:spaces/<:spaceId>/environments/<:environmentId>/entries/<:entryId>

The <:spaceId>, <:environmentId>, and <:entryId> portions must contain standard resource IDs. In the following snippets, the “{crn}” placeholder will be used where one of these is needed.

Omitting the environment in a crn is equivalent to referencing the master environment.

Create a content type with a ResourceLink field

To create a content type with a ResourceLink field, use the Create a content type with POST endpoint. The ResourceLink field is set in the request body, see example:

{
  "sys": {
    "type": "ContentType",
    "...": ""
  },
  "fields": [
    {
      "id": "myResourceLink",
      "type": "ResourceLink",
      "localized": true,
      "disabled": false,
      "omitted": false,
      "allowedResources": [
        {
          "type": "Contentful:Entry",
          "source": "{crn}",
          "contentTypes": [
            "foo",
            "bar"
          ]
        }
      ],
      "...": ""
    }
  ]
}

Update a content type with a ResourceLink field

To update a content type with a ResourceLink field, use the Create a content type with PUT endpoint. The ResourceLink field is set in the request body, see example: Use this endpoint to add a ResourceLink field to a content type or update an existing ResourceLink field.

{
  "sys": {
    "type": "ContentType",
    "...": ""
  },
  "fields": [
    {
      "id": "myResourceLinks",
      "type": "Array",
      "localized": true,
      "disabled": false,
      "omitted": false,
      "validations": [
        {
          "size": {
            "min": "1",
            "max": "3"
          }
        }
      ],
      "allowedResources": [
        {
          "type": "Contentful:Entry",
          "source": "{crn}",
          "contentTypes": [
            "foo",
            "bar"
          ]
        }
      ],
      "...": ""
    }
  ]
}

Allowed resources

The ResourceLink field definition expects an allowedResources array as additional property, restricting which resources can be linked through the field.

Only resources belonging to spaces within the same organization are accepted.

Property	Description	Validation rule
`allowedResources`	Array containing one item per distinct source.	Must contain at least one item.
`allowedResources[].type`	The type of resource that the rule contains.	Must be `Contentful:Entry`.
`allowedResources[].source`	The location of the allowed resources. A `crn` to a contentful environment for type `Contentful:Entry`.	Must be unique across `allowedResources` and does not refer to the same space owning the content type.
`allowedResources[].contentTypes`	The only entry types supported by Contentful.	Must be an array of strings.

Validations

For each field definition property, you can add or remove validations to the fields in the content type schema by specifying the validations property of a field.

Property	Description	Validation rule
`sys.crn`	The identifier of the resource.	Must correspond to a resource of type `sys.type` in the entry organization.
`sys.type`	The type of resource in the link.	Must be `Contentful:Entry`.

Create an entry with a ResourceLink field

To create an entry with a ResourceLink field, use the Create an entry endpoint. The ResourceLink field is set in the request body, see example:

{
  "sys": {
    "type": "Entry"
  },
  "fields": {
    "myResourceLink": {
      "en-US": {
        "sys": {
          "type": "ResourceLink",
          "linkType": "Contentful:Entry",
          "urn": "{crn}"
        }
      }
    }
  }
}

Update an entry with a ResourceLink field

To update an entry with a ResourceLink field, use the Create an entry with ID endpoint. The ResourceLink field is set in the request body, see example:

{
  "sys": {
    "type": "Entry"
  },
  "fields": {
    "myResourceLinks": {
      "en-US": [
        {
          "sys": {
            "type": "ResourceLink",
            "linkType": "Contentful:Entry",
            "urn": "{crn}"
          }
        }
      ]
    }
  }
}