AI Lab

References

Every Document Object includes a references array. Livingdocs automatically extracts these references from the document's metadata and content. They describe which resources (other documents, images, videos, files, lists, language groups) a document depends on.

References power the Incoming Publication References and Incoming Media References endpoints, which answer the question: "What links to this resource?" This is essential for cache invalidation and checking whether a resource is still in use.

Base Fields

All references share these fields:

PropertyTypeDescription
id*
string

Identifier of the referenced resource (e.g. a document id or media library entry id).

type*
string

One of document, image, video, file, list, or language-group.

location*
string

Where the reference was extracted from. See Locations.

Locations

The location field indicates where in the document the reference originates. Each location adds additional context fields.

metadata

A reference extracted from a metadata property (e.g. li-document-reference, li-tree, li-issue-management).

PropertyTypeDescription
propertyName*
string

The metadata property handle that holds the reference.

{
  "id": "lk3j4h5g",
  "type": "image",
  "location": "metadata",
  "propertyName": "teaserImage"
}

editable-directive

A reference extracted from an inline link or file reference within an editable text directive (e.g. <a data-li-document-ref="123"> in an HTML string).

PropertyTypeDescription
componentId*
string

The component instance id containing the directive.

componentName*
string

The component name.

directiveName*
string

The directive name within the component.

{
  "id": "123",
  "type": "document",
  "location": "editable-directive",
  "componentId": "doc-abc123",
  "componentName": "paragraph",
  "directiveName": "text"
}

A reference extracted from a link directive that points to a document.

PropertyTypeDescription
componentId*
string

The component instance id containing the directive.

componentName*
string

The component name.

directiveName*
string

The directive name within the component.

{
  "id": "456",
  "type": "document",
  "location": "link-directive",
  "componentId": "doc-def456",
  "componentName": "teaser",
  "directiveName": "link"
}

image-directive

A reference extracted from an image directive that points to a media library entry.

PropertyTypeDescription
componentId*
string

The component instance id containing the directive.

componentName*
string

The component name.

directiveName*
string

The directive name within the component.

{
  "id": "img-abc123",
  "type": "image",
  "location": "image-directive",
  "componentId": "doc-ghi789",
  "componentName": "image",
  "directiveName": "image"
}

include-directive

A reference extracted from an include directive's params. Includes are server-side render functions that can return html or a component.

PropertyTypeDescription
componentId*
string

The component instance id containing the include.

componentName*
string

The component name.

directiveName*
string

The directive name within the component.

serviceName*
string

The include service name.

propertyName*
string

The param property that holds the reference.

{
  "id": "7",
  "type": "document",
  "location": "include-directive",
  "componentId": "doc-2c95a77x14",
  "componentName": "teaser",
  "directiveName": "embed-teaser",
  "serviceName": "embed-teaser",
  "propertyName": "document"
}

include-directive-override

A reference extracted from an include directive's content overrides. Overrides allow editors to customize parts of an include's rendered output.

PropertyTypeDescription
componentId*
string

The component instance id containing the include.

componentName*
string

The component name.

directiveName*
string

The directive name within the component.

serviceName*
string

The include service name.

overrideId*
string

The component id within the override.

overrideDirectiveName*
string

The directive name within the override component.

{
  "id": "img-override1",
  "type": "image",
  "location": "include-directive-override",
  "componentId": "doc-2c95a77x14",
  "componentName": "teaser",
  "directiveName": "embed-teaser",
  "serviceName": "embed-teaser",
  "overrideId": "ref-override1",
  "overrideDirectiveName": "image"
}

Reference Types

TypeDescriptionPossible Locations
documentA reference to another Livingdocs documentmetadata, editable-directive, link-directive, include-directive, include-directive-override
imageA reference to a media library imagemetadata, image-directive, include-directive, include-directive-override
videoA reference to a media library videometadata, include-directive
fileA reference to a file within an editable directiveeditable-directive
listA reference to a document listmetadata, include-directive
language-groupA reference to a language groupmetadata

Type-specific Fields

Some reference types carry additional fields:

PropertyTypeDescription
posterImageId
string

Present on video references. The media library id of the poster image associated with the video.

externalSystem
string

Present on document references when the link points to a document managed by an external system.

⌘ K to search