In custom schemas, you can map asset features as properties into your entities.

Introduction

censhare asset features are mapped to an entity schema as a JSON object inside the properties. A feature mapping requires at least a feature key and type (data type). Optionally, you can add restrictions and formatting definitions.

Many censhare features can have multiple values, or have child features. For example, the contact feature in censhare does not store any value itself. Instead, the respective values are stored in the child features address, phone number, email, etc. The address itself has the child features street, house number, city, ZIP code, etc. These require a special mapping.

Single-value features

The following example shows the minimum configuration of an asset feature mapping:

"dateModified": {
  "cs:feature.key": "censhare:asset.modified_date",
  "type": "string"
}
Remarks

(1) In the cs:feature.key the feature key must be set. You can look up feature keys in the censhare Admin Client  in the Masterdata/Features.

(2) The format value is used for validation when uploading data. If the validation fails, the data are rejected. The data are also validated when downloaded. 

(3) The type defines the data type. Allowed values are string, integer, array or object.

Advanced configuration options

To only allow uploaded integer values within a defined range, you can provide a minValue and a maxValue:

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

To validate the format of uploaded data, you can provide a format:

"dateModified": {
  "cs:feature.key": "censhare:asset.modified_date",
  "format": "date-time",
  "type": "string"
}

Format definitions are part of the JSON schema standard. The format defines allowed data format of the JSON object value. It is not checked if the format conforms to feature configuration in the censhare master data. Make sure that your schema definitions match the the format in the censhare master data. Otherwise, values that are retrieved from the censhare Server are not passed via the REST API.

To allow a faceted search for an attribute, add the cs:feature.$faceted:

"name": {
  "cs:feature.$faceted": true,
  "cs:feature.key": "censhare:asset.name",
  "type": "string"
}

Multi-value features

Multi-value asset feature can store multiple values for one feature. The mapping for multi-value features must be defined with the array type. The items of an array represent the values. See the following example:

"languages": {
  "type": "array",
  "items": {
    "cs:feature.key": "censhare:usage-language",
    "type": "string"
  }
}
Remarks

(1) The type must be set to array.

(2) Inside the items, the feature key, type and optional definitions are added.


The items can also be defined as objects and hold more complex structures. For more information, see the following section.

Features with child-features

In censhare, features with child features are used to build hierarchical feature sets. To map a feature set to a property, you must use the object type. Each object represents a child feature. You can build nested properties over multiple hierarchical levels.

In feature sets, there are two types of root features:

Root feature without a value

A root feature without a value does not store any value itself. It works as a container for the child features and their values. The following example shows the configuration of the contact (IPTC)  feature with the ZIP code  and city  child features. By definition, the contact (IPTC) feature has no value.

"contact": {
  "cs:feature.key": "censhare:iptc.contact",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "zipCode": {
      "cs:feature.key": "censhare:address.zip-code",
      "type": "string"
    },
    "city": {
      "cs:feature.key": "censhare:address.city",
      "type": "string"
    }
  }
}
Remarks

(1) The censhare:iptc.contact feature is defined as root feature.

(2) The additionalProperties must be set to false if the root feature itself does not store any value. This prevents that a client can send unmapped properties to the REST API. Otherwise, these unmapped properties pass the validation, but are ignored later without further notice. 

(3) The type must be object. This means that the property stores another entity or multiple entities.

(4) The child features are configured as properties. Inside the properties, the configuration is identical to the single-value feature configuration. 

Root feature with a value

A root feature with a value stores itself a value. A use case for this type are feature sets that can exist multiple times. The following example shows the configuration of the address  feature. The first-level child feature address.type stores a value, for example: address: private and address: work. The second-level child features store the address parts, for example: ZIP code and city.  The configuration for the adress.type feature contains a mapping for its own feature value in the properties section.

"address": {
			"type": "array",
			"items": {
				"cs:feature.$value_property": "type",
				"cs:feature.key": "censhare:address/censhare:address.type",
				"additionalProperties": false,
				"type": "object",
				"properties": {
					"type": {
						"type": "string"
					},
					"zipCode": {
						"cs:feature.key": "censhare:address.zip-code",
						"type": "string"
					},
					"city": {
						"cs:feature.key": "censhare:address.city",
						"type": "string"
					}
				}
			}
		}
Remarks

(1) The address feature is defined as root feature. The feature can have multiple values. Therefore, it is defined as array. 

(2) The items of the address feature are the defined as address.type child features. 

(3) The second level of this feature hierarchy is skipped. Therefore, the  cs:feature.key is set to  censhare:address/censhare:address.type. This value is used in the third level of the hierarchy.

(4) The address.type feature stores a value itself to indicate the address type when multiple addresses exist. The value of the feature key censhare:address/censhare:address.type is used as unique name of the object and mapped into type of the properties section.

(5) Inside the properties object that represents an address type, the third level child features ZIP code and city are configured.

Complex feature sets

To map a complex hierarchical feature, you can add multiple objects the properties section of a JSON schema. The following example extends the example from the previous section with object:

"contact": {
  "cs:feature.key": "censhare:iptc.contact",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "comOtherType": {
      "cs:feature.$value_property": "type",
      "cs:feature.key": "censhare:address.com-other-type",
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "value": {
          "cs:feature.key": "censhare:address.uri-generic",
          "type": "string"
        }
      }
    },
    "zipCode": {
      "cs:feature.key": "censhare:address.zip-code",
      "type": "string"
    },
    "city": {
      "cs:feature.key": "censhare:address.city",
      "type": "string"
    }
  }
}
Remarks

(1) The comOtherType property is added to the contact and mapped to the censhare:address.com-other-type feature. 

(2) The censhare:address.com-other-type feature value stores a social media profile (a URL). For example: LinkedIn, Twitter, Facebook etc.

(3) The censhare:address.uri-generic child feature stores the URL of the social media profile.

A complex feature set can also contain an array. For example, the language area can store multiple language values with a contact:

"contact": {
  "cs:feature.key": "censhare:iptc.contact",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "comOtherType": {
      "cs:feature.$value_property": "type",
      "cs:feature.key": "censhare:address.com-other-type",
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "value": {
          "cs:feature.key": "censhare:address.uri-generic",
          "type": "string"
        }
      }
    },
    "zipCode": {
      "cs:feature.key": "censhare:address.zip-code",
      "type": "string"
    },
    "city": {
      "cs:feature.key": "censhare:address.city",
      "type": "string"
    },
    "languages": {
      "type": "array",
      "items": {
        "cs:feature.key": "censhare:usage-language",
        "type": "string"
      }
    }
  }
}
Remarks

(1) The languages property is added to the contact and mapped to the censhare:usage-language feature. 

(2) The censhare:usage-language feature is mapped as an array that can store multiple language values.