HCMS censhare Server Meta Data
Explains how to read out censhare Server meta data in the Headless CMS
censhare Server Meta Data
Most properties are mapped to censhare server object with detailed description, also known as "masterdata" or "cached tables". This description can be obtained by two ways:
for all properties at once by invoking GET /schema/{name}/descriptive
description is always added as special JSON object cs:$description
for single property by invoking GET /schema/{name}/cs-description/{path}
description is directly returned
Description texts are in default language (english).
If the specific text is also available in different languages, special property with localized_ prefix is present and it contains texts in various languages.
All descriptions contain at least the identification key and a "name" property; this is, in most cases, accompanied by "localized_name" with translations.
*searchable" flag
This boolean value can be used to determine if the property is usable for searching or not. Usually, relations and most features have true value (but not all of them), while most storage item attributes usually have false (only selected few attributes on master storage item are searchable). Storage items themselves (raw value) are never searchable.
This is especially handy if the query form is dynamically generated on top of descriptive schema.
Assets
Description of asset mapping always contains array of possible types (even if there is exactly one).
"cs:asset.type": "picture.",
"cs:$description": {
"types": [
{
"name": "Person",
"type": "person."
}
]
} "cs:asset.type": "picture.",
"cs:$description": {
"types": [
{
"name": "Image",
"type": "picture.",
"localized_name": {
"de": "Bild"
}
}
]
},Relation
Description of relation contains many texts:
name and description
child and parent describe assets at each end of the relation
this is equal to either child or parent (depending on which side of the relation is this entity present)
cardinality describes relation's suggested cardinality (it is not enforced in any way)
"likedBy": {
"type": "array",
"items": {
"cs:relation.direction": "child",
"cs:relation.$ref_type": "link",
"cs:relation.key": "user.liked-by.",
"cs:$description": {
"parent": "Likes",
"name": "Liked By",
"this": "Liked by",
"localized_child": {
"de": "Liked von"
},
"key": "user.liked-by.",
"cardinality": "many-to-many",
"child": "Liked by",
"localized_name": {
"de": "Beliebt bei"
}
},
"type": "string",
}
},Relation with inlined content also contains description of the asset types in special property "inlined":
"content": {
"patternProperties": {
"^[a-z]{2}([A-Z]+)?$": {
"cs:relation.direction": "child",
"cs:relation.key": "user.main-content.",
"cs:$description": {
"parent": "Main content of",
"localized_description": {
"de": "Hauptinhalt-Verknüpfung"
},
"name": "Main content",
"localized_parent": {
"de": "Hauptinhalt von"
},
"this": "Main content",
"description": "Main content relation",
"localized_child": {
"de": "Hauptinhalt"
},
"inlined": {
"types": [
{
"name": "Text",
"type": "text."
}
]
},
"key": "user.main-content.",
"cardinality": "many-to-many",
"child": "Main content",
"localized_name": {
"de": "Hauptinhalt"
}
},
"description": "Main content relation",
"cs:feature.$locale_property": "language",
"type": "object",
"title": "Main content",
"$ref": "article_content-schema.json#/",Storage item
Storage item is described simply by its name.
"preview": {
"cs:storage.item": "preview",
"cs:$description": {
"name": "Preview",
"key": "preview",
"localized_name": {
"de": "Voransicht"
}
},
"cs:link": "download",
"type": "string"
}Storage item attribute
Most storage item attributes have no description available.
The only exception is the "mimetype" attribute, which provides list of all supported mime types.
Note that this example is significantly pruned to contain only four mime types.
"mime": {
"cs:storage.$attribute": "mimetype",
"cs:$description": {
"searchable": false,
"values": [
{
"extension": ".obj",
"localized_description": {
"de": "Wavefront 3D Objekt-Datei"
},
"name": "Wavefront 3D Object File",
"description": "Wavefront 3D Object File",
"value": "application/vnd.wavefront.obj",
"localized_name": {
"de": "Wavefront 3D Objekt-Datei"
}
},
{
"extension": ".wav",
"name": "Waveform Audio",
"description": "Waveform Audio",
"value": "audio/wav"
},
{
"extension": ".groovy",
"localized_description": {
"de": "Groovy-Skript"
},
"name": "Groovy script",
"description": "Groovy script",
"value": "application/x-groovy",
"localized_name": {
"de": "Groovy-Skript"
}
},
{
"extension": ".cr2",
"name": "Canon 2 RAW image",
"value": "image/x-canon-cr2",
"localized_name": {
"de": "Canon 2 RAW-Bild"
}
}
]
},
"type": "string"Feature
Feature is described by many texts, most of them optional:
name and description
label, placeholder and tooltip (for GUI form construction)
child and parent if the feature is of asset-ref type (semantic is the same as for relation)
"name": {
"cs:$description": {
"localized_description": {
"de": "Asset-Name"
},
"name": "Name",
"description": "Asset name",
"placeholder": "Name",
"key": "censhare:asset.name"
},
"description": "Asset name",
"cs:feature.key": "censhare:asset.name",
"type": "string",
"title": "Name"
},Features of type ENUMERATION or HIERARCHICAL is allowed to have only one value of limited set; this set is part of feature description, in property "values". Values are properly sorted (by "sorting" property).
"gender": {
"cs:$description": {
"key": "censhare:address.gender",
"values": [
{
"sorting": 1,
"name": "Male",
"value": "male",
"localized_name": {
"de": "Männlich"
}
},
{
"sorting": 2,
"name": "Female",
"value": "female",
"localized_name": {
"de": "Weiblich"
}
}
],
"description": "Gender (address)",
"localized_description": {
"de": "Geschlecht (Adresse)"
},
"name": "Gender",
"localized_name": {
"de": "Geschlecht"
}
},
"description": "Gender (address)",
"cs:feature.key": "censhare:address/censhare:address.personal-data/censhare:address.gender",
"type": "string",
"title": "Gender",
"enum": [
"male",
"female"
]
},Feature units
If the feature is allowed to have units, its description contains "unitset" that contains all possible units.
If the feature is allowed to have one single unit, its description contains "unit" property with description of this single unit.
Note that these two options are exclusive.
Each unit is desribed by:
name
symbol and optional symbol_alt
property (text describing what does this unit measure)
Some units are derived from other units by constant factor; this is part of unit's description, as property "base" that contains base unit description plus additional property "factor".
"height": {
"cs:$description": {
"unitset": {
"name": "Length",
"units": [
{
"symbol": "mm",
"sorting": 1,
"name": "Millimeter",
"property": "Length",
"base": {
"symbol": "m",
"name": "Meter",
"property": "Length",
"factor": 0.001
}
},
{
"symbol": "cm",
"sorting": 2,
"name": "Centimeter",
"property": "Length",
"localized_name": {
"de": "Zentimeter"
},
"base": {
"symbol": "m",
"name": "Meter",
"property": "Length",
"factor": 0.01
}
},
{
"symbol": "m",
"sorting": 3,
"name": "Meter",
"property": "Length"
},
{
"symbol": "ft",
"sorting": 4,
"name": "Foot",
"property": "Length",
"localized_name": {
"de": "Fuß"
},
"base": {
"symbol": "m",
"name": "Meter",
"property": "Length",
"factor": 0.3048
}
},
{
"symbol": "in",
"sorting": 5,
"name": "Inch",
"property": "Length",
"localized_name": {
"de": "Zoll"
},
"base": {
"symbol": "m",
"name": "Meter",
"property": "Length",
"factor": 0.0254
}
}
],
"key": "censhare:length",
"localized_name": {
"de": "Länge"
}
},
"localized_description": {
"de": "Höhe (Produkt)"
},
"name": "Height (product)",
"description": "Height (product)",
"label": "Height",
"key": "censhare:product.height",
"localized_label": {
"de": "Höhe"
},
"localized_name": {
"de": "Höhe (Produkt)"
}
},
"cs:feature.key": "censhare:product.height",
"type": "object",
"title": "Height (product)",
"properties": {
"unit": {
"type": "string"
},
"value": {
"type": "integer"
}
}
}Other feature types mapped to scalar properties (string, boolean, number, integer) are not technically limited in their values, but in many cases user is able to select only from a limited set of values that acts as an enum list.
It is quite useful to provide this limited set the same way as for enumeration features -- the client application can treat them the same way and use the same code to render value list (dropdown menu, typically).
Features of reference type are often used to emulate enumeration feature, especially when the values are dynamically managed by users without administrative privileges. There are two distinctive ways to define the list of possible values, both via special meta-property "cs:feature.$ref_enum"; see [Asset Reference Features](HCMS Schema - Asset Reference Features) for details.
Other features can have the list statically defined directly in the schema, via special directive "cs:feature.$fake_enum_values".
Content of this directive is validated (any error causes compilation of the whole schema to fail): it must be an array of valid JSON objects, "name" and "value" are mandatory; and all the "value" properties must be of the correct type (the same as the property itself).
Example of hardcoded enum values:
{
"bookmarkable": {
"cs:feature.key": "demo:integer",
"cs:feature.$fake_enum_values": [
{
"enabled": true,
"name": "1.",
"description": "1.",
"value": 1
},
{
"enabled": true,
"name": "2.",
"description": "2.",
"value": 2
},
{
"enabled": true,
"name": "3.",
"description": "3.",
"value": 3
},
{
"enabled": true,
"name": "many",
"description": "too much!",
"value": 4
}
],
"type": "integer"
}
}