HCMS Schema - Asset Feature Basics

Explains the basics of accessing asset features via the Headless CMS as part of HCMS schemas.

Feature mapping is the default storage for any schema without censhare specific meta data (also see: Basic Mapping)

Common Options

"cs:feature.key": String value containing the feature id
- Specifies the feature to be used to store the property, either used to map properties to existing features or to manually specify the key of the feature to be created
- The value can actually contain several feature keys delimited by slash (/) which describes several levels of nested features, with the last one being the one with value
- Optional By default a new feature is automatically created
"cs:feature.index": String value containing feature id that is used for searching
- When present, different feature is used for value (serialization to JSON, deserialization from JSON) and for searching.
- This is the only way to use calculated features, because their value cannot be directly read or written, so they cannot be used as "cs:feature.key".
"cs:feature.value_type": Direct specification of the feature value type
- The default mapping for the JSON types is:
  - string: Text (String)
  - integer: Integer (Long)
  - number: Floating-point number (Double)
  - boolean: Boolean
  - string/integer with enum/const values: Value list (String)
  - object = None
- Possible values are:
  - novalue: None, applicable JSON types: object
  - hierarchical: Hierarchical value list (String), applicable JSON types: string
  - enumeration: Value list (String), applicable JSON types: string, integer
  - integer: Integer (Long), applicable JSON types: integer, 'number'
  - string: Text (String), applicable JSON types: string
  - timestamp: Date/time, applicable JSON types: string
  - boolean: Boolean, applicable JSON types: boolean
  - double: Floating-point number (Double), applicable JSON types: number
  - asset: Asset reference, see Asset references
  - xml: XML, not supported
  - : Floating-point number pair (Double),
  - date: Date, applicable JSON types: string, integer
  - time: Time, applicable JSON types: string, integer
  - year: Year, applicable JSON types: string, integer
  - year_month: Year/month, applicable JSON types: string, integer
  - month: Month, applicable JSON types: string, integer
  - day: Day, applicable JSON types: string, integer
  - duration: not supported
  - asset_key: Asset resource key applicable JSON types: string
  - asset_key_ref: Asset key reference, see Asset references
  - integer_pair, timestamp_pair, date_pair, double_pair, time_pair, year_pair, year_month_pair, month_pair, monath_day_pair, day_pair: must be mapped using the cs:feature.$value_property and cs:feature.$value2_property properties of the same type as their non-pair counterpart inside an object
- (Optional) If not provided the default mapping is applied
"cs:feature.$enum_values": array of possible values
- Only to be used with value type "enum"/"const"
- It can be used to automatically create new feature_value records in censhare
- It contains an array of objects; each item describes one possible value
  - "value_key": The value in JSON, must be present in "enum" array
  - "name": Name of the value, used by censhare clients
  - "description": Description of the value, as used by censhare clients
  - "sorting": Integer number used to define order in censhare clients user interface
"cs:feature.$resolve_enum":: Values are represented by their display names, instead of keys.
- Only for features of type ENUMERATION or HIERARCHICAL, ignored for other ones.
- Value is either true (to use requested locale) or the language (or locale) that will be used to resolve the display name.
  - In cases where value don't have display name in that language, default display name is used as a fallback.
  - Note that the behavior of true value changed in version 3.0
- Note that unlike keys, names are not guaranteed to be unique. If several feature values have the same name, this name cannot be used in import JSON - any attempt to create or update entity would result in error (invalid value).
"cs:feature.$ref_prefix": Just like cs:feature.$value_prefix, but for references; obsolete, replaced by cs:feature.$value_transformation.
"cs:feature.$value_prefix": Prefix that is prepended to feature value.
- Obsolete, replaced by more generic "cs:feature.$value_transformation". It still works and is equal to generic transformation with just "internal_prefix".
"cs:feature.$value_transformation": Transformation of string value by adding and removing strings at beginning/end.
- Object with four possible properties; none of them is mandatory, missing property is the same as empty string:
  - internal_prefix, internal_suffix: prefix/suffix always stored as part of the internal values stored in feature; removed on export, added on import,
  - external_prefix, external_suffix: prefix/suffix always presented in the external values in the JSON document; added on export, removed on import
- JSON mapped value is usually string, but it can be integer or number.
  - This allows numeric values to be stored in string features with some constant prefix.
- Feature value type is usually STRING, HIERARCHICAL or ENUMERATION, but it can be any scalar type that can be transformed to/from string.
  - This includes asset references and asset key references.
  - Note that in case of non-string values, the full "internal" value must be valid string representation of that value.
