Start page / Enhanced JSON support / JSON output of metadata

JSON function: Configuring JSON output of metadata


Metadata is additional information that is available for an object in FirstSpirit. In addition to system-specific metadata, such as “last change date”), project-specific metadata can be maintained as well.

Project-specific metadata is defined via a metadata template (see Options (→Documentation for Administrators)) for the project and can then be maintained on the corresponding FirstSpirit objects (e.g., on a page or page reference) on the “Metadata” register via a form. Some of this project-specific metadata is maintained hierarchically. This means the metadata is maintained on the root node of the store or a subtree and then automatically passed on to all hierarchically subordinate FirstSpirit objects (e.g., with the definition of user rights via the CMS_INPUT_PERMISSION input component).

See also

Metadata can be transferred to a JSON object structure. The JSON output format thereby considers the persistent metadata on the respective FirstSpirit object (pages, page references, media) at the time of generation. The output then contains the metaFormData attribute (see example).

A special case is the JSON output of user rights that were defined for an object via the CMS_INPUT_PERMISSION input component on the “Metadata” register (see JSON output of user permissions).

Configuration of the JSON output

The JSON output of the metadata can be configured via the JSON function.

The output may also include metadata that was not defined on the object itself but inherited by an hierarchically superordinate object.

metadataRendering: rendering metadata (default setting: true)

The JSON rendering of metadata can be activated or deactivated with the $CMS_SET(#global.json.metaDataRendering, <BOOLEAN>)$ switch (default setting: true).

$CMS_SET(#global.json.metaDataRendering, true)$

With the $CMS_SET(#global.json.metaDataRendering, true)$ setting (default setting), metadata for all objects is rendered. If no metadata is set, an empty element will be rendered.

$CMS_SET(#global.json.metaDataRendering, false)$

With the $CMS_SET(#global.json.metaDataRendering, false)$ setting, the JSON rendering of metadata is explicitly switched off.

metaInheritanceRendering: rendering inherited metadata (default setting: false)

The JSON rendering of inherited metadata can be activated or deactivated with the $CMS_SET(#global.json.metaInheritanceRendering, <BOOLEAN>)$ switch (default setting: false).

$CMS_SET(#global.json.metaInheritanceRendering, false)$

In the default setting $CMS_SET(#global.json.metaInheritanceRendering, false)$, only metadata that was defined on the object itself will be rendered. If no metadata is defined on the object, an empty value is rendered via the metaFormData attribute, even if the object has inherited metadata.

$CMS_SET(#global.json.metaInheritanceRendering, true)$

In the $CMS_SET(#global.json.metaInheritanceRendering, true)$ setting, the metadata that is rendered was not defined on the FirstSpirit object itself but on a hierarchically superordinate object. The inherited metadata is transferred to a JSON object structure. The values of the next higher object that are valid at that time, for which the corresponding metadata was defined, are thereby used (up to the root node of the store).

Important Changes to a pass-on node will not cause the inheriting nodes to be seen as changed. If the inheritance of the metadata is activated, a suitable mechanism must ensure that the data is updated accordingly.

Special characteristics for the rendering of inherited metadata

$CMS_SET(#global.json.metaInheritanceRendering, true)$: For the rendering of inherited metadata, the metadata of the hierarchically superordinate FirstSpirit objects will be analyzed. Starting from the source object, the process runs step by step through the entire parent chain until an object is found for which the metadata was defined. The analysis ends at the root node of the store (inclusively).

The following applies: If the input component that contains the metadata is not set in the metadata form on a FirstSpirit object, the value of the next higher FirstSpirit object will be analyzed. An input component is not set when the instruction isSet() renders the value false, which means that an object is not available in the current context. This state is reached when an input component was never set or an input component that has been set is overwritten with NULL, e.g., via a script (see example: “Switch input component to 'not set'”).

The simple deletion of a value in the input component is insufficient. In this case, the input component is empty (isEmpty() == true), but remains set (isSet() == true) (see API Documentation, Interface FormField, method isEmpty()).


JSON rendering of inherited metadata

"fsType": "PageRef",
"name": "pt_metadata_selective_1",
"displayName": "pt_metadata_selective",
"identifier": "15ff7b8d-9059-4721-b92b-e697e153fc85",
"uid": "pt_metadata_selective_1",
"uidType": "SITESTORE_LEAF",
"metaDataIsInherited": true,
"metaFormData": {
"meta_field1": {
"fsType": "CMS_INPUT_TEXT",
"name": "meta_field1",
"identifier": "meta_field1",
"value": null,
"valueSchema": {
"type": "null"
"meta_field2": {
"fsType": "CMS_INPUT_TEXT",
"name": "meta_field2",
"identifier": "meta_field2",
"value": "value_field2_set",
"valueSchema": {
"type": "string"
"meta_field3": {
"fsType": "CMS_INPUT_DATE",
"name": "meta_field3",
"identifier": "meta_field3",
"value": null,
"valueSchema": {
"type": "null"

Switch input component to 'not set'

FS_BUTTON input component:

<FS_BUTTON name="meta_field1" noBreak="yes" onClick="script:delete_meta_data">
<LANGINFO lang="*" label="Delete meta data"/>
<LANGINFO lang="DE" label="Metadaten entfernen"/>
<PARAM name="meta_data">#field.meta_field1</PARAM>

Script (“delete_meta_data”):

import de.espirit.firstspirit.forms.FormField;
if (meta_data instanceof FormField) {

© 2005 - 2023 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.12 | Data privacy