In custom schemas, you can map asset references as JSON object.

Introduction

In censhare, asset references are configured and stored as asset features. In CI HUB JSON schemas, asset references are configured as properties. Depending on the number of possible referenced assets, the property is configured as single value or as an array. If you are not familiar with asset references in the censhare data model, see Asset relationships.  

Single-value references

In a single-value reference, only one target asset can be referenced in the source asset in a given reference type. These references are configured as single-value asset features. To map a single-value reference, configure the JSON object as follows:

"color": { 
  "cs:feature.key": "censhare:content.color",
  "cs:feature.$value_property": "color",
  "cs:feature.$ref_type": "link",
  "type": string
}
Remarks

(1) The cs:feature.$key defines the asset reference feature. You can look up available relation types in the censhare Admin Client in Masterdata/Features. Make sure that the referenced assets are available as entities at in one of schemas. Otherwise, the value of the property is NULL.

(2) The cs:feature.$value_property defines the direction of the relation. Values can be child  or parent.

(3) The cs:feature.$ref_type defines how the related asset is referenced. In CI HUB schemas, the value must be link. The link points to the target asset. For example: "color": "<HOST>/hcms/v2.1/entity/person/14910".

(4) The type defines the data type of the property. The value must be string.


Multiple-value references

In a multiple-value reference, multiple target assets can be referenced in the source asset in a given reference type. These references are configured as multi-value asset features. To map a multiple-value reference, configure the JSON object as follows:

"colors": {
  "type": "array",
  "items": { 
    "cs:feature.key": "censhare:content.color",
    "cs:feature.$value_property": "color",
    "cs:feature.$ref_type": "link",
    "type": string
  }
}
Remarks

(1) The type defines the data type of the JSON property. The value must be array.

(2) Each item represents a referenced asset. All items are grouped into the array. The further mapping is done inside the item.

(3) The cs:feature.key defines the relation type. You can look up available relation types in the censhare Admin Client in Masterdata/Features. Make sure that the target assets are available as entities at in one of schemas. Otherwise, the value of the property is NULL.

(4) The cs:feature.$value_property defines the direction of the relation. Values can be child  or parent.

(5) The cs:feature.$ref_type defines how the related asset is referenced. In CI HUB schemas, the value must be link. The link points to the target asset. For example: "author": "<HOST>/hcms/v2.1/entity/feature-value/14910".

(6) The type defines the data type of an item of the array. The value must be string.

Handle NULL values

If a referenced asset is not assigned to an entity, the response gives back a NULL value. This causes the CI HUB server to throw an error. You can avoid this by explicitly allowing NULL values. Configure the property as follows (example with multiple-value reference/array):

"colors": {
  "type": "array",
  "items": {
    "oneOf": [
      {
        "type": "string"
      },
      {
        "type": "null"
      }
    ],
    "cs:feature.key": "censhare:content.color",
     "cs:feature.$ref_type": "link",
     "type": "string"
  }
},
Remarks

(1) The oneOf field defines the possible values of the property.

(2) This option defines that the value can be a string - in this case a URL.

(3) This option defines that the value can be NULL. The CI HUB server recognizes NULL as an allowed value and does not throw an error.

Map referenced assets into source asset

The mappings in the above examples retrieve the URL of the referenced assets and link them from the source asset. If users click the linked asset, the CI HUB server sends a new REST call to the censhare Server to retrieve the properties of the referenced asset.

In many use cases, the referenced assets represents a simple value (for example: a color or a keyword). In this case, you can map the desired properties from the referenced asset into the source asset. The referenced asset is is then returned as a serialized entity together with the source asset.

This reduces the number of REST calls. Also, is not necessary to define an entity schema for the referenced asset type. The mapping of the features from the referenced asset is done in the source entity schema, inside the schema definition of the reference property.

The following for example maps the name and id of referenced keywords into the source entity:

"keywords": {
  "type": "array",
  "items": {
    "cs:relation.$selection_key": [
       "id"
    ],
    "cs:asset.type": "module.keyword.",
    "cs:feature.value_type": "ASSET",
    "cs:feature.$ref_type": "INLINE",
    "cs:feature.key": "censhare:keyword-ref",
    "type": "object",
    "properties": {
      "name": {
        "cs:feature.key": "censhare:asset.name",
        "type": "string"
      },
      "id": {
        "cs:feature.key": "censhare:asset.id",
        "type": "integer"
      }
    }
  }
}
Remarks

(1) Instead of the link reference type, INLINE is used here.

(2) The module.keyword asset type maps keyword assets.

(3) The feature key censhare:keyword-ref stores referenced keyword assets.

(4) The type object must be used to define the property as a new entity.

(5) Inside the properties, the desired features from the referenced asset are mapped.