Feature Definition

A Feature Definition is a cross-cutting concern or Aspect that you can apply arbitrarily to content instances or content types (to apply to all instances of a type). A Feature Definition is used to optionally describe additional schema that should be applied to a content or association type. Feature Definitions also endow content instances with special behaviors.

Feature Definitions are defined in much the same way as Types or Associations. Each Feature has a QName and the JSON Schema that should be adopted.

Here is a feature that defines a custom Authorable feature. We give it the QName my:authorable. The feature introduces an Author property to any content it is endowed upon.

{
    "title": "Authorable",
    "type": "object",
    "properties": {
        "author": {
            "type": "string",
            "title": "Author"
        }
    },
    "_type": "d:feature"
}

For a list of out-of-the-box features and more information about how they work, please see the Features section of the documentation.

Applying Features to Content Instances

To apply a Feature to a content instance (a Node), you simply add it to the _features block of your Node's JSON along with the enabled flag set to true.

Suppose we have an Article instance. The JSON for the content instance node might look like this:

{
    "title": "My Article",
    "body": "Here is the text for my article...",
    "rating": 3,
    "_type": "my:article"
}

The _type field tells Cloud CMS that this JSON conforms to the Type Definition for the QName my:article.

To add the my:authorable Feature to this content instance, we simply adjust the JSON so that it looks like this:

{
    "title": "My Article",
    "body": "Here is the text for my article...",
    "rating": 3,
    "_type": "my:article",
    "_features": {
        "my:authorable": {
            "enabled": true
        }
    }
}

When we save our changes, Cloud CMS will recompile the dictionary and this node will validate against a schema which consists of the Article Type Definition in conjunction with the Authorable Feature Definition. As a result, our node's JSON will support an additional property called author which is endowed from the Feature.

Cloud CMS will automatically make this property available in forms and any server and client-side validation logic will take this new property into account.

Apply Features to Content Types

In addition to assigning Features at an instance-by-instance level, you can also assign them to Type Definitions so that Features are mandated for any content instances. To do so, simply add your Feature's QName to the mandatoryFeatures block in your definition. Like this:

{
    "title": "Article",
    "type": "object",
    "properties": {
        "title": {
            "type": "string",
            "title": "Title"
        },
        "body": {
            "type": "string",
            "title": "Body"
        },
        "rating": {
            "type": "number",
            "minimum": 0,
            "maximum": 10
        }
    },
    "_qname": "my:article",
    "_type": "d:type",
    "_parent": "n:node",
    "mandatoryFeatures": {
        "my:authorable": {
            "enabled": true
        }
    }
}

By setting the Feature as mandatory on the Type Definition, it will automatically be applied to all content instances (nodes) that are of this type. This effectively accomplishes the same thing as the previous example where we applied the Feature at the instance-level, except that we've now done it for all instances of this type.

Note - be sure to use mandatoryFeatures when assigning type-scoped features. One might be tempted to use the _features block. However, the _features block is for instance-level assignment. If you did use _features, you would be assigning features to the Type Definition instance. Recall that in Cloud CMS, everything is content. Even content definitions! They're just content of types d:type, d:association or d:feature.