diff --git a/schemas/definitions.json b/schemas/definitions.json
index 2edfd1dac..91a5746c9 100644
--- a/schemas/definitions.json
+++ b/schemas/definitions.json
@@ -13,47 +13,56 @@
     },
     "source": {
       "type": "object",
-      "description": "Source of data. An object containing at least the properties defined in 'properties', but can contain anything beyond that.",
+      "description": "Source of data, a record of where the data was received from. An object containing at least the properties defined in 'properties', but can contain anything beyond that.",
       "required": [
         "label",
         "type"
       ],
       "properties": {
         "label": {
-          "type": "string"
+          "type": "string",
+          "description":"A label to identify the source bus, eg serial-COM1, eth-local,etc . Can be anything but should follow a predicatable format",
+          "example": "N2K-1"
         },
         "type": {
           "type": "string",
-          "default": "NMEA2000"
+          "description":"A human name to identify the type. NMEA0183, NMEA2000, signalk",
+          "default": "NMEA2000",
+          "example": "NMEA2000"
         },
         "src": {
           "type": "string",
-          "description": "NMEA2000 src value or any similar value for encapsulating the original source of the data"
+          "description": "NMEA2000 src value or any similar value for encapsulating the original source of the data",
+          "example":"36"
         },
         "pgn": {
           "type": "number",
-          "description": "NMEA2000 pgn of the source message"
+          "description": "NMEA2000 pgn of the source message",
+          "example":"130312"
         },
         "sentence": {
           "type": "string",
-          "description": "Sentence type of the source NMEA0183 sentence"
+          "description": "Sentence type of the source NMEA0183 sentence, $GP[RMC],092750.000,A,5321.6802,N,00630.3372,W,0.02,31.66,280511,,,A*43",
+          "example":"RMC"
         },
         "talker": {
           "type": "string",
-          "description": "Talker id of the source NMEA0183 sentence"
+          "description": "Talker id of the source NMEA0183 sentence, $[GP]RMC,092750.000,A,5321.6802,N,00630.3372,W,0.02,31.66,280511,,,A*43",
+          "example":"GP"
         }
       }
     },
 
     "sourceRef": {
       "type": "string",
-      "description": "Reference to the source under vessel's sources"
+      "description": "Reference to the source under vessel's sources. A dot spearated path to the data. eg [type].[bus].[device]",
+      "example":"NMEA0183.COM1.GP"
     },
 
     "version": {
       "type": "string",
-      "description": "Version of the Signal K root object.",
-      "example": "1.0"
+      "description": "Version of the Signal K schema/APIs used by the root object.",
+      "example": "1.0.0"
     },
     "units": {
       "type": "string",
@@ -69,7 +78,7 @@
           "display": "Hz",
           "quantity": "Frequency",
           "quantityDisplay": "F",
-          "description": "Frequency in Herz"
+          "description": "Frequency in Hertz"
         },
         "m3": {
           "display": "m\u00b3",
@@ -216,7 +225,8 @@
       "description": "Maritime Mobile Service Identity (MMSI). Has to be 9 digits. See http://en.wikipedia.org/wiki/Maritime_Mobile_Service_Identity for information.",
       "pattern": "^[2-7][0-9]{8,8}$",
       "maxLength": 9,
-      "minLength": 9
+      "minLength": 9,
+      "example": "503123456"
     },
     "uuid": {
       "type": "string",
@@ -226,7 +236,8 @@
     },
     "url": {
       "type": "string",
-      "description": "A location of a resource, potentially relative. For hierarchical schemes (like http), applications must resolve relative URIs (e.g. './v1/api/'). Implementations should support the following schemes: http:, https:, mailto:, tel:, and ws:."
+      "description": "A location of a resource, potentially relative. For hierarchical schemes (like http), applications must resolve relative URIs (e.g. './v1/api/'). Implementations should support the following schemes: http:, https:, mailto:, tel:, and ws:.",
+      "example":"http://localhost:8080/signalk/v1/api/vessels/self/environment"
     },
 
     "commonValueFields": {
diff --git a/schemas/delta.json b/schemas/delta.json
index 1f16bb276..0057a2172 100644
--- a/schemas/delta.json
+++ b/schemas/delta.json
@@ -3,62 +3,186 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "id": "https://signalk.github.io/specification/schemas/delta.json#",
   "title": "SignalK Delta message schema",
-  "description": "Schema for defining updates to parts of a SignalK data model, for example for communicating updates of data",
-  "required": ["updates"],
+  "description": "Schema for defining updates and subscriptions to parts of a SignalK data model, for example for communicating updates of data",
+  "required": [
+  "updates"  ],
   "properties": {
     "context": {
       "type": "string",
-      "description": "The context path of the updates, eg. the top level path plus object identifier."
-    },
-
+      "description": "The context path of the updates, eg. the top level path plus object identifier.",
+    "example": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5"    },
     "updates": {
       "type": "array",
       "description": "The updates",
       "items": {
         "type": "object",
-        "required": ["values"],
+        "required": [
+        "values"        ],
         "properties": {
           "source": {
-            "allOf": [{
-              "$ref": "./definitions.json#/definitions/source"
-            }, {
-              "properties": {
-                "instance": {
-                  "type": "string"
+            "allOf": [
+              {
+              "$ref": "./definitions.json#/definitions/source"              },
+              {
+                "properties": {
+                  "instance": {
+                  "type": "string"                  }
                 }
               }
-            }]
+            ]
           },
           "timestamp": {
-            "$ref": "./definitions.json#/definitions/timestamp"
-          },
-
+          "$ref": "./definitions.json#/definitions/timestamp"          },
           "values": {
             "type": "array",
             "items": {
               "type": "object",
-              "required": ["path", "value"],
+              "required": [
+                "path",
+              "value"              ],
               "properties": {
                 "path": {
-                  "type": "string"
-                },
-
+                  "type": "string",
+                  "description": "The local path to the data value",
+                "example": "navigation.courseOverGroundMagnetic"                },
                 "value": {
                   "type": [
                     "string",
                     "number",
                     "object",
                     "boolean",
-                    "null"
-                  ],
-
-                  "additionalProperties": true
-                }
+                  "null"                  ],
+                "additionalProperties": true                }
               }
             }
           }
         }
       }
+    },
+    "subscribe": {
+      "type": "array",
+      "description": "A subscription request",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+          	"description": "The relative path of the subscription,  supports jsonPath syntax for complex matches",
+          "type": "string"          },
+          "period": {
+          	"description": "The period to repeat the message in millisecs",
+          	"example": 1000,
+          	"default": 1000, 
+          "type": "integer"          },
+          "format": {
+            "type": "string",
+            "description": "The message format for periodic messages",
+            "enum": [
+							"full",
+						"delta"						],
+					"default":"delta"          },
+          "policy": {
+          	"type": "string",
+          	"description": "The policy rules for repetition. [instant]=send all changes as fast as they are received, but no faster than minPeriod. [ideal]=use instant policy, but send the value every `period` millisecs anyway, whether changed or not. [fixed]=send the last known values every period. ",
+            "enum": [
+							"instant",
+							"ideal",
+						"fixed"						],
+					"default":"ideal"          },
+          "minPeriod": {
+            "type": "integer",
+          "description": "The the fastest message transmission rate allowed, e.g. every `minPeriod/1000` seconds."          }
+        },
+        "required": [
+        "path"        ]
+      }
+    },
+    "unsubscribe": {
+      "type": "array",
+      "description": "An unsubscribe request.",
+      "items": {
+        "type": "object",
+        "properties": {
+        	"path": {
+          	"description": "The relative path to unsubscribe,  supports jsonPath syntax for complex matches",
+          "type": "string"          },
+          "period": {
+          	"description": "The period to repeat the message in millisecs",
+          	"example": 1000,
+          	"default": 1000, 
+          "type": "integer"          },
+          "format": {
+            "type": "string",
+            "description": "The message format for periodic messages",
+            "enum": [
+							"full",
+						"delta"						],
+					"default":"delta"          },
+          "policy": {
+          	"type": "string",
+          	"description": "The policy rules for repetition. [instant]=send all changes as fast as they are received, but no faster than minPeriod. [ideal]=use instant policy, but send the value every `period` millisecs anyway, whether changed or not. [fixed]=send the last known values every period. ",
+            "enum": [
+							"instant",
+							"ideal",
+						"fixed"						],
+					"default":"ideal"          },
+          "minPeriod": {
+            "type": "integer",
+          "description": "The the fastest message transmission rate allowed, e.g. every `minPeriod/1000` seconds."          }
+        },
+        "required": [
+        "path"        ]
+      }
+    },
+    "get": {
+      "type": "array",
+      "description": "A websockets equivalent to a REST GET request.This is for one-off requests, use the subscribe message for regular changes.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+          "description": "The relative path to GET,  supports jsonPath syntax for complex matches"          }
+        },
+        "required": [
+        "path"        ]
+      }
+    },
+    "list": {
+      "type": "array",
+      "description": "Gets a list of known keys for this path",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+          "description": "The relative path to list keys for,  supports jsonPath syntax for complex matches"          }
+        },
+        "required": [
+        "path"        ]
+      }
+    },
+    "put": {
+      "type": "array",
+      "description": "A websockets equivalent to a REST PUT request. This is for one-off changes, use the updates message for regular changes.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+          "description": "The relative path to set."          },
+					"value": {
+						"type": [
+							"string",
+							"number",
+							"object",
+							"boolean",
+						"null"						],
+					"description": "The value to set at the path"        },
+					"required": [
+						"path",
+          "value"        ]
+        }
+      }
     }
   }
 }
