Metadata

10 min

When you query CMS (SaaS) content through Optimizely Graph, each content item exposes a _metadata field that you can cast to specialized types depending on the context: global contracts, base types, instance metadata for stand-alone items, item metadata for items embedded in content areas, or media metadata for assets. The following sections describe the fields available on each type.

Global contract types

A contract is an abstract type that other types can be composed of. Contracts can be user-defined, but Optimizely Graph also comes with a set of predefined contracts referred to as global contracts. Global contracts define common fields across multiple products and systems, which means there might be overlap of some of the fields between contracts and base types.

_Item

All types implement this contract. This contract defines the field _itemMetadata of type _Metadata.

The type _Metadata defines the following fields:

Field	Type	Description
key	String	Unique identifier of document.
displayName	String	The name of the document.
lastModified	DateTime	When the document was last modified.
type	String	The type of the document.

_AssetItem

All asset types, for example _Media, _Image, and _Video, implement this contract. This contract defines the field _assetMetadata of type _AssetMetadata.

The type _AssetMetadata defines the following fields:

Field	Type	Description
fileSize	Float	The size of the document's binary (see url field) in bytes.
mimeType	String	The MIME type of the document's binary (see url field).
url	String	The URL to the document's binary.

_ImageItem

All image types, for example _Image, implement this contract. This contract defines the field _imageMetadata of type _ImageMetadata.

The type _ImageMetadata defines the following fields:

Field	Type	Description
width	Int	The width of document's image (see url field in _AssetMetadata).
height	Int	The height of document's image (see url field in _AssetMetadata).

Base types

IContentMetadata

The common base type _Content, that all content types inherit, has the property _metadata of type IContentMetadata.

🚧 Important Content can be displayed as stand-alone instances and as part of other content, for example inside content areas. Therefore _Content._metadata is of type IContentMetadata rather than ContentMetadata.

IContentMetadata can be cast (with fragments) to InstanceMetadata, ItemMetadata, and MediaMetadata, see below.

The type IContentMetadata defines the following fields:

Field	Type	Description
key	String	Unique identifier of a content item. The key currently uses a UUID-based format, but this may change, and you should treat the key as an opaque string.
locale	String	The locale is in the format 'language code-country', like 'en-US'. For invariant cultures, the country is omitted, like 'en'. Content that is not localizable has an empty string value.
fallbackForLocale	String	The locale this instance is available in but hasn't been translated to yet.
version	String	The version uses an integer-based format, but this may change, and you should treat the version as an opaque string. The version identifier is guaranteed to be unique across versions with the same key.
displayName	String	The name of the content item.
url	ContentUrl	The URL for the content item. The URL consists of several parts depending on the type of content and the application definitions. See ContentUrl.
types	[String]	A list of types, where the first item is the content type, then base types, and finally all contracts. Example: ["StandardPage", "_Page", "_Content", "_Item"]. Note that this list changes when you define new contracts.
published	DateTime	A datetime specified when the content item was published. For drafts, published is null. Content with a future published date is excluded from public queries until that date is reached.
status	String	The status of the content version. See content version status values.
changeset	String	Specifies whether this instance is part of a changeset. The value is default when this instance is the common draft.
created	DateTime	When the first content version in the current locale was created.
lastModified	DateTime	When the content version was last modified.
sortOrder	Int	The sort order within the same container. See container in InstanceMetadata.
variation	String	The name of the content version if it's created as a variation. See create content variations.

InstanceMetadata

For stand-alone instances, _metadata can be cast to InstanceMetadata, which implements IContentMetadata but adds more fields. The following is an example of a query that casts to InstanceMetadata:

query RouteSegmentQuery {
  _Page {
    items {
      _metadata {
        displayName
        ... on InstanceMetadata {
          routeSegment
        }
      }
    }
  }
}

The type InstanceMetadata defines the following fields:

Field	Type	Description
locales	[String]	The locales in which the content exists.
expired	DateTime	When the content item expires. If the date is a time that has passed, the content will be filtered from public queries.
container	String	The key of the content item that contains this instance.
path	[String]	The hierarchy of containers.
owner	String	The key of the content item owning this instance if it's a content asset.
routeSegment	String	The route segment for this content item. This field is empty for components or blocks that are not routable.
lastModifiedBy	String	Who last updated the content version.
createdBy	String	Who created the first version in the current locale.

ItemMetadata

For instances embedded in content areas, _metadata can be cast to ItemMetadata, which implements IContentMetadata but adds more fields. The following is an example of a query that casts to ItemMetadata:

query ContentAreaQuery {
  _StandardPage {
    items {
      ContentAreaProperty {
        ... on TeaserBlock {
          _metadata {
            ... on ItemMetadata {
              displayOption
            }
          }
        }
      }
    }
  }
}

The type ItemMetadata defines the following fields:

Field	Type	Description
displayOption	String	A string identifier representing the display option selected for this item in the content area (e.g., full, half, narrow).

MediaMetadata

For media content items, _metadata can be cast to MediaMetadata, like the following:

query MimeTypeQuery {
  _Media {
    items {
      _metadata {
        displayName
        ... on MediaMetadata {
          mimeType
        }
      }
    }
  }
}

The type MediaMetadata defines the following fields:

Field	Type	Description
thumbnail	String	The URL for a thumbnail of the media content item.
mimeType	String	The mime type for the media content item.
content	String	Contains extracted content from the media item. See Text extraction fieldText extraction field.