Content types

👍

Beta

Optimizely CMS (SaaS) is in beta. Apply on Join the waitlist for CMS (SaaS) or contact your Customer Success Manager.

A content type describes a content item's characteristics and data model schema in Optimizely Content Management System (CMS).

Base type

The content type also has a specific type, known as the base type. Each base type comes with characteristics such as how an editor manages an instance of the content type.

📘

Note

You cannot change the base type after you create the content type.

Base types in CMS are as follows:

• component – A generic content type used as a field on other content instances or as a standalone instance. It supports multiple locale branches.
• page – Represents a web page. Each content instance is unique. It supports multiple locale branches. You cannot model this field type as fields on other content types.
• media – Represents content with associated binary data, a generic content type for binary data. Content instances based on media do not support multiple locale branches.
• image – Used to store image binary data. It does not support multiple locale branches.
• video – Used to store video binary data. It does not support multiple locale branches.
• folder – Used to organize other content. It does not support multiple versions or multiple locale branches.

Standard fields

Every content type comes with many built-in, standard fields that describe the behavior of content instances of that content type.

• key – The unique identifier of a content type used in the API.
• displayName – A user-friendly name for the content type used, such as in the UI for editors.
• description – A description of the content type used, such as in the UI for editors.
• baseType – The base type of the content type.
• sortOrder – A relative index used in some listings to define the order of content types.
• mayContainTypes – A list of content types that you can create under content instances of the content type. It can be a content type key or the name of a base type.
• features – A list of features that these content types have. The value of this field is derived from the base type and cannot be changed.
• usage – Defines where you can use this content type. The base type derives the value of this field, and you cannot change it. Possible values are:
  • property – Indicates that you can use the content type as a component property.
  • instance – Indicates that you can create the content type as a standalone instance.
• source – A string indicating the source of this content type. It is empty for content types added through the UI and set to system for built-in content types.
• created – A timestamp indicating when someone created the content type.
• lastModified – A timestamp indicating when someone last modified the content type.
• lastModifiedBy – A string indicating the username of the person that last modified this content type.

Properties

Each content type can have properties that specify that content model. Depending on the property type, you can define different validations and editor settings for the property. Each property should have a unique string-based key within the content type. You can define properties for a content type in a Properties dictionary with the key and the property.

• type – The property's data type (one of the following).
• format – A reference to a predefined data format, including validation rules, an editor, and editor settings.
• displayName – A user-friendly name for the content type used, such as in the UI for editors.
• description – A description of the content type used, such as in the UI for editors.
• localized – Indicates if the property has a different value for each locale or if the same value should apply to all locales.
• required – Indicates if someone must give a value to the property.
• group – A reference to the group under which this property is organized.
• sortOrder – A relative index used in some listings to define the order of content types.
• editor – A reference to an editor specification that defines the editor used.

📘

Note

Validation settings have multiple API fields that apply to this property. Which ones are available depend on the data type of the property.

Property formats

The property format on a content type property references a predefined format. The format is a preset that defines validation rules, which editor to use, and settings for that editor. A format is always associated with a specific data type.

Read more about property formats.

Data types

Every content property has a data type.

• string – A string value.
• boolean – A Boolean value (true, false, or not set).
• integer – A whole number.
• float – A fractional number.
• dateTime – A date time. The API will provide this value as a string formatted according to the extended ISO 8601-1:2019 profile (2023-09-26T15:47:52Z).
• contentReference – A reference to another content instance.
• binary – A reference to a binary stored in the CMS.
• content – Represents a composition of another content item (inline or referenced).
• component – Represents a composition of another content item of a specific content type (inline only).
• array – A list of values you must specify with the item's data type in the array.

Complex data in CMS is defined using a content type. You can then assign the content type to a property with a component or content dataType. The content type of a component property is predefined and always the same, while you can assign any content type to a content property unless limited to a specific set.

Validation fields

You can apply validation fields to individual properties. Which of these settings is available depends on the data type of the property to which it is applied. Validation fields ignore fields that do not apply to the data type.

• maxLength (string, array) – Maximum length of a valid string or array.
• pattern (string) – The string must adhere to a regular expression pattern.
• allowedTypes (content, contentReference) – An array of content types that are allowed in the property.
• restrictedTypes (content, contentReference) – An array of content types that are not allowed in this property. It has priority over allowedTypes.
• minimum (integer, float, dateTime) – The property's minimum value. Inclusive.
• maximum (integer, float, dateTime) – The property's maximum value. Inclusive.
• enum (string, integer, float) – A list of valid possible values for the property.