diff --git a/schemas/discovery.json b/schemas/discovery.json
index 7903acd82..b7cc7839e 100644
--- a/schemas/discovery.json
+++ b/schemas/discovery.json
@@ -12,7 +12,9 @@
         ".*": {
           "description": "The name of a group of endpoints at the same version level",
           "type": "object",
-          "required": ["version"],
+          "required": [
+            "version"
+          ],
           "properties": {
             "version": {
               "description": "The version this group supports",
diff --git a/schemas/groups/environment.json b/schemas/groups/environment.json
index b1e91dba8..9a1fd6ab0 100644
--- a/schemas/groups/environment.json
+++ b/schemas/groups/environment.json
@@ -71,19 +71,24 @@
           "units": "ratio"
         },
         "engineRoom": {
+          "description": "Current engine room air temperature",
           "$ref": "#/definitions/objectWithTemperature"
         },
         "mainCabin": {
+          "description": "Current main cabin air temperature",
           "$ref": "#/definitions/objectWithTemperature"
         },
 
         "refrigerator": {
+          "description": "Current refrigerator temperature",
           "$ref": "#/definitions/objectWithTemperature"
         },
         "freezer": {
+          "description": "Current freezer temperature",
           "$ref": "#/definitions/objectWithTemperature"
         },
         "heating": {
+          "description": "Current heating temperature",
           "$ref": "#/definitions/objectWithTemperature"
         }
       }
@@ -103,9 +108,11 @@
           "units": "ratio"
         },
         "liveWell": {
+          "description": "Current livewell temperature",
           "$ref": "#/definitions/objectWithTemperature"
         },
         "baitWell": {
+          "description": "Current baitwell air temperature",
           "$ref": "#/definitions/objectWithTemperature"
         }        
       }
@@ -141,7 +148,7 @@
         },
 
         "surfaceToTransducer": {
-          "description": "Depth transducer is below the water",
+          "description": "Depth transducer is below the water surface",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "m"
         }
