Documentation
Documentation
Labels

1Intention

The intention behind the label concept is to extend dynamically certain data models. The properties of those models differ depending on the context in which they are created or used. The label infrastructure is only relevant when the information needs to be processed by an third party application or if the additional information has to be shown on a user interface of a third party application. If this is not the case labels are typically not relevant.

2Label Descriptors

Since we extend the data models dynamically we have to describe the data we return. For each label we return also the label descriptor. The descriptor provides the semantic of the data item. It provides also a description and a name which can be understood by a human user.

Additionally the descriptor contains a type. The type indicates of which type (string, integer etc.) the value of the label is.

3Resolve the Descriptions Via Webservice API

The label descriptors can be fetched over the web service API by using the Label Descriptor Service. A label consists of a value, a type and a descriptor. The descriptor id can be resolved over the web service API to get the additional information.

4Label Example

An object with labels may look like the following JSON:

{
	"id": 123141,
	"regularProperty": "A regular property which is not dynamically added.",
	"labels": [
		{
			"content": "Sample Label Value",
			"contentAsString": "Sample Label Value",
			"descriptor": 11001231,
			"displayName": "ID: 58",
			"id":58,
			"version":0
		}
	]
}

In this example we have a label with the value Sample Label Value. The details about the label can be found by querying for the label descriptor. The descriptor will provide the the following data:

{
	"id": 11001231,
	"name": "Sample Label",
	"category": "HUMAN",
	"description":{
		"en-US":"This field will contain a human understandable description of the label in English."
	},
	"type": {
		"description":{
			"en-US":"The string label type indicates that the label value is of the type string."
		},
		"id":1455545848917,
		"name":{
			"en-US":"String"
		}
	},
	...
}

As the example shows the descriptor provides a description, a name, a type and other properties. The type will be used for other descriptors as well. To use this infrastructure properly for each label type a handler should be implemented. In this way a generic implementation to handle labels can be realized. In case only some particular label descriptors are of interest it may also make sense to handle only those labels.

5Label Type: Static Value

The static value label type is special because the label contains actually an ID of another object. The object can be resolved via the REST API for static values. Typically such values represents objects which do not change. They are comparable to Enums known in some programming languages.