HCMS schema - Asset Reference Features

The HCMS allows to access assets that are referenced in an asset feature.

Introduction

Reference features are features with the value type asset or asset_key_ref. The value type can either be hinted with the property "cs:feature.value_type" in the schema or is already defined for existing features.

There are several possible ways to map reference features to/from JSON documents that can be selected in the schema with the optional property "cs:feature.$ref_type", defaulting to the actually stored value. This means that the asset id is returned for value type asset and the resource key for asset_key_ref if no particular $ref_type is provided. Please note that asset references cannot be mapped as inline.

Reference by Asset id

Basic type of mapping: JSON document contains the asset id (feature censhare:asset.id) of the referenced asset. It can be mapped as integer, number or string. Note that the import can fail if the string does not contain proper integer value.

Mapping as a Single Value

The schema below shows the correct mapping of an asset reference feature to an integer property.

{
  "type": "object",
  "properties": {
    "perm-groups": {
      "minValue": 0,
      "maxValue": 9007199254740991,
      "cs:feature.key": "censhare:module.oc.permission.group-ref",
      "type": "integer"
    }
  }
}

Example entity:

{
  "perm-groups": 51706
}

Multi-value Features as Array

The schema below shows the correct mapping of an multi-value asset reference feature to an array of integers.

{
    "type": "object",
    "properties": {
        "perm-groups": {
            "type": "array",
            "items": {
                "cs:feature.key": "censhare:module.oc.permission.group-ref",
                "type": "integer",
                "minValue": 0,
                "maxValue": 9007199254740991
            }
        }
    }
}

Example entity:

{
  "perm-groups": [
    51706,
    51707
  ]
}

id as String Value

The schema below shows the correct mapping of an asset reference feature to a string property.

{
  "type": "object",
  "properties": {
    "perm-groups": {
      "type": "array",
      "items": {
        "cs:feature.key": "censhare:module.oc.permission.group-ref",
        "type": "string"
      }
    }
  }
}

Example entity:

{
  "perm-groups": [
    "51706",
    "51707"
  ]
}

Reference by id_extern

In censhare environments it is common practice to store the external primary key prefixed with a source system identifier in the string typed feature censhare:asset.id_extern when importing data into assets. If the ref_type is set to id_extern the reference is represented by the censhare:asset.id_extern feature instead of the censhare primary key, also known as asset id.

The schema below shows the mapping:

{
  "type": "object",
  "properties": {
    "workspace": {
      "cs:feature.value_type": "asset",
      "cs:feature.$ref_type": "id_extern",
      "type": "string"
    }
  }
}

Example entity:

{
  "workspace": "workspace:13136"
}

The same entity can be also be mapped to number value, suppressing the prefix "workspace:" in the JSON representation:

{
  "id": 51728
}

by using cs:feature.$ref_prefix:

{
  "type": "object",
  "properties": {
    "workspace": {
      "cs:feature.value_type": "asset",
      "cs:feature.$ref_prefix": "workspace:",
      "cs:feature.$ref_type": "id_extern",
      "type": "integer"
    }
  }
}

Reference by Asset Key Reference Feature

Example schema:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "cs:feature.value_type": "asset_key_ref",
      "cs:feature.$ref_type": "asset_key"
    }
  }
}

Example entity:

{
  "city": "censhare:city.london"
}

The property "cs:feature.$ref_type" defaults to asset_key, therefore the reference schema can be simplified:

{
 "type": "object",
  "properties": {
    "city": {
      "cs:feature.value_type": "asset_key_ref",
      "type": "string"
    }
  }
}

This mapping is not the only possible one, all options available for asset features are available for asset_key_ref too. For example, the mapping above can be modified to use asset ID as external value, despite using key reference internally:

{
  "type": "object",
    "properties": {
      "city": {
        "cs:feature.value_type": "asset_key_ref",
        "cs:feature.$ref_type": "asset_id",
        "type": "integer"
      }
  }
}

and the entity shown above now contains just two integers:

{
  "city": 10007
}

Representation as Links

Asset references can also be represented as URLs referencing the target assets as entities in the Headless CMS REST API by setting the $ref_type to link.

{
    "type": "object",
    "properties": {
        "perm-groups": {
            "type": "array",
            "items": {
                "cs:feature.key": "censhare:module.oc.permission.group-ref",
                "cs:feature.$ref_type": "link",
                "type": "string"
            }
        }
    }
}

Example entity:

{
  "perm-groups": [
    "http://localhost:8080/hcms/v1.0/entity/group/51706",
    "http://localhost:8080/hcms/v1.0/entity/group/51707"
  ]
}

Master File URL

Besides the $ref_type link, there is also content_link, which provides a read only URL to the first master storage items binary data of the referenced asset. The value is considered missing if the target asset has no storage item.

{
    "type": "object",
    "properties": {
        "perm-groups": {
            "type": "array",
            "items": {
                "cs:feature.key": "censhare:module.oc.permission.group-ref",
                "cs:feature.$ref_type": "content_link",
                "type": "string"
            }
        }
    }
}

Example entity:

{
  "perm-groups": [
    "http://localhost:8080/hcms/v1.0/entity/group/storage/MDA2ODgyNS8xOC9wcmV2aWV3",
    "http://localhost:8080/hcms/v1.0/entity/group/storage/Njg4MjUvMjcvdGh1bWJuYWls"
  ]
}