@@ -185,19 +192,19 @@
       "description": "Tide data",
       "properties": {
         "heightHigh": {
-          "description": "Next high tide",
+          "description": "Next high tide height  relative to lowest astronomical tide (LAT/Chart Datum)",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "m"
         },
 
         "heightNow": {
-          "description": "The current tide height",
+          "description": "The current tide height  relative to lowest astronomical tide (LAT/Chart Datum)",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "m"
         },
 
         "heightLow": {
-          "description": "The next low tide height",
+          "description": "The next low tide height relative to lowest astronomical tide (LAT/Chart Datum)",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "m"
         },
diff --git a/schemas/groups/navigation.json b/schemas/groups/navigation.json
index d80da0819..ea80a8fd3 100644
--- a/schemas/groups/navigation.json
+++ b/schemas/groups/navigation.json
@@ -4,7 +4,6 @@
   "id": "https://signalk.github.io/specification/schemas/groups/navigation.json#",
   "description": "Schema describing the navigation child-object of a Vessel.",
   "title": "navigation",
-
   "definitions": {
     "course": {
       "type": "object",
@@ -16,19 +15,16 @@
           "units": "m",
           "$ref": "../definitions.json#/definitions/numberValue"
         },
-
         "bearingTrackTrue": {
           "description": "The bearing of a line between previousPoint and nextPoint, relative to true north.",
           "units": "rad",
           "$ref": "../definitions.json#/definitions/numberValue"
         },
-
         "bearingTrackMagnetic": {
           "description": "The bearing of a line between previousPoint and nextPoint, relative to magnetic north.",
           "units": "rad",
           "$ref": "../definitions.json#/definitions/numberValue"
         },
-
         "activeRoute": {
           "type": "object",
           "properties": {
@@ -41,109 +37,111 @@
               "$ref": "../definitions.json#/definitions/timestamp",
               "description": "The estimated time of arrival at the end of the current route"
             },
-
             "startTime": {
               "$ref": "../definitions.json#/definitions/timestamp",
               "description": "The time this route was activated"
             }
           }
         },
-
         "nextPoint": {
           "type": "object",
           "description": "The point on earth the vessel's presently navigating towards",
-          "allOf": [{
-            "$ref": "../definitions.json#/definitions/commonValueFields"
-          }, {
-            "properties": {
-              "type": {
-                "description": "The type of the next point (e.g. Waypoint, POI, Race Mark, etc)",
-                "type": "string"
-              },
-              "href": {
-                "description": "A reference (URL) to an object (under resources) this point is related to",
-                "type": "string"
-              },
-              "distance": {
-                "description": "The distance in meters between the vessel's present position and the nextPoint",
-                "units": "m",
-                "type": "number"
-              },
-              "bearingTrue": {
-                "description": "The bearing of a line between the vessel's current position and nextPoint, relative to true north",
-                "units": "rad",
-                "type": "number"
-              },
-              "bearingMagnetic": {
-                "description": "The bearing of a line between the vessel's current position and nextPoint, relative to magnetic north",
-                "units": "rad",
-                "type": "number"
-              },
-              "velocityMadeGood": {
-                "description": "The velocity component of the vessel towards the nextPoint",
-                "units": "m/s",
-                "type": "number"
-              },
-              "timeToGo": {
-                "description": "Time in seconds to reach nextPoint's perpendicular) with current speed & direction",
-                "units": "s",
-                "type": "number"
-              },
-              "position": {
-                "type": "object",
-                "description": "The position of nextPoint in two dimensions",
-                "properties": {
-                  "latitude": {
-                    "type": "number"
-                  },
-                  "longitude": {
-                    "type": "number"
+          "allOf": [
+            {
+              "$ref": "../definitions.json#/definitions/commonValueFields"
+            },
+            {
+              "properties": {
+                "type": {
+                  "description": "The type of the next point (e.g. Waypoint, POI, Race Mark, etc)",
+                  "type": "string"
+                },
+                "href": {
+                  "description": "A reference (URL) to an object (under resources) this point is related to",
+                  "type": "string"
+                },
+                "distance": {
+                  "description": "The distance in meters between the vessel's present position and the nextPoint",
+                  "units": "m",
+                  "type": "number"
+                },
+                "bearingTrue": {
+                  "description": "The bearing of a line between the vessel's current position and nextPoint, relative to true north",
+                  "units": "rad",
+                  "type": "number"
+                },
+                "bearingMagnetic": {
+                  "description": "The bearing of a line between the vessel's current position and nextPoint, relative to magnetic north",
+                  "units": "rad",
+                  "type": "number"
+                },
+                "velocityMadeGood": {
+                  "description": "The velocity component of the vessel towards the nextPoint",
+                  "units": "m/s",
+                  "type": "number"
+                },
+                "timeToGo": {
+                  "description": "Time in seconds to reach nextPoint's perpendicular) with current speed & direction",
+                  "units": "s",
+                  "type": "number"
+                },
+                "position": {
+                  "type": "object",
+                  "description": "The position of nextPoint in two dimensions",
+                  "properties": {
+                    "latitude": {
+                      "type": "number"
+                    },
+                    "longitude": {
+                      "type": "number"
+                    }
                   }
                 }
               }
             }
-          }]
+          ]
         },
-
         "previousPoint": {
           "type": "object",
           "description": "The point on earth the vessel's presently navigating from",
-          "allOf": [{
-            "$ref": "../definitions.json#/definitions/commonValueFields"
-          }, {
-            "properties": {
-              "type": {
-                "description": "The type of the previous point (e.g. Waypoint, POI, Race Mark, etc)",
-                "type": "string"
-              },
-              "href": {
-                "description": "A reference (URL) to an object (under resources) this point is related to",
-                "type": "string"
-              },
-              "distance": {
-                "description": "The distance in meters between previousPoint and the vessel's present position",
-                "units": "m",
-                "type": "number"
-              },
-              "position": {
-                "type": "object",
-                "description": "The position of lastPoint in two dimensions",
-                "properties": {
-                  "latitude": {
-                    "type": "number"
-                  },
-                  "longitude": {
-                    "type": "number"
+          "allOf": [
+            {
+              "$ref": "../definitions.json#/definitions/commonValueFields"
+            },
+            {
+              "properties": {
+                "type": {
+                  "description": "The type of the previous point (e.g. Waypoint, POI, Race Mark, etc)",
+                  "type": "string"
+                },
+                "href": {
+                  "description": "A reference (URL) to an object (under resources) this point is related to",
+                  "type": "string"
+                },
+                "distance": {
+                  "description": "The distance in meters between previousPoint and the vessel's present position",
+                  "units": "m",
+                  "type": "number"
+                },
+                "position": {
+                  "type": "object",
+                  "description": "The position of lastPoint in two dimensions",
+                  "properties": {
+                    "latitude": {
+                      "type": "number"
+                    },
+                    "longitude": {
+                      "type": "number"
+                    }
                   }
                 }
               }
             }
-          }]
+          ]
         }
       }
     }
   },
-
   "properties": {
     "lights": {
       "type": "object",
@@ -177,31 +175,26 @@
             "mine clearance"
           ]
         },
-
         "source": {
           "description": "Source of this data",
           "$ref": "../definitions.json#/definitions/source"
         },
-
         "timestamp": {
           "description": "timestamp of the last update to this data",
           "$ref": "../definitions.json#/definitions/timestamp"
         }
       }
     },
-
     "courseOverGroundMagnetic": {
       "description": "Course over ground (magnetic)",
       "$ref": "../definitions.json#/definitions/numberValue",
       "units": "rad"
     },
-
     "courseOverGroundTrue": {
       "description": "Course over ground (true)",
       "$ref": "../definitions.json#/definitions/numberValue",
       "units": "rad"
     },
-
     "courseRhumbline": {
       "description": "Course information computed with Rhumbline",
       "$ref": "#/definitions/course"
@@ -210,7 +203,6 @@
       "description": "Course information computed with Great Circle",
       "$ref": "#/definitions/course"
     },
-
     "racing": {
       "type": "object",
       "properties": {
@@ -263,22 +255,18 @@
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "m"
         }
-
       }
     },
-
     "magneticVariation": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "The magnetic variation (declination) at the current position",
       "units": "rad"
     },
-
     "magneticVariationAgeOfService": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "Seconds since the 1st Jan 1970 that the variation calculation was made",
       "units": "s"
     },
-
     "destination": {
       "title": "destination",
       "description": "The intended destination of this trip",
@@ -287,24 +275,20 @@
         "eta": {
           "$ref": "../definitions.json#/definitions/timestamp"
         },
-
         "source": {
           "description": "Source of this data",
           "$ref": "../definitions.json#/definitions/source"
         },
-
         "timestamp": {
           "description": "timestamp of the last update to this data",
           "$ref": "../definitions.json#/definitions/timestamp"
         },
-
         "waypoint": {
           "description": "UUID of destination waypoint",
           "type": "string"
         }
       }
     },
