Develop content

9 min

The content resource is the primary resource type of Optimizely Content Management System (CMS) (SaaS). Content can represent webpages, components, media, and almost any other type. A content item holds data in a structured way described by a schema defined by a content type. Every content item is an instance of a content type. Content instances are indexed as queryable items in Optimizely Graph.

Each content item can have multiple versions. Versions can be in different draft states, but you can have only one published version for each locale.

Content organization

CMS (SaaS) organizes content in a hierarchical structure. The content's container field defines where to locate a content item. You should set this value to the parent container's key when creating the content item. The content type may restrict what type of content you can create under another content item of a certain type.

Assets

A content item can also own another content item. Content owned by another content item is an asset, and a media or component content type. A content asset has the owner field assigned. See Assets.

Content resource

The content resource represents shared information across the content item. This information is not versioned, and changes affect all versions of the content.

The content resource contains the following fields:

key – The 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.

contentType – The content type that describes the schema of the content item.

container – The key of the content item that contains this content item.

owner – The key of the content item that owns this content item. Used for assets of another content item.

created – A timestamp indicating when someone created the content item.

createdBy – A string indicating the username of the person who created the content item.

deleted – A timestamp that, if present, indicates when someone deleted the content item.

Content version resource fields

The content version resource represents information specific to one version of a content item and contains the following fields:

key – The unique identifier of the content is the same for different versions of the same content item.

locale – Specifies the locale of this version. You cannot change the locale for an existing version.

version – A unique identifier for the version generated by the service. The version is guaranteed to be unique across versions for the same content key. You cannot assign this value.

contentType – The content type of the content item. This value matches the content type of the content item, and you cannot change it.

displayName – The display name of the content.

status – The status of the version.

published – A timestamp indicates when a content item should be public. If not assigned, this gets assigned when the first version is published.

expired – A timestamp indicated when a content item should no longer be public.

delayPublishUntil – A timestamp used when scheduling a version to be published to indicate when to publish the version. It is required when you set the status scheduled.

routeSegment – A route segment associated with the current content generates a route to the content item.

simpleRoute – A simple route (shortcut URL) for pages and experiences.

binding – Binding information for content connected to an external source. See Connect content sources.

lastModified – A timestamp indicating when this version was last modified.

lastModifiedBy – A string indicating the user's username that last modified this version.

properties – A set of values that describes the content data. The content type schema defines the names and types.

Content version status values

A content version can have the following status values.

draft – Default. Indicates that the version is a work in progress.

ready – Indicates that editing of the version is complete and ready to be reviewed.

inReview – Indicates that the approval process has started.

rejected – Indicates that the version was reviewed but rejected.

scheduled – Indicates that the version is scheduled for publishing.

published – Indicates that the version is the published version. You can publish only one version for each locale.

previouslyPublished – Assigned by the system when another version is published. You cannot assign it through the API. You cannot modify versions with this status.

Properties

The properties field contains values for any property defined by the content type schema. The values of each property must match the data type specified by the content type definition.

The following example shows a version with some basic data types.

{
  "key": "98eb33cfa7df48d1b987442c522984c8",
  "locale": "en",
  "contentType": "basic",
  "displayName": "Content with basic properties",
  "properties": {
    "someString": {
      "value": "some string content"
    },
    "someBoolean": {
      "value": true
    },
    "someInteger": {
      "value": 12
    },
    "someFloat": {
      "value": 3.14
    },
    "someDateTime": {
      "value": "2023-01-01T10:46:08.293+00:00"
    },
    "someContentReference": {
      "value": "cms://content/e56f85d0e8334e02976a2d11fe4d598c"
    },
    "someStringArray": {
      "value": [
        "first",
        "second"
      ]
    }
  }
}

Media in rich text properties

A rich text property value contains HTML in its html field. To add an image or a video, put a cms://content reference to the media item in a src attribute. Use an img element for an image, or a source element inside a video element for a video. Write the GUID as 32 hexadecimal characters without hyphens, as for content reference properties. The API stores a hyphenated GUID as a plain URL. The API returns a CMS reference without its ?ver= value, and returns a DAM asset as cms://content/SOURCE/KEY.

{
  "properties": {
    "body": {
      "value": {
        "html": "<p>Visit our office.</p><img src=\"cms://content/e56f85d0e8334e02976a2d11fe4d598c\" alt=\"Office entrance\" />"
      }
    }
  }
}

Component properties

The content type defines a complex property as a component property of a certain component content type.

So, if there is a component defined as:

{
  "key": "teaser",
  "baseType": "_component",
  "properties": {
    "heading": {
      "type": "string"
    },
    "body": {
      "type": "richText"
    }
  }
}

Then you can use that teaser component as property on another content type:

{
  "key": "pageWithComponents",
  "baseType": "_page",
  "properties": {
    "mainTeaser": {
      "type": "component",
      "format": "teaser"
    },
    "teaserList": {
      "type": "array",
      "items": {
        "type": "_component",
        "format": "teaser"
      }
    }
  }
}

You could define a content version of the page with components as:

{
  "key": "98EB33CAA7DE48D1B487442C522984C8",
  "contentType": "pageWithComponents",
  "displayName": "A page with components",
  "locale": "en",
  "container": "5B51C2BAB5804DBE96CC5EAA2478830D",
  "properties": {
    "mainTeaser": {
      "value": {
        "displayName": "Main teaser",
        "contentType": "teaser",
        "properties": {
          "heading": {
            "value": "Single component"
          },
          "body": {
            "value": {
              "html": "<p>Some text for a single component</p>"
            }
          }
        }
      }
    },
    "teaserList": {
      "value": [
        {
          "displayName": "First teaser",
          "contentType": "teaser",
          "properties": {
            "heading": {
              "value": "first"
            },
            "body": {
              "value": {
                "html": "<p>Some text for the first list component</p>"
              }
            }
          }
        },
        {
          "displayName": "Second teaser",
          "contentType": "teaser",
          "properties": {
            "heading": {
              "value": "second"
            },
            "body": {
              "value": {
                "html": "<p>Some text for the second list component</p>"
              }
            }
          }
        }
      ]
    }
  }
}

Content properties

A content property is a complex property where the component content type is defined in the content data rather than by the content type. However, the definition of a content type may restrict the content property to only certain types.

A content property can also reference an existing content item using its unique content item key.

So, suppose you define a page with a property as a list of content components as follows:

{
  "key": "pageWithContentList",
  "baseType": "_page",
  "properties": {
    "someItems": {
      "type": "array",
      "items": {
        "type": "content"
      }
    }
  }
}

If there exists a content item with a specified key and a component type teaser, then a content version with a content property could be defined as follows:

{
  "key": "38EB33CAB7DE48D1B456442C522984C8",
  "contentType": "pageWithContentList",
  "displayName": "Example",
  "locale": "en",
  "container": "5B51C2BAB5804DBE96CC5EAA2478830D",
  "properties": {
    "someItems": {
      "value": [
        {
          "reference": "cms://content/38eb33cab7de48d1b487442c522984c8"
        },
        {
          "displayName": "Inline teaser",
          "contentType": "teaser",
          "properties": {
            "heading": {
              "value": "Heading for teaser component"
            },
            "body": {
              "value": {
                "html": "Some text"
              }
            }
          }
        }
      ]
    }
  }
}