Docs Developer Site
Developer Docs CMS reference docs 8.x Schemas CMS descriptor

CMS descriptor

Contents

The CMS descriptor (cms.yaml) marks an application as a CMS contributor and exposes its schemas for assignment to content projects and sites.

Introduction

cms.yaml is the application-level descriptor for the CMS. Its presence is what makes an application assignable to a content project or a site — without it, the schemas it ships will not appear in CMS contexts. The descriptor also lets the developer declare:

  • A configuration form shown to administrators when the application is added to a project or site, capturing per-instance settings.

  • Mixins that should be activated on content within the assigned scope, with optional content-type filtering.

The descriptor normally resides at src/main/resources/cms/cms.yaml inside the app, and the application name is the namespace of its schemas. See Deployment below for packaging and registration details.

Descriptor

kind: "CMS"  (1)
form:  (2)
  - type: "TextLine"
    name: "api_key"
    label: "API key"
    occurrences:
      min: 1
      max: 1
mixins:  (3)
  - name: "address"
1 kind (required) Identifies this as a CMS descriptor. Without kind: "CMS", the file is ignored and the application will not appear as installable in Content Studio’s project or site app-picker.
2 form (optional) A Form definition rendered when an administrator adds the application to a project or site. The submitted values are persisted alongside the assignment and are available at runtime — useful for per-instance settings such as API keys, feature flags, or endpoint URLs.
3 mixins (optional) Registers mixins to be activated on content within the assigned scope. See Mixin registration below for filtering and optional-mode variants.

Mixin registration

Mixins declared under mixins: are applied by default to all content types within the project or site that hosts the application. Two attributes refine that behaviour:

allowContentTypes

A regular expression matched against the qualified content-type name. Only matching content types receive the mixin.

optional

When true, the mixin is not added automatically — editors must enable it per content item from within the Content Wizard.

kind: "CMS"
mixins:
  - name: "my-mixin-1"  (1)
  - name: "my-mixin-2"  (2)
    allowContentTypes: "^(?!base:folder$).*"
  - name: "my-mixin-3"  (3)
    allowContentTypes: "portal:site"
    optional: true
1 Activated for all content types, no opt-out.
2 Activated for all content types except base:folder.
3 Available to portal:site content only, and only when an editor explicitly enables it.

See content type filtering modes for the full regex syntax accepted by allowContentTypes.

Deployment

Schemas are deployed to Enonic XP as part of an application. The CMS descriptor and all schemas it references live in the application’s src/main/resources/cms/ directory, and are registered automatically when the application is installed — instantly reflected in Content Studio and the headless APIs.

See the schema packaging and deployment reference in the Enonic Development Kit docs for project layout, build configuration, and registration details.

An app that also contributes page components ships a separate site.yaml descriptor alongside cms.yaml. site.yaml belongs to Enonic’s app-rendering paradigm (parts, layouts, controllers, page contributions) and is documented in the Enonic Development Kit docs.

Contents

Contents