Skip to main content
Skip table of contents

HCMS Schema - Core

Describes the general structure of the Headless CMS schemas.

Entities are defined by an extended JSON schema: A JSON document as defined by JSON schema Draft 7 with additional properties that describe storage and mapping details. By convention, these additional properties always start with cs:.

Basic Requirements

The following rules need to be observed when writing a JSON schema for the Headless CMS:

  • Every schema must be explicitly and unambiguously typed using the validation keyword type with a single type except null and optionally null as a secondary type to allow null values.
  • Conditional (if, then, else) and boolean logic (allOf, anyOf, oneOf, not) validation keywords are not supported.
  • For schemas of a scalar type, the appropriate validation keywords out of enum, const, mulitpleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum, maxLength, minLength and pattern are supported.
  • For schemas that are of the type object, all properties must be specified using sub schemas either with the properties keyword in general or with the patternProperties keyword for some special mappings. The keywords maxProperties, minProperties, required, additionalProperties, dependencies and propertyNames can be used to apply further constraints to the schema.
  • For schemas that are of the type array, the elements must be specified using the keyword items and a single sub schema. The sub schema must not be of the type array itself. The keyword additionalItems is not supported. The keywords maxItems, minItems, uniqueItems and contains can be used to apply further constraints.
  • Schema references ($ref) can be used instead of the allowed validation keywords and must not result in a recursive schema structure.

Basic Mapping

Entities as censhare Assets

All Headless CMS data is stored as entities; each entity is one record in censhare, known as asset, and identified by id , a 64-bit integer number, sequentially assigned and externally represented as JSON document conforming to JSON schema. Entities can be created, updated, deleted and of course read, listed and searched for.

Internal Representation

Although the Headless CMS hides much of the censhare servers internals to the entity API user and provides simple solution for storing data, there are some aspects that must be considered.

Entities are stored as censhare assets, entity properties are stored as asset features, as other assets or as storage files. Some features are always present in features, therefor they are always present in the underlying assets, even when they are not mapped to any property in schema. Especially noteworthy are:

  • "cs:feature.key": "censhare:asset.id"
    • This is the id used as a identifier of the entity
    • It is recommended to be mapped in every schema
    • It is not possible to write this value as it is assigned automatically
  • "cs:feature.key": "censhare:asset.type"
    • This feature identifies the entity type
    • Schema/entity mapping is defined by this feature
    • Changing of this property is not recommended

Mapping Rules

The following mapping rules apply when no censhare specific mapping keywords (cs:*) are used:

  • The whole entity itself is mapped to an censhare asset of an automatically created asset type.
    • The asset type id is constructed using the namespace from the HCMS configuration and the entity name using the following pattern: <namespace>.<entity-name>.entity.
    • The asset type name and description are derived from the JSON schema properties title and description respectively.
  • Schemas of a scalar type are mapped to censhare asset features using an automatically created feature.
    • The feature id is constructed using the namespace from the HCMS configuration, the entity name and the property name using the following pattern. <namespace>.<entity-name>:<property-name>. For nested properties, all property names from the schema root are concatenated using a dot character.
    • The feature value type is Text (String), Integer (Long), Floating-point number (Double) and Boolean for the respective JSON schema types string, integer, number and boolean.
    • When a set of enumeration values is specified using the keywords enum or const for the schema type string or integer, a feature of the value type Value list (String) with the appropriate values is created.
    • The feature name and description are derived from the JSON schema properties title and description respectively.
    • If the scalar property is either missing or has a null value during import the mapped asset feature is deleted.
    • If there is no mapped asset feature during export, the entire property is either skipped or written using a null value of it is part of the required keyword in the schema.
  • Schemas of the type array change the mapping of their sub schema to a multi value censhare feature.
    • The order of the array elements is mapped using the sorting attribute of the asset feature.
    • If the array property is missing, has a null value or an empty array, all mapped asset features are deleted.
    • If there are no mapped asset features during export, the property is either skipped or written using an empty array if it is part of the required keyword in the schema.
  • Schemas of the type object are only mapped when they occur as a sub schema of an array. Otherwise they are considered structural decoration and not mapped at all. Their properties in turn are mapped according to these rules.
    • Inside an array the mapping works along the lines of scalar values, but with a feature value type of None.