-
     "gnss": {
       "type": "object",
       "title": "gnss",
@@ -314,12 +298,10 @@
           "description": "Source of this data",
           "$ref": "../definitions.json#/definitions/source"
         },
-
         "timestamp": {
           "description": "timestamp of the last update to this data",
           "$ref": "../definitions.json#/definitions/timestamp"
         },
-
         "methodQuality": {
           "type": "object",
           "description": "Quality of the satellite fix",
@@ -341,7 +323,6 @@
             }
           }
         },
-
         "integrity": {
           "type": "object",
           "description": "Integrity of the satellite fix",
@@ -357,124 +338,113 @@
             }
           }
         },
-
         "satellites": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Number of satellites"
         },
-
         "antennaAltitude": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Altitude of antenna",
           "units": "m"
         },
-
         "horizontalDilution": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Horizontal Dilution of Precision"
         },
-
         "positionDilution": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Positional Dilution of Precision"
         },
-
         "geoidalSeparation": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Difference between WGS84 earth ellipsoid and mean sea level"
         },
-
         "differentialAge": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Age of DGPS data",
           "units": "s"
         },
-
         "differentialReference": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "ID of DGPS base station"
         }
       }
     },
-
     "headingMagnetic": {
       "$ref": "../definitions.json#/definitions/numberValue",
-      "description": "Current magnetic heading of the vessels",
+      "description": "Current magnetic heading of the vessel",
       "units": "rad"
     },
-
     "headingTrue": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "The current true heading of the vessel",
       "units": "rad"
     },
-
     "position": {
-      "description": "The position of the vessel in 3 dimensions",
-      "allOf": [{
-        "$ref": "../definitions.json#/definitions/commonValueFields"
-      }, {
-      "$ref": "../definitions.json#/definitions/position"
-      }]
+      "description": "The position of the vessel in 2 or 3 dimensions (WGS84 datum)",
+      "allOf": [
+        {
+          "$ref": "../definitions.json#/definitions/commonValueFields"
+        },
+        {
+          "$ref": "../definitions.json#/definitions/position"
+        }
+      ]
     },
-
     "attitude": {
       "type": "object",
       "title": "Attitude",
       "description": "Vessel attitude: roll, pitch and yaw",
-      "allOf": [{
-        "$ref": "../definitions.json#/definitions/commonValueFields"
-      }, {
-      "properties": {
-        "roll": {
-          "type": "number",
-          "description": "Vessel roll, +ve is list to starboard",
-          "units": "rad"
+      "allOf": [
+        {
+          "$ref": "../definitions.json#/definitions/commonValueFields"
         },
-        "pitch": {
-          "type": "number",
-          "description": "Pitch, +ve is bow up",
-          "units": "rad"
-        },
-        "yaw": {
-          "type": "number",
-          "description": "Yaw, +ve is heading change to starboard",
-          "units": "rad"
+        {
+          "properties": {
+            "roll": {
+              "type": "number",
+              "description": "Vessel roll, +ve is list to starboard",
+              "units": "rad"
+            },
+            "pitch": {
+              "type": "number",
+              "description": "Pitch, +ve is bow up",
+              "units": "rad"
+            },
+            "yaw": {
+              "type": "number",
+              "description": "Yaw, +ve is heading change to starboard",
+              "units": "rad"
+            }
+          }
         }
-      }
-      }]
+      ]
     },
-
     "rateOfTurn": {
       "$ref": "../definitions.json#/definitions/numberValue",
-      "description": "Rate of turn",
+      "description": "Rate of turn (+ve is change to starboard)",
       "units": "rad/s"
     },
-
     "speedOverGround": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "Vessel speed over ground",
       "units": "m/s"
     },
-
     "speedThroughWater": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "Vessel speed through the water",
       "units": "m/s"
     },
-
     "log": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "Log value",
       "units": "m"
     },
-
     "logTrip": {
       "$ref": "../definitions.json#/definitions/numberValue",
       "description": "Trip log value",
       "units": "m"
     },
-
     "state": {
       "type": "object",
       "title": "state",
@@ -484,12 +454,10 @@
           "description": "Source of this data",
           "$ref": "../definitions.json#/definitions/source"
         },
-
         "timestamp": {
           "description": "timestamp of the last update to this data",
           "$ref": "../definitions.json#/definitions/timestamp"
         },
-
         "value": {
           "type": "string",
           "enum": [
@@ -519,7 +487,6 @@
         }
       }
     },
-
     "anchor": {
       "type": "object",
       "title": "anchor",
@@ -529,61 +496,62 @@
           "description": "Source of this data",
           "$ref": "../definitions.json#/definitions/source"
         },
-
         "timestamp": {
-          "description": "timestamp of the last update to this data",
+          "description": "Timestamp of the last update to this data",
           "$ref": "../definitions.json#/definitions/timestamp"
         },
-
         "maxRadius": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Radius of anchor alarm boundary. The distance from anchor to the center of the boat",
           "units": "m"
         },
-
         "currentRadius": {
           "$ref": "../definitions.json#/definitions/numberValue",
           "description": "Current distance to anchor",
           "units": "m"
         },