"cs:feature.$value_default": literal JSON value to be output if no actual asset feature exists
- Must conform to the schema
- It has no effect on create and update (POST and PUT)
- It is useful to provide default value of newly added property
"cs:feature.$unit_set": id of the unit set to associate with the feature when creating it
"cs:feature.$faceted": Boolean value specifying if faceted search is allowed for this property
- Default is false
- Pair values and inlined references does not allow faceted search and setting this option to true is an error.
- Properties that are not mapped to censhare features with deactivated index or altresults will not yield valid alt results.
- By default properties mapped to the features censhare:approved-date and censhare:uuid can not be used.
cs:feature.$ref_schema: Array of known schemas that the referred asset belongs to.
- Only for asset reference features (asset, asset_key_ref), ignored for all other types.
- Optional, but empty array is not allowed.
- Each array item is string with schema name. These names are not validated in any way, unknown schema is always accepted and silently ignored (presumably, it will be created in future).
  - Note that it is possible to form dependency cycle.
- This list is not used for any validation or input and output data.
- Used in graphql schema to replace reference value with target entity value (as long as a least one specified schema exists).
- When combined with "cs:feature.$ref_type": "link", this list is used to select the best schema (if any of specified schemas matches asset type), overriding the default cs:$priority mechanism.

Primary Key / Asset id

All entities must have a property containing the id of the asset (primary key) used to store the entity which is also used to identify the entity in the Headless CMS. Although the property name can be defined at one's own discretion, the type needs to be correct and the mapping needs to be set to the feature censhare:asset.id:

JSON

{
        "id": {
            "cs:feature.key": "censhare:asset.id",
            "type": "integer",
            "minValue": 0,
            "maxValue": 9007199254740991
        }
}

The mapping of asset IDs and other non user modifiable asset attributes (e.g. version) are read only and ignored on import.

Multi-value Features

Multi-value features are defined as JSON "type":"array". The feature itself is defined by "items", including cs:feature. properties.

JSON

{
  "type": "object",
  "keywords": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

Mapping JSON Objects to Features

A JSON object can be also mapped to an asset feature.

"cs:feature.$value_property": Name of property that contains the asset feature value
"cs:feature.$value2_property": Name of property that contains the second asset feature value for pair feature value types
"cs:feature.$locale_property": Name of property that contains the asset feature locale (must be of JSON type string)
"cs:feature.$sorting_property": Name of property that contains the asset feature sorting attribute (must be of JSON type integer)
"cs:feature.$unit_property": Name of the property that contains the asset feature unit (must be of JSON type string)
"cs:feature.$relevance_property": Name of the property that contains the asset feature relevance percentage (must be of JSON type number or string)

Example

JSON

{
  "type": "array",
  "items": {
    "type": "object",
    "cs:feature.key": "my:double_pair_localized_with_unit",
    "cs:feature.value_type": "double_pair",
    "cs:feature.$unit_set": "censhare:currency",
    "cs:feature.$value_property": "value",
    "cs:feature.$value2_property": "value2",
    "cs:feature.$locale_property": "language",
    "cs:feature.$sorting_property": "sorting",
    "cs:feature.$unit_property": "unit",    
    "properties": {
      "value": {
        "type": "number"      
      },
      "value2": {
        "type": "number"      
      },
      "language": {
        "type": "string"
      },
      "sorting": {
        "type": "integer"
      },
      "unit": {
        "type": "string"
      }
    }
  }
}

Real-world example of feature with relevance percentage:

JSON

{
        "keywords": {
            "type": "array",
            "items": {
                "type": "object",
                "cs:graphql.type": "keyword",
                "cs:feature.$ref_type": "link",
                "cs:feature.key": "censhare:keyword-ref",
                "cs:feature.$value_property": "keyword",
                "cs:feature.$relevance_property": "relevance",
                "required": ["keyword"],
                "properties": {
                    "keyword": {
                        "type": "string"
                    },
                    "relevance": {
                        "type": "number"
                    }
                }
            }
        }
}

Note: pair features (test pair, number pair, date pair, etc.) must be mapped as JSON object with both "cs:feature.$value_property" and "cs:feature.$value2_property" present.

Localized Features

censhare Features can be set to to support locales. If locales are present, the feature can be present for each configured locale with different values on the same asset.
As a common pattern, these localized features are mapped to properties with the locale as property name, as illustrated in the example below.

JSON

{
    "localized": {
        "en": "colour",
        "en_US": "color",
        "de": "farbe",
        "": "color (default text with no language)"
    }
}

In the JSON schema, this is defined as "object" with "patternProperties" instead of "properties" and special marker "cs:feature.$localized": true. The values of the properties can be anything that is allowed for simple (or even complex) features.

JSON

{
    "type": "object",
    "properties": {
        "localized": {
            "type": "object",
            "cs:feature.$localized": true,
            "additionalProperties": false,
            "patternProperties": {
                "^[a-z]{2}(_[A-Z]+)?$|^$": {
                    "cs:feature.key": "censhare:name",
                    "type": "string"
                }
            }
        }
    }
}

An empty string is a special value: it means "no locale" and usually represents "default". It is actually a placeholder for the internal value null (which is not allowed as a property key).
Only locales that are configured on the censhare server are admissible. Any key that is not part of this configuration causes the import (create/update) to fail. The error message contains the offending value and also a list of possible values. New languages can be added using the schema endpoint.
If multiple values are required per locale, the feature must be mapped using an array and "cs:feature.$locale_property".