Root Level

The root level of the schema defines the entity itself and it is required to be of "type": "object", because entities have to be JSON objects.

  • "cs:asset.type": Asset type(s) represented by this schema
    • Defines what censhare asset type is used to store to and query from entities belonging to this schema
    • (Optional) By default a new asset type is automatically generated registered
    • Wildcards are supported in version 4.2 or later. Please check the changelog (Release Notes) and your version.
      • Wildcard means "specified type or its subtypes" and is represented by a * (asterisk) character at the end of the type definition (that is, after the last dot).
      • No other types of wildcards are supported, so the * character cannot be present anywhere else.
      • Wildcard with empty base type is allowed: simple "*" string means that any asset type is accepted.
      • Examples of valid values: "*", "video.*", "user.account.*"
      • Examples of invalid values: "*.account.", "vid*."
    • Value of this property can be one of:
      • null means that the schema does not directly represent any asset; it is a mixin and can be included in other schemas.
      • Single string value means that the schema represents assets of one particular asset type. New assets will be created with this schema (unless the value is a wildcard).
      • Array of strings means that the schema can represent assets of all these types.
        • If the array is longer than one element, new entities are not allowed. Any attempt to create new entity fails with errors (it is not clear what would the asset type be).
        • Single-element array is just an alternate representation simple string value.
      • JSON object with asset types and optional default. Detailed description is below.
  • "cs:$mixin": Array of string containing the schema reference names of the mixins (schema name with suffix -schema.json)
    • The referenced mixins need to already registered on the endpoint
    • See also below.
  • "cs:$no_new_masterdata": true
    • Prevents the automatic creation of master data that is declared in this schema but is not present in the censhare application server
    • (Optional) If not present, the missing master data is automatically created.
    • Please note that the automatic creation of master data can be deactivated centrally in the HCMS configuration. In this case the switches in the schemas will be overwritten.
  • "cs:fulltext.$faceted": true
    • Allows use of faceted fulltext search in queries
    • Only allowed features mapped as a scalar value (no pairs, no inlined references).
    • Default is false
  • cs:$priority: Priority of this schema in link-generator algorithm.
    • Default is 0.
    • Used only if there are more than one schema for given asset type. The schema with lowest priority is selected; in case of tie, the choice is not deterministic.
  • "cs:update.new.version": Whether the asset updates create new version or not.
    • Boolean value (true or false). When missing, the global configuration is used (usually false).

