HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Content types

Describes the Content Type resource and how to create and manage them.

πŸ‘

Beta

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

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

Base type

The content type itself 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:

Base typeDescriptionCharacteristics
componentA generic content type used as a field on other content instances, or as a standalone instance.Supports multiple locale branches.
pageRepresents a web page. Each content instance is a unique instance.Supports multiple locale branches. Cannot be modeled as fields on other content types.
mediaRepresents content that has binary data associated with it; a generic content type for binary data.Content instances based on media do not support multiple locale branches.
imageUsed to store image binary data.Does not support multiple locale branches.
videoUsed to store video binary data.Does not support multiple locale branches.
folderUsed to organize other contentDoes not support multiple versions or multiple locale branches.

Standard fields

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

NameAPI fieldDescription
KeykeyThe unique identifier of a content type used in the API.
Display NamedisplayNameA user-friendly name for the content type used, such as in the UI for editors.
DescriptiondescriptionA description of the content type used, such as in the UI for editors.
Base typebaseTypeThe base type of the content type.
Sort ordersortOrderA relative index used in some listings to define the order of content types.
May contain typesmayContainTypesA list of content types that you can create under content instances of the content type. Can either be a content type key or the name of a base type.
FeaturesfeaturesA list of features that this content types have. The value of this field is derived from the base type and cannot be changed.
UsageusageDefines where this content type can be used. The value of this field is derived from the base type and cannot be changed. Possible values are property and instance. property indicates that the content type can be used as a component property. instance indicates that the content type can be created as a standalone instance.
SourcesourceA string indicating the source of this content type. Will be empty for content types added through the UI and set to system for built-in content types.
CreatedcreatedA timestamp indicating when this content type was created.
Last modifiedlastModifiedA timestamp indicating when this content type was last modified.
Last modified bylastModifiedByA string indicating the username of the user that last modified this content type.

Properties

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

NameAPI fieldDescription
TypetypeThe data type of the property. One of the data types described below.
FormatformatReference to a predefined data format, which can include validation rules, editor, and editor settings.
Display NamedisplayNameA user-friendly name for the content type used, such as in the UI for editors.
DescriptiondescriptionA description of the content type used, such as in the UI for editors.
LocalizedlocalizedIndicates if the property has a different value for each locale, or if the same value should apply to all locales.
RequiredrequiredIndicates if the property must be given a value.
GroupgroupA reference to the group under which this property is organized.
Sort ordersortOrderA relative index used in some listings to define the order of content types.
EditoreditorA reference to an editor specification that defines the editor that is used.
Editor settingseditorSettingsDefines settings for the defined editor.
Validation settings[multiple]Validation settings that apply to this property. Which ones are available depend on the data type of the property.

Data types

Every content property is defined with a data type.

Data typeDescription
stringA string value.
booleanA Boolean value. Can be true, false or not set.
integerA whole number.
floatA fractional number.
dateTimeA date time. The API will provide this value as a string formatted according to the extended ISO 8601-1:2019 profile, e.g. '2023-09-26T15:47:52Z'.
contentReferenceA reference to another content instance.
binaryA reference to a binary stored in the CMS.
contentRepresents a composition of another content item. Can be inline or referenced.
componentRepresents a composition of another content item of a specific content type. Always inline.
arrayA list of values. An array must always be specified together with the data type of the item in the array.

Complex types

Complex data in CMS is always defined using a Content Type. The Content Type can then be assigned to a property with a component or content dataType. The content type of a component property is pre-defined and always the same, while any content type can be assigned to a content property unless limited to a specific set.

Property formats

The property format on a content type property is a reference to 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.

Validation settings

Validation settings are fields that you can apply to individual properties. Which of these settings are available depends on the data type of the property the apply to. Fields that do not apply to the data type are ignored.

Validation fieldData typeDescription
minLengthstring, arrayMinimum length of a valid string or array.
maxLengthstring, arrayMaximum length of a valid string or array.
patternstringRegular expression pattern that the string must adhere to.
allowedTypescontent, contentReferenceArray of content types that are allowed in the property.
restrictedTypescontent, contentReferenceArray of content types that are specifically not allowed in this property. Has priority over allowedTypes.
minimuminteger, float, dateTimeMinimum value of the property. Inclusive.
maximuminteger, float, dateTimeMaximum value of the property. Inclusive.
enumstring, integer, floatA list of possible values that are considered valid for the property.

Work with content types

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 all content types using 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. This can be done by providing the the sources parameter.

The value default indicates that content types where the source field is empty should be returned.

List content types from a specific source

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

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 that can be created under a content type

Use the forContainerType parameter to list which content type can be created under another content type.

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 updated content type will be returned in the response.

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

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

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