Attribute Metadata

Apart from metadata elements to which Orion pays special attention (e.g. dateCreated, etc.), users can attach their own metadata to entity attributes. These metadata elements are processed by Orion in a transparent way: Orion simply stores them in the database at update time and retrieves them at query and notification time.

You can use any name for your custom metadata except for a few reserved names, used for special metadata that are interpreted by Orion:

• location, which is currently deprecated, but still supported
• The ones defined in "Builtin metadata" section in the NGSIv2 spec

Custom attribute metadata

For example, to create an entity Room1 with attribute "temperature", and associate metadata "accuracy" to "temperature":

curl localhost:1026/v2/entities -s -S --header 'Content-Type: application/json' \
    -d @- <<EOF
{
  "id": "Room1",
  "type": "Room",
  "temperature": {
    "value": 26.5,
    "type": "Float",
    "metadata": {
      "accuracy": {
        "value": 0.8,
        "type": "Float"
      }
    }
  }
}
EOF

At the moment NGSIv2 doesn't define an operation to update metadata regardless of the attribute value being updated or not. In addition, it doesn't define an operation to add metadata after attribute creation. In other words, the whole metadata array is updated along with attribute value and type in the PUT /v2/entities/{id}/attrs/{attrName} operation.

We can check that temperature includes the metadata:

curl localhost:1026/v2/entities/Room1 -s -S \
    --header 'Accept: application/json' | python -mjson.tool

which response is

{
    "id": "Room1",
    "temperature": {
        "metadata": {
            "accuracy": {
                "type": "Float",
                "value": 0.8
            }
        },
        "type": "Float",
        "value": 26.5
    },
    "type": "Room"
}

At the moment, NGSIv2 doesn't allow to delete individual metadata elements once introduced. However, you can delete all metadata updating the attribute with metadata set to {}.

Note that, from the point of view of subscriptions, changing the metadata of a given attribute is considered a change even though the attribute value itself hasn't changed.

Updating metadata

When an attribute is updated the following rules apply:

• Metadata included in the attribute update request not previously existing are added to the attribute
• Metadata included in the attribute update request previous existing are updated in the attribute
• Existing metadata not included in the request are not touched in the attribute (i.e. they keep the previous value).

For instance, let's consider an attribute temperature with metadata unit and avg which values are at the present moment:

• unit: "celsius"
• avg: 25.4

and Context Broker receives a request like this:

PUT /v2/entities/E/attrs/temperature
{
  "value": 26,
  "type": "Number",
  "metadata": {
    "avg": {
      "value": 25.6,
      "type": "Number"
    },
    "accuracy": {
      "value": 98.7,
      "type": "Number"
    }
  }
}

After processing the update, the metadata at the attribute temperature would be:

• unit: "celsius" (existing and not touched by the request)
• avg: 25.6 (existing but touched by the request)
• accuracy: 98.7 (metadata added by the request)

The rationale behind the "stikyness" of metadata in this default behaviour is described in more detail in this issue at Orion repository

overrideMetadata option

You can override the default behaviour using the overrideMetadata option. In that case, the metadata in the request replace the previously ones existing in the attribute. For instance, with the same initial situation than before, but adding the overrideMetadata option to the request:

PUT /v2/entities/E/attrs/temperature?options=overrideMetadata
{
  "value": 26,
  "type": "Number",
  "metadata": {
    "avg": {
      "value": 25.6,
      "type": "Number"
    },
    "accuracy": {
      "value": 98.7,
      "type": "Number"
    }
  }
}

After processing the update, the metadata at the attribute temperature would be:

• avg: 25.6 (existing but touched by the request)
• accuracy: 98.7 (metadata added by the request)

Note that unit metadata has been removed.

The overrideMetadata option can be use also to cleanup the metadata of a given attribute omitting the metadata field in the request (equivalently, using "metadata":{}), e.g.:

PUT /v2/entities/E/attrs/temperature?options=overrideMetadata
{
  "value": 26,
  "type": "Number"
}

Note overrideMetadata option is ignored in the update attribute value operation (e.g. PUT /v2/entities/E/attrs/temperature/value) as in that case the operation semantics makes explicit that only the value is going to be updated (leaving type and metadata attribute fields untouched).