Full cs:asset.type description (JSON object) can contain following properties:

  • "types": Array of all asset types (strings). This is basically the same as a string value directly used for cs:asset.type, but simplified string form is not allowed here.
    • Required.
    • Wildcards are accepted (if the HCMS version supports it).
  • "default": (Optional) Default asset type used for new assets.
    • It is automatically added at the end of the "types" array (unless it is already present in it).
    • When missing and the "types" has more than one type, new entities cannot be created.
    • This value cannot be a wildcard, ever.
  • "mimetype-of": (Optional) List of storage items used to autodetect asset type.
    • Used only together with "default". Without extensive list of allowed types and default, it has no effect.
    • Detection uses masterdata definition, defined in Java Admin Client (MIME types).
    • Following conditions need to be satisfied to actually use asset type from masterdata:
      • New entity is created.
      • Storage item of given type is created.
      • Mime type of this storage item is configured in masterdata and the record has "Default Asset Type" specified.
      • This asset type is allowed by the mapping (it's either in "types" array or in the "default" property). Any other asset type is ignored by this algorithm (to ensure that the new asset is visible as this entity).
      • First asset type that matches these criteria is used as an asset type of the new asset.
      • If no such match is found, the "default" is used.

Examples:

JSON 
    "cs:asset.type": {
        "types": ["picture.", "video.", "document."],
        "mimetype-of": ["master"],
        "default": "temp.upload."
    },
JSON 
    "cs:asset.type": {
        "types": ["picture.*", "video.*", "document.*", "temp.*"],
        "mimetype-of": ["master"],
        "default": "temp.upload."
    },

Mixin

Mixins provide a mechanism for managing common property subsets among multiple schemas. Mixins are similar to schemas as they hold property definitions, but can be included included into regular schemas. The defining difference between a mixin and a schema is that it is not assigned to asset types, but to null, see root level. As a consequence entities can not be based directly on a mixin and there are no entity endpoints for mixins, although they are otherwise managed through the schema endpoint.

When an mixin is included in an entity, see section root level, all property definitions of the mixin are included into the schema, the other parts of the mixin are ignored, including all cs: metadata. Note that duplicate property definitions are not allowed. Declarations of the same property in the mixin and the including schema will lead to the rejection of the schema. Mixins can form inheritance like structures by including other mixins, in which inclusion of the same mixin at several levels is possible.

Mixin properties can be used in queries as they will automatically be replaced by all effective schemas that use this mixin directly or indirectly.

Mixin Example

The following mixin provides the features censhare:asset.name and censhare:asset.id, which are present on all assets:

JSON 
{
    "cs:asset.type" : null,
    "type" : "object",
    "properties" : {
        "name" : {
            "type" : "string",
            "cs:feature.key" : "censhare:asset.name"
        },
        "id" : {
            "type" : "number",
            "cs:feature.key" : "censhare:asset.id"
        }
    }
}

Assuming the mixin above has been registered under the name asset the following schema text can reference it to inherit its properties:

JSON 
{
    "cs:$mixin": [
        "asset-schema.json"
    ],
    "cs:asset.type": "text.",
    "type": "object",
    "properties": {
        "content": {
            "cs:storage.item": "master",
            "type": "string"
        }
    }
}

Accessing the effective schema reveals that censhare:asset.name and censhare:asset.id have been included:

JSON 
{
    "cs:$mixin": [
        "asset-schema.json"
    ],
    "cs:asset.type": "text.",
    "type": "object",
    "properties": {
        "name": {
            "cs:feature.key": "censhare:asset.name",
            "type": "string"
        },
        "id": {
            "cs:feature.key": "censhare:asset.id",
            "type": "number"
        },
        "content": {
            "cs:storage.item": "master",
            "type": "string"
        }
    }
}

Therefor all three properties are included into the entities:

JSON 
{
    "name": "words.txt",
    "id": 13612,
    "content": "Tips for Creating Content, and Getting It Found."
}

Data-less Object

Property defined as "type": "object" with no additional metadata is considered data-less: it is not stored anywhere, it just provides one level in JSON structure. The actual payload data must be stored somewhere in its properties. When writing JSON output, data-less entities are omitted if empty. For this reason, it is not recommended to declare them as required.

Constant Mapping

Constant string properties that have their value specified using JSON schema "const" or a single value "enum" can be mapped using "cs:$const": true. They are not mapped to/from the data store, but the value is added during export.

Ignore Mapping

Any schema type can be marked using "cs:$ignore": true which is then ignored during mapping, but the validation is still be performed.

String property with special feature "cs:entity.link" is used to generate links (URL endpoints) representing the serialized asset. If can be used both at the top level (to represent the enity) or in inlined assets (via relations or reference feature). In the latter case, the link is available only if the asset type is also part of some entity schema - otherwise, property is missing.

Note that in the case of multiple possibilities, the link is resolved by schema priority and it is possible that it will use different schema than the one currently being serialized.

In import (create/update), any such property is just ignored.

JSON 
"link": {
  "cs:entity.link": true,
  "type": "string"
},

change

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close