Content types

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

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 (SaaS) are:

• 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. Does not support multiple locale branches.
• video – Used to store video binary data. Does not support multiple locale branches.
• folder – Used to organize other content. Does not support multiple versions or multiple locale branches.
• experience – Represents an experience. Each content instance is unique, supports multiple branches, and cannot be used as a field on other content types. Can contain a dynamic layout similar to a content area with nested blocks, but instead made up of sections and elements.
• section – Represents a section, part of an experience through its layout field. Each instance is unique, supports multiple branches, and cannot be used as fields on other content types. Can contain dynamic layout like an experience with the difference that it only can contain elements.
• element – Represents an element, part of a section. Each instance is unique, supports multiple branches, and cannot be used as fields on other content types. An element is similar to a block in many ways and constitutes the leaf in the hierarchy of experiences and sections. It contains the actual authored content.

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. For example, 2023-09-26T15:47:52Z.
• contentReference – A reference to another content instance.
• binary – A reference to a binary stored in CMS (SaaS).
• 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 (SaaS) is defined using a content type. You can assign the content type to a property with a component or content data type. The content type of a component property is predefined and is 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 settings are 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/preview2/contenttypes?forContainerType=news

See ContentTypes API reference.

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/preview2/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
            } 
        }
    }
}

See Create content type API reference.

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/preview2/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
        }
    }
}

See Create or replace content type API reference.

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

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

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

See Update content API reference.

Get a specific content type

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

GET https://example.com/_cms/preview2/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
            } 
        }
    }
}

See Get content type API reference.

List content types

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

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

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

See List content types API reference.

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 list to only 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/preview2/contenttypes?sources=default,custom

See List content types API reference.

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/preview2/contenttypes?forContainerType=news

See List content types API reference.

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/preview2/contenttypes/story

See Delete content type API reference.