GET https://example.com/_cms/v1/contenttypes?forContainerType=news

Create a content type

You can create content types using the content type API. You must provide a unique key and a baseType.

POST https://example.com/_cms/v1/contenttypes
Content-Type: application/json

{
    "key": "story",
    "baseType": "component",
    "displayName": "Story",
    "properties": {
        "heading": {
            "type": "string",
            "displayName": "Heading",
            "description": "Write the greatest heading you can think of."
            "localized": true,
            "required": true,
            "sortOrder": 10,
            "maxLength": 100
        },
        "body": {
            "type": "string",
            "format": "html",
            "displayName": "Body text",
            "localized": true,
            "required": true,
            "sortOrder": 20
        },
        "tags": {
            "type": "array",
            "required": false,
            "sortOrder": 30,
            "items": {
                "type": "string",
                "format": "shortString",
                "maxLength": 50
            } 
        }
    }
}

Update a content type

You can update existing content types using the content type API, but you cannot update the key or baseType of an existing content type.

PUT https://example.com/_cms/v1/contenttypes/story
Content-Type: application/json

{
    "key": "story",
    "baseType": "component",
    "displayName": "Story",
    "properties": {
        "heading": {
            "type": "string",
            "displayName": "Heading",
            "description": "Write the greatest heading you can think of."
            "localized": true,
            "required": true,
            "sortOrder": 10,
            "maxLength": 100
        },
        "body": {
            "type": "string",
            "format": "html",
            "displayName": "Body text",
            "localized": true,
            "required": true,
            "sortOrder": 20
        }
    }
}

You can modify individual content type properties and field values. The response returns the updated content type.

PATCH https://example.com/_cms/v1/contenttypes/story
Content-Type: application/merge-patch+json

{
    "properties": {
        "heading": {
            "required": false
        }
    }
}

Get a specific content type

You can retrieve a content type using content type API with its unique key.

GET https://example.com/_cms/v1/contenttypes/story

{
    "key": "story",
    "displayName": "Story",
    "description": "The Story contains data about news stories."
    "baseType": "component",
    "sortOrder": 10,
    "mayContainTypes": [ "*" ],
    "features": [ "localization", "versioning", "publishPeriod" ],
    "usage": [ "property", "instance" ],
    "source": "",
    "created": "2023-05-22T14:31:08.43+00:00",
    "lastModified": "2023-05-22T14:31:20.557+00:00",
    "lastModifiedBy": "steve",
    "properties": {
        "heading": {
            "type": "string",
            "displayName": "Heading",
            "description": "Write the greatest heading you can think of."
            "localized": true,
            "required": true,
            "sortOrder": 10,
            "maxLength": 100
        },
        "body": {
            "type": "string",
            "format": "html",
            "displayName": "Body text",
            "localized": true,
            "required": true,
            "sortOrder": 20
        },
        "tags": {
            "type": "array",
            "required": false,
            "sortOrder": 30,
            "items": {
                "type": "string",
                "format": "shortString",
                "maxLength": 50
            } 
        }
    }
}

List content types

You can retrieve a list of content types using the content type API.

GET https://example.com/_cms/v1/contenttypes

{
  "items": [
    {
      "key": "story",
      "baseType": "component",
      "displayName": "Story"
    },
    {
      "key": "newspage",
      "baseType": "page",
      "displayName": "News"
    }
  ],
  "pageSize": 10,
  "pageIndex": 0,
  "totalItemCount": 2
}

List editable content types

Because you can edit only certain content types, you may want to list only editable content types by providing the sources parameter.

The value default returns content types where the source field is empty.

List content types from a specific source

You can restrict the listing only to return content types from one or more sources. For example, you could use this to limit the listing to include only content types that are editable in the UI.

The value default indicates that content types where the source field is empty should be returned; all indicates that every content type, regardless of source, should be returned.

GET https://example.com/_cms/v1/contenttypes?sources=default,custom

List content types you can create under a content type

Use the forContainerType parameter to list which content type you can create under another content type.

GET https://example.com/_cms/v1/contenttypes?forContainerType=news

Delete a content type

You can delete existing content types using the content type API. You cannot delete built-in content types.

DELETE https://example.com/_cms/v1/contenttypes/story