docs: modify re meta deltas (#491)

Author: bkp7

gitbook-docs/data_model.md

@@ -8,7 +8,7 @@ transmitted as UTF-8 JSON.
 ## Full Format
 
 The full format is conceptually the simplest representation of data in Signal K. It contains all of the data from a
-Signal K node, which in the case of a Signal K server could me many hundreds of data points.
+Signal K node, which in the case of a Signal K server could be many hundreds of data points.
 
 [>]: # (mdpInsert ```json fsnip ../samples/full/docs-data_model.json)
 ```json
@@ -263,32 +263,42 @@ the value should be merged to the full model mounted where the delta‘s context
   ]
 }
 ```
+[<]: #
 ## Delta Format For Metadata
 
-Metadata can also be specified via a delta. The delta is very similiar to the `values` deltas above, but instead of having `values` key, it will have a `meta` key. Note that a client could multiple meta deltas for any given path from different sources, so the client merge the meta information.
+Metadata can also be updated via a delta within the `meta` key.
+
+Since meta data is not often updated it is only sent when there has been a change. See [Subscription Protocol](subscription_protocol.md) for details.
 
+[>]: # (mdpInsert ```json fsnip ../samples/delta/docs-data_model_meta_deltas.json --prettify 2 20)
 ```json
 {
   "context": "vessels.urn:mrn:imo:mmsi:234567890",
   "updates": [
     {
-      "source": {...},
       "timestamp": "2014-08-15T19:02:31.507Z",
-      "meta":[
+      "meta": [
         {
           "path": "environment.wind.speedApparent",
-          "value":
-            {
-              "units": "m/s",
-              "description": "Apparent wind speed"
-            }
+          "value": {
+            "units": "m/s",
+            "description": "Apparent wind speed",
+            "displayName": "Apparent Wind Speed",
+            "shortName": "AWS",
+            "zones": [
+              {
+                "upper": 15.4333,
+                "state": "warn",
+                "message": "high wind speed"
+              }
+            ]
+          }
         }
       ]
     }
   ]
 }
 ```
-
 [<]: #
 ## Data Quality
 

gitbook-docs/subscription_protocol.md

@@ -86,7 +86,7 @@ The following are optional, included above only for example as it uses defaults
 
 * `period=[millisecs]` becomes the transmission rate, e.g. every `period/1000` seconds. Default: 1000
 * `format=[delta|full]` specifies delta or full format. Default: delta
-* `policy=[instant|ideal|fixed]`. Default: ideal
+* `policy=[instant|ideal|fixed]`. Default: ideal. (does not apply to meta - see below)
  * `instant` means send all changes as fast as they are received, but no faster than `minPeriod`. With this policy the
      client has an immediate copy of the current state of the server.
  * `ideal` means use `instant` policy, but if no changes are received before `period`, then resend the last known
@@ -101,6 +101,13 @@ duplication as it prefers on a per connection basis. At the same time it is good
 connections necessary, for instance one WebSocket connection shared between an instrument panel with many gauges,
 rather then one WebSocket connection per gauge.
 
+## Meta data
+Meta is updated via the `meta` section within the delta message. As meta changes infrequently it is only sent when it has changed.
+
+Servers implementing the subscription model (ie. using deltas) SHOULD implement meta deltas. Where meta deltas are implemented, servers MUST only ever send full copies of the meta for a leaf, ie. they MUST NEVER send a partial meta.
+
+Upon receiving a new subscription a server MUST send the meta for each leaf subscribed to; this MAY be in the same JSON document as the values, or in a separate one prior to sending values for that leaf or leaves. Subsequently the server MUST resend the full meta for a leaf each time any item in that meta is changed. This is equivalent to the `instant` subscription for values. Therefore meta is never subscribed on an `ideal` or `fixed` policy, irrespective of the policy requested by the consumer (which applies to values only).
+
 ## Multiple value handling in subscriptions
 
 A subscription to a key is for all the updates to that key. If there are multiple sources generating data for that key

samples/delta/docs-data_model_meta_deltas.json

@@ -0,0 +1,25 @@
+{
+  "context": "vessels.urn:mrn:imo:mmsi:234567890",
+  "updates": [
+    {
+      "timestamp": "2014-08-15T19:02:31.507Z",
+      "meta": [
+        {
+          "path": "environment.wind.speedApparent",
+          "value": {
+            "units": "m/s",
+            "description": "Apparent wind speed",
+            "displayName": "Apparent Wind Speed",
+            "shortName": "AWS",
+            "zones": [{
+              "upper": 15.4333,
+              "state": "warn",
+              "message": "high wind speed"
+            }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}