Issue #785 add documentation for the Ditto metadata feature (#680).

Corrections in basic-metadata.md and added changes to ditto-api-2.yml-Swagger Doc.

Signed-off-by: julian <[email protected]>

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -403,6 +403,7 @@ paths:
         - $ref: '#/components/parameters/thingIdPathParam'
         - $ref: '#/components/parameters/ifMatchHeaderParam'
         - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
+        - $ref: '#/components/parameters/putMetadataParam'
         - $ref: '#/components/parameters/requestedAcksParam'
         - $ref: '#/components/parameters/timeoutParam'
         - $ref: '#/components/parameters/responseRequiredParam'
@@ -4664,6 +4665,10 @@ components:
           description: |-
             _(read-only)_ The modified timestamp of the Thing in ISO-8601 UTC format. The timestamp is set on each
             modification of a Thing. This field is not returned by default but must be selected explicitly.
+        _metadata:
+          type: string
+          description: |-
+            _(read-only)_ The Metadata of the Thing will be included in the Thing. This field is not returned by default but must be selected explicitly.
     Policy:
       type: object
       description: policy consisting of policy entries
@@ -4858,6 +4863,14 @@ components:
       required: false
       schema:
         type: string
+    putMetadataParam:
+      name: Put-Metadata
+      in: header
+      description:  >-
+        The `put-metadata` header, which sets Metadata information in the Thing.
+      required: false
+      schema:
+        type: string
     featureIdPathPathParam:
       name: featureId
       in: path

documentation/src/main/resources/pages/ditto/basic-metadata.md

@@ -0,0 +1,82 @@
+---
+title: Metadata Support
+keywords: metadata, things
+tags: [model]
+permalink: basic-metadata.html
+---
+
+Besides [features](basic-feature.html) a Thing in Ditto is also able to store Metadata information. 
+These informations can be additional information for describing specific features or properties of the thing.
+A very simple example is the timestamp when the current value of the feature or property was set.
+
+Metadata can be manipulated by using the `metadata` header, see [here](protocol-specification.html#headers) for more information.
+
+## Predefined Metadata 
+
+Currently, there are no pre-defined Metadata keys.
+
+<!--
+Right now, the only fixed pre-defined Metadata key is `issuedAt`.
+
+### The `issuedAt` Metadata key
+ 
+The Metadata key `issuedAt` describes the timestamp when the current value of a feature property was _recorded_ (_not when it was set_).
+This means, that a client _can_ send this value by using the `metadata` header. If the client does not send
+this header the `issuedAt` field will be set by Ditto with the timestamp when the value was written.
+-->
+
+## Setting custom Metadata
+
+The only way to set arbitrary `Metadata` is by using the `put-metadata` header, see [here](protocol-specification.html#headers) for more information.
+The Format of the Json Array is 
+
+```
+[
+  {
+    "key":"/features/lamp/properties/color/r",
+    "value":{"issuedAt":someTimestamp,"issuedBy":{"name":"me","mail":"[email protected]"}}
+  },
+  {
+    "key":"*/foo",
+    "value": "bar"
+  },
+  ...
+]
+```
+
+where `key` describes the hierarchical position in the Thing where the metadata is placed and 
+`value` is a map of Metadata keys to their respective values.
+
+A special Syntax for the key is `*/{key}` which means that all affected Json Leafs of the Modify Operation will
+get the Metadata Key `{key}` with the given value. So if, for example, only the affected Json Leafes should 
+get the timestamp where the changed values were recorded, one would set the `metadata` header as shown in the
+following example: 
+
+```json
+[
+  {
+    "key":"*/timestamp",
+    "value": someTimestamp
+  }
+]
+```
+
+## Reading Metadata Information
+
+Currently, the only way to retrieve stored Metadata is by a full thing query, e.g. via the [HTTP API](http-api-doc.html).
+But, `get-metadata` has to be added to the queried fields together with `thingId,attributes,_metadata`.
+
+For example a `GET` request to `https://{ditto-instance}/api/2/things/{namespace}:{thing}?fields=thingId,attributes,_metadata`
+will yield the Metadata stored for the given Thing, in the following format:
+
+```json
+{
+    "thingId": ...,
+    "attributes": {
+        ...
+    },
+    "_metadata": {
+        ...
+    }
+}
+``` 

documentation/src/main/resources/pages/ditto/protocol-specification.md

@@ -78,6 +78,7 @@ There are some pre-defined headers, which have a special meaning for Ditto:
 | `requested-acks` | Defines which [acknowledgements](basic-acknowledgements.html) are requested for a command processed by Ditto. | `JsonArray` of `String` - default: `["twin-persisted"]` |
 | `timeout` | Defines how long the Ditto server should wait, e.g. applied when waiting for requested acknowledgements. | `String` - e.g.: `42s` or `250ms` or `1m` - default: `60s`|
 | `version` | Determines in which schema version the `payload` should be interpreted. | `Number` - currently: \[1,2\] |
+| `metadata` | Determines which metadata information is stored in the thing. | `JsonArray` of `String` - default: `` |
 
 Custom headers of messages through the [live channel](protocol-twinlive.html) are delivered verbatim. When naming 
 custom headers, it is best to attach a prefix specific to your application, that does not conflict with Ditto or
@@ -97,6 +98,8 @@ HTTP protocol, for example the prefix `ditto-*`.
 The interaction between the headers `response-required`, `requested-acks` and `timeout` is documented
 [here](basic-acknowledgements.html#interaction-between-headers).
 
+More information of the Metadata management of Ditto and predefined Metadata-Keys can be found [here](basic-metadata.html).
+
 ## Path
 
 Contains a JSON pointer of where to apply the [value](#value) of the protocol message.