-
         "position": {
           "description": "The actual anchor position of the vessel in 3 dimensions, probably an estimate at best",
-          "allOf": [{
-            "$ref": "../definitions.json#/definitions/commonValueFields"
-          }, {
-          "$ref": "../definitions.json#/definitions/position"
-          }]
+          "allOf": [
+            {
+              "$ref": "../definitions.json#/definitions/commonValueFields"
+            },
+            {
+              "$ref": "../definitions.json#/definitions/position"
+            }
+          ]
         }
       }
     },
-
     "datetime": {
       "type": "object",
-      "allOf": [{
-        "$ref": "../definitions.json#/definitions/commonValueFields"
-      }, {
-      "properties": {
-        "value": {
-          "type": "string",
-          "description": "GNSS Time and Date in ISO8601 format",
-          "exmple": "2015-12-05T13:11:59Z"
+      "allOf": [
+        {
+          "$ref": "../definitions.json#/definitions/commonValueFields"
         },
-        "gnssTimeSource": {
-          "description": "Source of GNSS Date and Time",
-          "enum": [
-            "GPS",
-            "GLONASS",
-            "Galileo",
-            "Beidou",
-            "IRNSS",
-            "Radio Signal",
-            "Internet",
-            "Local clock"
-          ]
+        {
+          "properties": {
+            "value": {
+              "type": "string",
+              "description": "GNSS Time and Date in ISO8601 format",
+              "exmple": "2015-12-05T13:11:59Z"
+            },
+            "gnssTimeSource": {
+              "description": "Source of GNSS Date and Time",
+              "enum": [
+                "GPS",
+                "GLONASS",
+                "Galileo",
+                "Beidou",
+                "IRNSS",
+                "Radio Signal",
+                "Internet",
+                "Local clock"
+              ]
+            }
+          }
         }
-      }
-      }]
+      ]
     }
   }
 }
diff --git a/schemas/groups/notifications.json b/schemas/groups/notifications.json
index 4a320dfb8..d4bf200ff 100644
--- a/schemas/groups/notifications.json
+++ b/schemas/groups/notifications.json
@@ -3,7 +3,7 @@
   "$schema": "http://json-schema.org/draft-04/schema#",
   "id": "https://signalk.github.io/specification/schemas/groups/notifications.json#",
   "title": "notifications",
-  "description": "Alarms, their state, and actions. The alarm limits are set in any Signal K key.meta.zones array.",
+  "description": "Notifications, their state, and actions. The notification limits are set in any Signal K key.meta.zones array.",
 
   "patternProperties": {
     "(^method$)": {
@@ -15,7 +15,7 @@
     },
 
     "(^state$)": {
-      "description": "Current alarm state",
+      "description": "Current notification state",
       "$ref": "../definitions.json#/definitions/alarmState"
     },
 
@@ -25,7 +25,7 @@
     },
 
     "(^timestamp$)": {
-      "description": "timestamp of the last update to this data",
+      "description": "Timestamp of the last update to this data",
       "$ref": "../definitions.json#/definitions/timestamp"
     },
 
@@ -34,7 +34,7 @@
       "$ref": "../definitions.json#/definitions/sourceRef"
     },
     "(^[A-Za-z0-9-]+$)": {
-      "description": "This regex pattern is used for validation of the path of the alarm",
+      "description": "This regex pattern is used for validation of the path of the notification",
       "$ref": "notifications.json#"
     }
   }
