Definitions

A content definition is a JSON schema v4 document that informs Cloud CMS of a new content type. The JSON schema semantics spell out the exact properties that a content type should have, the types of every element (such as whether a property is a string or a number), constraints and other nested aspects of the content type.

Definitions come in several flavors, the main ones being:

Cloud CMS lets you create adhoc content on the fly which means that you don't technically need definitions. You can just throw JSON content into Cloud CMS and everything works fine. However, definitions provide you with a structured way to automate server-side validation and data integrity checking ahead of write. This lets you assert that your data conforms to an expected schema.

If you create content that has a definition (i.e. a _type property), the content will first run through JSON schema validation ahead of writing. If the JSON schema validation throws, the write is aborted and an error is returned.

Example

A content definition is just a node like any other node.

As a really simple example, you might define an article like this:

{
    "_qname": "custom:article",
    "_type": "d:type",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "author": {
            "type": "string",
            "required": true
        }
    }
}

A content definition is simply a JSON schema document with a special qname property that identifies the definition's QName and a type property that indicates this is a type definition (d:type). You might also choose to define an association (d:association) or a feature (d:feature).

With JSON schema, there's quite a lot you can do and the entirety of it isn't spelled out here. That said, Cloud CMS is fully complaint with v4 of the specification and so you can take full advantage of JSON schema to define your content types, constraints and properties.

QNames

A QName is a unique term within the Cloud CMS dictionary. The dictionary exists on a per-branch basis and is automatically recompiled every time you make a change to a definition. The compilation step wires together validation logic, behaviors and other runtime necessities so that your content is persisted properly going forward.

In Cloud CMS, every object has a QName. In most cases, this QName is auto-generated for you. For example, if you create a node and the node has ID 1234567890, then by convention, it will be automatically assigned a QName of o:1234567890.

A content definition explicitly declares its QName. In the example above, the content definition has a QName of custom:article. Upon saving this node, the Cloud CMS dictionary will detect that a new type was added and will reserve the custom:article namespace for this definition. Only one namespace is allowed per branch. If another definition comes along and tries to save itself as custom:article, the save operation will fail.

Inheritance

Content definitions support inheritance. You can declare a new content definition that inherits from an existing definition. The new content definition will be bestowed with all of the properties, constraints and other aspects of the JSON schema from the parent definition. In addition, any behavioral bindings assigned to the parent will be ascribed to the child as well.

To do so, all you need to do is supply the _parent attribute. Here is an example of a new article type that inherits from the previous one.

{
    "_qname: "custom:article2",
    "_type": "d:type",
    "_parent": "custom:article",
    "type": "object",
    "properties": {
        "score": {
            "type": "number"
        }
    }
}

The new content type has a QName of custom:article2 and will inherit all of the properties and behaviors from custom:article. In addition, it will define a new property called score which is a number.

Properties

Cloud CMS supports the full range of JSON schema properties, constraints and validators. Properties can be nested as well and it is entirely encouraged that you use JSON to it's richest advantage. Cloud CMS will parse these properties at compile time and perform full validation across the entire JSON document.

Default Type (for ad-hoc content)

As mentioned, Cloud CMS supports ad-hoc content creation which means that you don't have to use definitions if you don't want to. Any ad-hoc created content will be of type n:node. Content that is of type n:node doesn't go through the same validation checks as custom content types.

Working with Definitions

You can work with definitions using Cloud CMS user interface, or using the Cloud CMS API within a programmatic fashion.

Cloud CMS

There are 2 choices in Cloud CMS on how to create and mangage the Content Types:

  1. edit the JSON definition (simply go into your project, Manage Project, and click on Definitions menu item)
  2. use the Content Model Builder that makes it a bit easier to work with JSON schema. Check out the documentation on Content Model Builder.

Cloud CMS API

Let's look at some examples of working with definitions from the API.

Create a Definition

To create a definition, simply create a node like you normally would. Here is an example where we create the custom article from above.

// assume we have a branch
var branch = ...;

// create our definition
branch.createNode({
    "_qname": "custom:article",
    "_type": "d:type",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "author": {
            "type": "string",
                "required": true
        }
    }
}).then(function() {
    // ...
})

Afterwards, content instances of type custom:article are created just as before. You only need to specify the _type property of the new node.

// assume we have a branch
var branch = ...;

// create a few nodes
branch.createNode({
    "_type": "custom:article",
    "title": "Germany wins World Cup 2014",
    "body": "...",
    "author": "Franz Meuler"
});

branch.createNode({
    "_type": "custom:article",
    "title": "Bolivia training for World Cup 2018",
    "body": "...",
    "author": "Anita Barrios"
});

You can also query to find any nodes of type custom:article.

// assume we have a branch
var branch = ...;

// find instances of type "custom:article"
branch.queryNodes({
    "_type": "custom:article"
}).each(function() {
    console.log("Found article: " + this.title);
});

Delete a Definition

To delete a definition, you find the node defining your definition and then delete it. Cloud CMS will handle all of the dictionary recompilation and will sort things out.

// assume we have a branch
var branch = ...;

// find our type (using it's qname) and then delete it
branch.queryNodes({
    "_qname": "custom:article"
}).keepOne().del();

If there are existing content instances of type custom:article, the attempt to delete the type will fail. The error message will indicate the IDs of the content instance nodes that must first be resolved. Those instances must either first be deleted or have their content type changed.

Changing a Content Instance's Type

You can change a content instance's type at any time.

// assume we have a branch
var branch = ...;

// find instances of type "custom:article"
branch.queryNodes({
    "_type": "custom:article"
}).each(function() {

    // change each one back to n:node
    this.changeTypeQName("n:node");

});

Default Content Definitions

Cloud CMS comes pre-installed with a library of ready-to-go definitions for a variety of cases.

Content Type Definitions

QName Title Parent Description
blog:blog Blog
blog:post Blog Post
n:comment Node n:node A comment
n:company Comment n:node
n:email_template Email Template n:node
n:form Form n:node
n:group Group n:node
n:heatmap Heat Map n:node
n:list Data List n:node
n:node Node A node
n:person Person n:node
n:role Role n:node
n:root Root Node of Repository n:node
n:rule Rule n:node
n:tag Tag n:node
wcm:page WCM Page n:node
wcm:template WCM Page Template n:node
workflow:package Workflow Package n:node

Association Type Definitions

QName Title Parent Description
a:child Child Association a:owned
a:copied_from Copied From Association a:linked
a:created Created Association a:linked
a:deems_helpful Deems Helpful Association a:linked
a:deems_spam Deems Spam Association a:linked
a:deems_unhelpful Deems Unhelpful Association a:linked
a:deleted Deleted Association a:linked
a:dislikes Dislikes Association a:linked
a:has_behavior Has Behavior Association a:linked
a:has_comment Has Comment Association a:linked
a:has_form Has Form Association a:linked
a:has_lock Has Lock Association a:linked
a:has_mount Has Mount Association a:linked
a:has_rendition Has Rendition Association a:linked
a:has_role Has Role Association a:linked
a:has_tag Has Tag Association a:linked
a:has_translation Has Translation Association a:linked
a:likes Likes Association a:linked
a:linked Linked Association n/a
a:list_item List Item Association a:owned
a:owned Owned Association n/a
a:updated Updated Association a:linked
wcm:page_has_content WCM Page has Content a:linked
workflow:package_has_item Workflow Package has Item a:linked
blog:has_post Blog has Post a:linked

Feature Definitions

For information on feature definitions and their use, check out Features.