diff --git a/schemas/groups/propulsion.json b/schemas/groups/propulsion.json
index 7fec73a82..603d99e3d 100644
--- a/schemas/groups/propulsion.json
+++ b/schemas/groups/propulsion.json
@@ -7,98 +7,87 @@
   "patternProperties": {
     "(^[A-Za-z0-9]+$)": {
       "description": "This regex pattern is used for validation of the identifier for the propulsion unit",
-
       "properties": {
         "label": {
           "type": "string",
           "description": "Human readable label for the propulsion unit"
         },
-
         "state": {
           "type": "object",
           "description": "The current state of the engine",
-          "allOf": [{
-            "$ref": "../definitions.json#/definitions/commonValueFields"
-          }, {
-            "properties": {
-              "value": {
-                "type": "string",
-                "enum": [
-                  "stopped",
-                  "started",
-                  "unusable"
-                ]
+          "allOf": [
+            {
+              "$ref": "../definitions.json#/definitions/commonValueFields"
+            },
+            {
+              "properties": {
+                "value": {
+                  "type": "string",
+                  "enum": [
+                    "stopped",
+                    "started",
+                    "unusable"
+                  ]
+                }
               }
             }
-          }]
+          ]
         },
-
         "revolutions": {
-          "description": "Engine revolutions",
+          "description": "Engine revolutions (x60 for RPM)",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "Hz"
         },
-
         "temperature": {
           "description": "Engine temperature",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "K"
         },
-
         "oilTemperature": {
           "description": "Oil temperature",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "K"
         },
-
         "oilPressure": {
           "description": "Oil pressure",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "Pa"
         },
-
         "alternatorVoltage": {
           "description": "Alternator voltage",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "V"
         },
-
         "runTime": {
-          "description": "Total running time for engine",
+          "description": "Total running time for engine (Engine Hours in seconds)",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "s"
         },
-
         "coolantTemperature": {
           "description": "Coolant temperature",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "K"
         },
-
         "coolantPressure": {
           "description": "Coolant pressure",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "Pa"
         },
-
         "boostPressure": {
           "description": "Engine boost (turbo, supercharger) pressure",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "Pa"
         },
-
         "engineLoad": {
-          "description": "Engine load ratio, 1 is 100%",
+          "description": "Engine load ratio, 0<=ratio<=1, 1 is 100%",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "ratio"
         },
-
         "engineTorque": {
-          "description": "Engine torque ratio, 1 is 100%",
+          "description": "Engine torque ratio, 0<=ratio<=1, 1 is 100%",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "ratio"
         },
-
         "transmission": {
           "type": "object",
           "properties": {
@@ -106,12 +95,17 @@
               "type": "object",
               "properties": {
                 "value": {
-                  "enum": ["Forward", "Neutral", "Reverse", "Fault"]
+                  "enum": [
+                    "Forward",
+                    "Neutral",
+                    "Reverse",
+                    "Fault"
+                  ]
                 }
               }
             },
             "gearRatio": {
-              "description": "Gear ratio, Engine rotations per propeller shaft rotation",
+              "description": "Gear ratio, engine rotations per propeller shaft rotation",
               "$ref": "../definitions.json#/definitions/numberValue",
               "units": "ratio"
             },
@@ -127,15 +121,21 @@
             }
           }
         },
-
         "drive": {
           "type": "object",
           "properties": {
             "type": {
-              "enum": ["saildrive", "shaft", "outboard", "jet", "pod", "other"]
+              "enum": [
+                "saildrive",
+                "shaft",
+                "outboard",
+                "jet",
+                "pod",
+                "other"
+              ]
             },
             "trimState": {
-              "description": "Trim/tilt state",
+              "description": "Trim/tilt state, 0<=ratio<=1, 1 is 100% up",
               "$ref": "../definitions.json#/definitions/numberValue",
               "units": "ratio"
             },
@@ -146,25 +146,30 @@
             },
             "propeller": {
               "pitch ": {
-                "description": "Current pitch of propeller, the distance the propeller ideally would advance during one revolution of the propeller",
+                "description": "Current pitch of propeller, the distance the propeller would advance during one revolution of the propeller without slip",
                 "$ref": "../definitions.json#/definitions/numberValue",
                 "units": "m"
               },
               "slip": {
-                "description": "Propeller slip, the ratio between propeller pitch and actual distance travelled",
+                "description": "Propeller slip, the ratio between propeller pitch and distance travelled. eg 1-(actual distance travelled/propeller pitch). 0<=ratio<=1, 0 is 0% slip, 1 is 100% slip",
                 "$ref": "../definitions.json#/definitions/numberValue",
                 "units": "ratio"
               }
             }
           }
         },
-
         "fuel": {
           "type": "object",
           "properties": {
             "type": {
               "description": "Fuel type",
-              "enum": ["diesel", "petrol", "electric", "coal/wood", "other"]
+              "enum": [
+                "diesel",
+                "petrol",
+                "electric",
+                "coal/wood",
+                "other"
+              ]
             },
             "used": {
               "description": "Used fuel since last reset. Resetting is at user discretion",
@@ -177,47 +182,28 @@
               "units": "Pa"
             },
             "rate": {
-              "description": "Fuel rate",
+              "description": "Fuel rate  of consumption",
               "$ref": "../definitions.json#/definitions/numberValue",
               "units": "m3/s"
             },
             "economyRate": {
-              "description": "Fuel rate",
+              "description": "Economy fuel rate of consumption",
               "$ref": "../definitions.json#/definitions/numberValue",
               "units": "m3/s"
             },
             "averageRate": {
-              "description": "Fuel rate",
+              "description": "Average fuel rate of consumption",
               "$ref": "../definitions.json#/definitions/numberValue",
               "units": "m3/s"
             }
           }
         },
-
-        "waterTemperature": {
-          "description": "Water temperature",
-          "$ref": "../definitions.json#/definitions/numberValue",
-          "units": "K"
-        },
-
         "exhaustTemperature": {
           "description": "Exhaust temperature",
           "$ref": "../definitions.json#/definitions/numberValue",
           "units": "K"
-        },
-
-        "fuelRate": {
-          "description": "Fuel consumption rate",
-          "$ref": "../definitions.json#/definitions/numberValue",
-          "units": "m3/s"
         }
       }
-    },
-
-    "exhaustTemperature": {
-      "description": "Exhaust temperature",
-      "$ref": "../definitions.json#/definitions/numberValue",
-      "units": "K"
     }
   }
 }
diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json
index e30fd26fa..5611bcfe9 100644
--- a/schemas/groups/resources.json
+++ b/schemas/groups/resources.json
@@ -16,11 +16,13 @@
           "properties": {
             "name": {
               "type": "string",
-              "description": "Chart common name"
+              "description": "Chart common name",
+              "example":"NZ615 Marlborough Sounds"
             },
             "identifier": {
               "type": "string",
-              "description": "Chart number"
+              "description": "Chart number",
+              "example":"NZ615"
             },
             "description": {
               "type": "string",
@@ -28,7 +30,8 @@
             },
             "tilemapUrl": {
               "type": "string",
-              "description": "A url to the tilemap of the chart for use in TMS chartplotting apps"
+              "description": "A url to the tilemap of the chart for use in TMS chartplotting apps",
+              "example":"http://{server}:8080/mapcache/NZ615"
             },
             "region": {
               "type": "string",
@@ -40,7 +43,8 @@
             },
             "chartUrl": {
               "type": "string",
-              "description": "A url to the chart file's storage location"
+              "description": "A url to the chart file's storage location",
+              "example":"file:///home/pi/freeboard/mapcache/NZ615"
             },
             "chartFormat": {
               "type": "string",
@@ -81,7 +85,8 @@
           "properties": {
             "name": {
               "type": "string",
-              "description": "Route's common name"
+              "description": "Route's common name",
+              "example":"Nelson Harbour to Adele Is"
             },
             "description": {
               "type": "string",
@@ -102,7 +107,7 @@
             },
             "feature": {
               "title": "Feature",
-              "description": "A Geo JSON feature object",
+              "description": "A Geo JSON feature object which describes the route between the waypoints",
               "required": [
                 "geometry",
                 "properties"
@@ -141,7 +146,7 @@
               }
             },
             "timestamp": {
-              "description": "timestamp of the last update to this data",
+              "description": "Timestamp of the last update to this data",
               "$ref": "../definitions.json#/definitions/timestamp"
             },
             "source": {
@@ -190,7 +195,7 @@
               "description": "Location of the note"
             },
             "timestamp": {
-              "description": "timestamp of the last update to this data",
+              "description": "Timestamp of the last update to this data",
               "$ref": "../definitions.json#/definitions/timestamp"
             },
             "source": {
@@ -216,7 +221,7 @@
             },
             "feature": {
               "title": "Feature",
-              "description": "A Geo JSON feature object",
+              "description": "A Geo JSON feature object which describes the regions boundary",
               "required": [
                 "geometry",
                 "properties"
@@ -275,7 +280,7 @@
               }
             },
             "timestamp": {
-              "description": "timestamp of the last update to this data",
+              "description": "Timestamp of the last update to this data",
               "$ref": "../definitions.json#/definitions/timestamp"
             },
             "source": {
diff --git a/schemas/groups/sources.json b/schemas/groups/sources.json
index aef71bac7..cc511c6f1 100644
--- a/schemas/groups/sources.json
+++ b/schemas/groups/sources.json
@@ -9,129 +9,155 @@
       "type": "object",
       "patternProperties": {
         ".*": {
-          "anyOf": [{
-            "required": ["n2k"]
-          }, {
-            "required": ["talker", "sentences"]
-          }],
-          "anyOf": [{
-            "properties": {
-              "talker": {
-                "type": "string"
-              },
-              "sentences": {
-                "type": "object",
-                "patternProperties": {
-                  "^[A-Z][A-Z][A-Z]$": {
-                    "$ref": "#/definitions/timestamp"
+          "anyOf": [
+            {
+              "properties": {
+                "talker": {
+                  "description": "NMEA 0183 talker id, the GP in $GPRMC..",
+                  "type": "string"
+                },
+                "sentences": {
+                  "description": "NMEA 0183 sentences",
+                  "type": "object",
+                  "patternProperties": {
+                    "^[A-Z][A-Z][A-Z]$": {
+                      "$ref": "#/definitions/timestamp"
+                    }
                   }
-                }
-              },
-              "n2k": {
-                "type": "object",
-                "properties": {
-                  "src": {
-                    "type": "string"
-                  },
-                  "pgns": {
-                    "type": "object",
-                    "patternProperties": {
-                      "[0-9]*": {
-                        "$ref": "#/definitions/timestamp"
+                },
+                "n2k": {
+                  "type": "object",
+                  "properties": {
+                    "src": {
+                      "description": "NMEA 2000 bus",
+                      "type": "string"
+                    },
+                    "pgns": {
+                      "type": "object",
+                      "description": "NMEA 2000 pgn numbere",
+                      "patternProperties": {
+                        "[0-9]*": {
+                          "$ref": "#/definitions/timestamp"
+                        }
                       }
+                    },
+                    "uniqueId": {
+                      "type": "string",
+                      "description": "Unique id of the source device"
+                    },
+                    "deviceFunction": {
+                      "type": "number",
+                      "description": "NMEA 2000 Device Function code"
+                    },
+                    "deviceClass": {
+                      "type": "number",
+                      "description": "NMEA 2000 Device Class code"
                     }
-                  },
-                  "uniqueId": {
-                    "type": "string",
-                    "description": "Unique id of the source device"
-                  },
-                  "deviceFunction": {
-                    "type": "number",
-                    "description": "NMEA 2000 Device Function code"
-                  },
-                  "deviceClass": {
-                    "type": "number",
-                    "description": "NMEA 2000 Device Class code"
                   }
-                }
-              },
-              "manufacturer": {
-                "type": "object",
-                "properties": {
-                  "id": {
-                    "type": "number",
-                    "description": "Manufacturer numeric NMEA 2000 id"
-                  },
-                  "name": {
-                    "type": "string",
-                    "description": "Manufacturer name"
-                  },
-                  "productId": {
-                    "type": "string"
-                  },
-                  "modelId": {
-                    "type": "string"
-                  },
-                  "softwareVersion": {
-                    "type": "string"
-                  },
-                  "hardwareVersion": {
-                    "type": "string"
-                  },
-                  "serialNumber": {
-                    "type": "string"
+                },
+                "manufacturer": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "number",
+                      "description": "Manufacturer numeric NMEA 2000 id"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "Manufacturer name"
+                    },
+                    "productId": {
+                      "type": "string",
+                      "description": "Maunfacturer product Id"
+                    },
+                    "modelId": {
+                      "type": "string",
+                      "description": "Manufacturer model"
+                    },
+                    "softwareVersion": {
+                      "type": "string",
+                      "description": "Manufacturer software version"
+                    },
+                    "hardwareVersion": {
+                      "type": "string",
+                      "description": "Manufacturer hardware version"
+                    },
+                    "serialNumber": {
+                      "type": "string",
+                      "description": "Manufacturer serial number"
+                    }
                   }
                 }
               }
-            }
-          }, {
-            "patternProperties": {
-              ".*": {
-                "properties": {}
+            },
+            {
+              "patternProperties": {
+                ".*": {
+                  "properties": {}
+                }
               }
             }
-          }]
+          ]
         }
       },
       "properties": {
         "label": {
-          "type": "string"
+          "description": "Sources unique name e.g. [type-bus].[id], N2000-01.034",
+          "type": "string",
+          "example":"N2000-01.034"
         },
         "type": {
-          "type": "string"
+          "description": "Type of interface i.e. signalk, NMEA0183 or NMEA2000",
+          "type": "string",
+          "example":"NMEA0183"
         },
         "manufacturer": {
-          "type": "string"
+          "description": "Manufacturer of the source device",
+          "type": "string",
+          "example":"Digital Yacht"
         },
         "productFunction": {
+          "description": "NMEA2000 Product Function Code",
           "type": "number"
         },
         "productClass": {
+          "description": "NMEA2000 Product Class Code",
           "type": "number"
         },
         "productCode": {
+          "description": "NMEA2000 Product Code",
           "type": "number"
         },
         "productName": {
+          "description": "Product Name or Model Number",
           "type": "string"
         },
         "softwareVersion": {
+          "description": "Version of the device's Software/Firmware",
           "type": "string"
         },
         "hardwareVersion": {
+          "description": "Version of the device's Hardware",
           "type": "string"
         },
         "serialNo": {
+          "description": "Device's Serial Number",
           "type": "string"
         },
         "installationNote1": {
-          "type": "string"
+          "description": "Product Installation Note 1 i.e. 'Wired on Navigation Switch/Circuit'",
+          "type": "string",
+          "example":"Wired on Navigation Switch/Circuit"
         },
         "installationNote2": {
-          "type": "string"
+          "description": "Product Installation Note 2 i.e. 'Located under forward bunk'",
+          "type": "string",
+          "example":"Located under forward bunk"
         },
         "manufacturerInfo": {
-          "type": "string"
+          "description": "Manufacturer's Info i.e. 'http://digitalyachtamerica.com Tel:+44 1179 554474'",
+          "type": "string",
+          "example":"http://digitalyachtamerica.com Tel:+44 1179 554474"
         }
       }
     }
diff --git a/schemas/groups/steering.json b/schemas/groups/steering.json
index 08bd8c50f..b114d78d7 100644
--- a/schemas/groups/steering.json
+++ b/schemas/groups/steering.json
@@ -67,7 +67,7 @@
             },
 
             "timestamp": {
-              "description": "timestamp of the last update to this data",
+              "description": "Timestamp of the last update to this data",
               "$ref": "../definitions.json#/definitions/timestamp"
             }
           }
@@ -104,7 +104,7 @@
             },
 
             "timestamp": {
-              "description": "timestamp of the last update to this data",
+              "description": "Timestamp of the last update to this data",
               "$ref": "../definitions.json#/definitions/timestamp"
             }
           }
diff --git a/schemas/signalk.json b/schemas/signalk.json
index d45a9987a..58c442882 100644
--- a/schemas/signalk.json
+++ b/schemas/signalk.json
@@ -4,13 +4,16 @@
   "id": "https://signalk.github.io/specification/schemas/signalk.json#",
   "title": "SignalK",
   "description": "Root schema of Signal K. Contains the list of vessels plus a reference to the local boat (also contained in the vessels list).",
-  "required": ["vessels", "version"],
+  "required": [
+    "vessels",
+    "version"
+  ],
   "properties": {
     "self": {
       "type": "string",
-      "description": "This holds the key (MMSI or other unique ID) of this vessel, the actual data is in the vessels array."
+      "description": "This holds the key (UUID, MMSI or URL) of this vessel, the actual data is in the vessels array.",
+      "example": "urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5"
     },
-
     "vessels": {
       "type": "object",
       "description": "A wrapper object for vessel objects, each describing vessels in range, including this vessel.",
@@ -21,18 +24,16 @@
         }
       }
     },
-
     "sources": {
-      "description": "Metadata about the data sources",
+      "description": "Metadata about the data sources; physical interface, address, protocol, etc.",
       "$ref": "groups/sources.json#"
     },
-
     "resources": {
-      "description": "resources to aid in navigation and operation of the vessel",
+      "description": "Resources to aid in navigation and operation of the vessel including waypoints, routes, notes, etc.",
       "$ref": "groups/resources.json#"
     },
-
     "version": {
+      "description": "Version of the schema and APIs that this data is using in Canonical format i.e. V1.0.0.",
       "$ref": "definitions.json#/definitions/version"
     }
   }
diff --git a/schemas/vessel.json b/schemas/vessel.json
index c810889b3..bafa6594d 100644
--- a/schemas/vessel.json
+++ b/schemas/vessel.json
@@ -4,47 +4,52 @@
   "id": "https://signalk.github.io/specification/schemas/vessel.json#",
   "description": "An object describing an individual vessel. It should be an object in vessels, named using MMSI or a UUID",
   "title": "vessel",
-  "anyOf": [{
-    "required": ["mmsi"]
-  }, {
-    "required": ["url"]
-  }, {
-    "required": ["uuid"]
-  }],
+  "anyOf": [
+    {
+      "required": [
+        "mmsi"
+      ]
+    },
+    {
+      "required": [
+        "url"
+      ]
+    },
+    {
+      "required": [
+        "uuid"
+      ]
+    }
+  ],
   "properties": {
     "url": {
       "description": "URL based identity of the vessel, if available.",
       "$ref": "definitions.json#/definitions/url"
     },
-
     "mmsi": {
       "description": "MMSI number of the vessel, if available.",
       "$ref": "definitions.json#/definitions/mmsi"
     },
-
     "uuid": {
       "description": "A unique Signal K flavoured maritime resource identifier, assigned by the server.",
       "$ref": "definitions.json#/definitions/uuid",
       "example": "urn:mrn:signalk:uuid:b7590868-1d62-47d9-989c-32321b349fb9"
     },
-
     "name": {
       "type": "string",
-      "description": "The common name of the vessel"
+      "description": "The common name of the vessel",
+      "example": "Motu"
     },
-
     "flag": {
       "type": "string",
       "description": "The country of ship registration, or flag state of the vessel",
       "example": "NZ"
     },
-
     "port": {
       "type": "string",
       "description": "The home port of the vessel",
       "example": "Nelson"
     },
-
     "registrations": {
       "type": "object",
       "description": "The various registrations of the vessel.",
@@ -130,41 +135,34 @@
         }
       }
     },
-
-
-
-
     "communication": {
-      "description": "Communication data",
+      "description": "Communication data including Radio, Telephone, E-Mail, etc.",
       "$ref": "groups/communication.json#"
     },
-
     "environment": {
-      "description": "Environmental data",
+      "description": "Environmental data measured locally including Depth, Wind, Temp, etc.",
       "$ref": "groups/environment.json#"
     },
-
     "navigation": {
-      "description": "Navigation data",
+      "description": "Navigation data including Position, Course to next WP information, etc.",
       "$ref": "groups/navigation.json#"
     },
-
     "propulsion": {
       "type": "object",
       "title": "propulsion",
-      "description": "Engine data",
+      "description": "Engine data, each engine identified by a unique name i.e. Port_Engine",
       "$ref": "groups/propulsion.json#"
     },
-
     "electrical": {
-      "description": "Electrical data",
+      "type": "object",
+      "title": "electrical",
+      "description": "Electrical data, each electrical device indentified by a unique name i.e. Battery_1",
       "$ref": "groups/electrical.json#"
     },
-
     "notifications": {
       "type": "object",
       "title": "notifications",
-      "description": "Notifications currently raised",
+      "description": "Notifications currently raised. Major categories have well-defined names, but the tree can be extended by any hierarchical structure",
       "properties": {
         "mob": {
           "description": "Man overboard",
@@ -210,30 +208,29 @@
       "patternProperties": {
         "(^[A-Za-z0-9-]+$)": {
           "description": "This regex pattern is used for validation of the path of the alarm",
-          "$ref": "groups/notifications.json#"
+          "$ref": "groups/notifications.json#",
+          "example": "engine"
         }
       }
     },
-
     "steering": {
-      "description": "Vessel steering data",
+      "description": "Vessel steering data for steering controls (not Autopilot 'Nav Data')",
       "$ref": "groups/steering.json#"
     },
-
     "tanks": {
+      "type": "object",
+      "title": "tanks",
+      "description": "Tank data, each tank indentified by a unique name i.e. FreshWater_2",
       "$ref": "groups/tanks.json#"
     },
-
     "design": {
-      "description": "Design data of this vessel",
+      "description": "Design/dimensional data of this vessel",
       "$ref": "groups/design.json#"
     },
-
     "sails": {
       "description": "Sails data",
       "$ref": "groups/sails.json#"
     },
-
     "sensors": {
       "type": "object",
       "title": "sensors",
@@ -245,9 +242,8 @@
         }
       }
     },
-
     "performance": {
-      "description": "Performance data",
+      "description": "Performance Sailing data including VMG, Polar Speed, tack angle, etc.",
       "$ref": "groups/performance.json#"
     }
   }