From e9cb9374030df423b07139b488baec8c688f32ff Mon Sep 17 00:00:00 2001 From: sumps Date: Tue, 7 Jun 2016 15:04:02 +0100 Subject: [PATCH 1/6] Adding Descriptions and Examples for V1 - Step 1 First set of changes to get the specification ready for V1 release --- schemas/definitions.json | 4 +- schemas/groups/navigation.json | 4 +- schemas/groups/propulsion.json | 27 +- schemas/groups/sources.json | 269 +++++++++--------- schemas/signalk.json | 65 ++--- schemas/vessel.json | 492 +++++++++++++++++---------------- 6 files changed, 437 insertions(+), 424 deletions(-) diff --git a/schemas/definitions.json b/schemas/definitions.json index 2edfd1dac..b66e2bcc3 100644 --- a/schemas/definitions.json +++ b/schemas/definitions.json @@ -52,8 +52,8 @@ "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", diff --git a/schemas/groups/navigation.json b/schemas/groups/navigation.json index d80da0819..cffa1dbff 100644 --- a/schemas/groups/navigation.json +++ b/schemas/groups/navigation.json @@ -410,7 +410,7 @@ }, "position": { - "description": "The position of the vessel in 3 dimensions", + "description": "The position of the vessel in 2 or 3 dimensions (WGS84 datum)", "allOf": [{ "$ref": "../definitions.json#/definitions/commonValueFields" }, { @@ -447,7 +447,7 @@ "rateOfTurn": { "$ref": "../definitions.json#/definitions/numberValue", - "description": "Rate of turn", + "description": "Rate of turn (+ve is change to starboard)", "units": "rad/s" }, diff --git a/schemas/groups/propulsion.json b/schemas/groups/propulsion.json index 7fec73a82..a43e3d3b7 100644 --- a/schemas/groups/propulsion.json +++ b/schemas/groups/propulsion.json @@ -34,7 +34,7 @@ }, "revolutions": { - "description": "Engine revolutions", + "description": "Engine revolutions (x60 for RPM)", "$ref": "../definitions.json#/definitions/numberValue", "units": "Hz" }, @@ -64,7 +64,7 @@ }, "runTime": { - "description": "Total running time for engine", + "description": "Total running time for engine (Engine Hours in seconds)", "$ref": "../definitions.json#/definitions/numberValue", "units": "s" }, @@ -182,42 +182,25 @@ "units": "m3/s" }, "economyRate": { - "description": "Fuel rate", + "description": "Economy Fuel rate", "$ref": "../definitions.json#/definitions/numberValue", "units": "m3/s" }, "averageRate": { - "description": "Fuel rate", + "description": "Average Fuel rate", "$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/sources.json b/schemas/groups/sources.json index aef71bac7..3b909672c 100644 --- a/schemas/groups/sources.json +++ b/schemas/groups/sources.json @@ -1,139 +1,158 @@ { - "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", - "id": "https://signalk.github.io/specification/schemas/groups/sources.json#", - "title": "sources", - "description": "Metadata about the sources, eg. buses and connected sensors", - "patternProperties": { - ".*": { - "type": "object", - "patternProperties": { + "type": "object", + "$schema": "http://json-schema.org/draft-04/schema#", + "id": "https://signalk.github.io/specification/schemas/groups/sources.json#", + "title": "sources", + "description": "Metadata about the sources, eg. buses and connected sensors", + "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" - } + "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" + } + } + }, + "n2k": { + "type": "object", + "properties": { + "src": { + "type": "string" + }, + "pgns": { + "type": "object", + "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" + } + } + }, + "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" + } + } + } + } + }, + { + "patternProperties": { + ".*": { + "properties": { } + } + } + } + ] } - }, - "n2k": { - "type": "object", - "properties": { - "src": { + }, + "properties": { + "label": { + "description": "Sources unique name e.g. N2000-01.034", "type": "string" - }, - "pgns": { - "type": "object", - "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" - } - } - }, - "manufacturer": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "Manufacturer numeric NMEA 2000 id" - }, - "name": { - "type": "string", - "description": "Manufacturer name" - }, - "productId": { + }, + "type": { + "description": "Type of interface i.e. NMEA0183 or NMEA2000", + "type": "string" + }, + "manufacturer": { + "description": "Manufacturer of the source device", + "type": "string" + }, + "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" - }, - "modelId": { + }, + "softwareVersion": { + "description": "Version of the device's Software/Firmware", "type": "string" - }, - "softwareVersion": { + }, + "hardwareVersion": { + "description": "Version of the device's Hardware", "type": "string" - }, - "hardwareVersion": { + }, + "serialNo": { + "description": "Device's Serial Number", "type": "string" - }, - "serialNumber": { + }, + "installationNote1": { + "description": "Product Installation Note 1 i.e. 'Wired on Navigation Switch/Circuit'", + "type": "string" + }, + "installationNote2": { + "description": "Product Installation Note 2 i.e. 'Located under forward bunk'", + "type": "string" + }, + "manufacturerInfo": { + "description": "Manufacturer's Info i.e. 'http://digitalyachtamerica.com Tel:+44 1179 554474'", "type": "string" - } } - } } - }, { - "patternProperties": { - ".*": { - "properties": {} - } - } - }] - } - }, - "properties": { - "label": { - "type": "string" - }, - "type": { - "type": "string" - }, - "manufacturer": { - "type": "string" - }, - "productFunction": { - "type": "number" - }, - "productClass": { - "type": "number" - }, - "productCode": { - "type": "number" - }, - "productName": { - "type": "string" - }, - "softwareVersion": { - "type": "string" - }, - "hardwareVersion": { - "type": "string" - }, - "serialNo": { - "type": "string" - }, - "installationNote1": { - "type": "string" - }, - "installationNote2": { - "type": "string" - }, - "manufacturerInfo": { - "type": "string" } - } } - } } diff --git a/schemas/signalk.json b/schemas/signalk.json index d45a9987a..14db42d25 100644 --- a/schemas/signalk.json +++ b/schemas/signalk.json @@ -1,39 +1,40 @@ { - "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", - "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"], - "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." - }, + "type": "object", + "$schema": "http://json-schema.org/draft-04/schema#", + "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" ], + "properties": { + "self": { + "type": "string", + "description": "This holds the key (UUID, MMSI or URL) of this vessel, the actual data is in the vessels array." + }, - "vessels": { - "type": "object", - "description": "A wrapper object for vessel objects, each describing vessels in range, including this vessel.", - "patternProperties": { - "(^urn:mrn:(imo|signalk):(mmsi:[2-7][0-9]{8,8}|uuid:[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}))|^(http(s?):.*|mailto:.*|tel:(\\+?)[0-9]{4,})$": { - "description": "This regex pattern is used for validation of an MMSI or Signal K UUID identifier for the vessel. Examples: urn:mrn:imo:mmsi:230099999 urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d", - "$ref": "vessel.json#" - } - } - }, + "vessels": { + "type": "object", + "description": "A wrapper object for vessel objects, each describing vessels in range, including this vessel.", + "patternProperties": { + "(^urn:mrn:(imo|signalk):(mmsi:[2-7][0-9]{8,8}|uuid:[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}))|^(http(s?):.*|mailto:.*|tel:(\\+?)[0-9]{4,})$": { + "description": "This regex pattern is used for validation of an MMSI or Signal K UUID identifier for the vessel. Examples: urn:mrn:imo:mmsi:230099999 urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d", + "$ref": "vessel.json#" + } + } + }, - "sources": { - "description": "Metadata about the data sources", - "$ref": "groups/sources.json#" - }, + "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", - "$ref": "groups/resources.json#" - }, + "resources": { + "description": "Resources to aid in navigation and operation of the vessel including waypoints, routes, notes, etc.", + "$ref": "groups/resources.json#" + }, - "version": { - "$ref": "definitions.json#/definitions/version" + "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..8f955e25d 100644 --- a/schemas/vessel.json +++ b/schemas/vessel.json @@ -1,254 +1,264 @@ { - "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", - "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"] - }], - "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" - }, - - "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.", - "example": "eg for a New Zealand Part B recreational vessel: 'NZ654'", - "properties": { - "imo": { - "type": "string", - "description": "The IMO number of the vessel.", - "pattern": "^IMO [0-9]{7,7}$", - "example": "IMO 9074729", - "maxLength": 11, - "minLength": 11 - }, - "national": { - "type": "object", - "description": "The national registration number of the vessel.", - "patternProperties": { - "(^[A-Za-z0-9_-]+$)": { - "description": "This regex pattern is used for validating the identifier for the registration", - "properties": { - "country": { - "type": "string", - "description": "The ISO 3166-2 country code.", - "example": "NZ", - "maxLength": 2, - "minLength": 2 + "type": "object", + "$schema": "http://json-schema.org/draft-04/schema#", + "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" ] + } + ], + "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/gateway.", + "$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", + "example": "SY Morning Star" + }, + + "flag": { + "type": "string", + "description": "The country of vessel 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.", + "example": "eg for a New Zealand Part B recreational vessel: 'NZ654'", + "properties": { + "imo": { + "type": "string", + "description": "The IMO number of the vessel.", + "pattern": "^IMO [0-9]{7,7}$", + "example": "IMO 9074729", + "maxLength": 11, + "minLength": 11 }, - "registration": { - "type": "string", - "description": "The registration code", - "example": "NZ654" + "national": { + "type": "object", + "description": "The national registration number of the vessel.", + "patternProperties": { + "(^[A-Za-z0-9_-]+$)": { + "description": "This regex pattern is used for validating the identifier for the registration", + "properties": { + "country": { + "type": "string", + "description": "The ISO 3166-2 country code.", + "example": "NZ", + "maxLength": 2, + "minLength": 2 + }, + "registration": { + "type": "string", + "description": "The registration code", + "example": "NZ654" + }, + "description": { + "type": "string", + "description": "The registration description", + "example": "New Zealand Part B recreational vessel" + } + } + } + } }, - "description": { - "type": "string", - "description": "The registration description", - "example": "New Zealand Part B recreational vessel" + "local": { + "type": "object", + "description": "A local or state registration number of the vessel.", + "patternProperties": { + "(^[A-Za-z0-9_-]+$)": { + "description": "This regex pattern is used for validating the identifier for the registration", + "properties": { + "registration": { + "type": "string", + "description": "The registration code", + "example": "NZCG-2345" + }, + "description": { + "type": "string", + "description": "The registration description", + "example": "Nelson Coast Guard Membership" + } + } + } + } + }, + "other": { + "type": "object", + "description": "Other registration or permits for the vessel.", + "patternProperties": { + "(^[A-Za-z0-9_-]+$)": { + "description": "This regex pattern is used for validating the identifier for the registration", + "properties": { + "registration": { + "type": "string", + "description": "The registration code", + "example": "DOC-2345" + }, + "description": { + "type": "string", + "description": "The registration description", + "example": "Tasmanian National Parks Access Permit 2015" + } + } + } + } } - } } - } - }, - "local": { - "type": "object", - "description": "A local or state registration number of the vessel.", - "patternProperties": { - "(^[A-Za-z0-9_-]+$)": { - "description": "This regex pattern is used for validating the identifier for the registration", - "properties": { - "registration": { - "type": "string", - "description": "The registration code", - "example": "NZCG-2345" + }, + + + + + "communication": { + "description": "Communication data including Radio, Telephone, E-Mail, etc.", + "$ref": "groups/communication.json#" + }, + + "environment": { + "description": "Environmental data measured locally including Depth, Wind, Temp, etc.", + "$ref": "groups/environment.json#" + }, + + "navigation": { + "description": "Navigation data including Position, Course to next WP information, etc.", + "$ref": "groups/navigation.json#" + }, + + "propulsion": { + "type": "object", + "title": "propulsion", + "description": "Engine data, each engine identified by a unique name i.e. Port_Engine", + "$ref": "groups/propulsion.json#" + }, + + "electrical": { + "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", + "properties": { + "mob": { + "description": "Man overboard", + "$ref": "groups/notifications.json#" + }, + "fire": { + "description": "Fire onboard", + "$ref": "groups/notifications.json#" + }, + "sinking": { + "description": "Vessel is sinking", + "$ref": "groups/notifications.json#" + }, + "flooding": { + "description": "Vessel is flooding", + "$ref": "groups/notifications.json#" + }, + "collision": { + "description": "In collision with another vessel or object", + "$ref": "groups/notifications.json#" + }, + "grounding": { + "description": "Vessel grounding", + "$ref": "groups/notifications.json#" }, - "description": { - "type": "string", - "description": "The registration description", - "example": "Nelson Coast Guard Membership" + "listing": { + "description": "Vessel is listing", + "$ref": "groups/notifications.json#" + }, + "adrift": { + "description": "Vessel is adrift", + "$ref": "groups/notifications.json#" + }, + "piracy": { + "description": "Under attack or danger from pirates", + "$ref": "groups/notifications.json#" + }, + "abandon": { + "description": "Abandon ship", + "$ref": "groups/notifications.json#" + } + }, + "patternProperties": { + "(^[A-Za-z0-9-]+$)": { + "description": "This regex pattern is used for validation of the path of the alarm", + "$ref": "groups/notifications.json#" } - } } - } - }, - "other": { - "type": "object", - "description": "Other registration or permits for the vessel.", - "patternProperties": { - "(^[A-Za-z0-9_-]+$)": { - "description": "This regex pattern is used for validating the identifier for the registration", - "properties": { - "registration": { - "type": "string", - "description": "The registration code", - "example": "DOC-2345" - }, - "description": { - "type": "string", - "description": "The registration description", - "example": "Tasmanian National Parks Access Permit 2015" + }, + + "steering": { + "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/dimensional data of this vessel", + "$ref": "groups/design.json#" + }, + + "sails": { + "description": "Sails data", + "$ref": "groups/sails.json#" + }, + + "sensors": { + "type": "object", + "title": "sensors", + "description": "Sensors, their state, and data.", + "patternProperties": { + "(^[A-Za-z0-9]+$)": { + "description": "This regex pattern is used for validation UUID identifier for the sensor", + "$ref": "groups/sensors.json#" } - } } - } - } - } - }, - - - - - "communication": { - "description": "Communication data", - "$ref": "groups/communication.json#" - }, - - "environment": { - "description": "Environmental data", - "$ref": "groups/environment.json#" - }, - - "navigation": { - "description": "Navigation data", - "$ref": "groups/navigation.json#" - }, - - "propulsion": { - "type": "object", - "title": "propulsion", - "description": "Engine data", - "$ref": "groups/propulsion.json#" - }, - - "electrical": { - "description": "Electrical data", - "$ref": "groups/electrical.json#" - }, - - "notifications": { - "type": "object", - "title": "notifications", - "description": "Notifications currently raised", - "properties": { - "mob": { - "description": "Man overboard", - "$ref": "groups/notifications.json#" - }, - "fire": { - "description": "Fire onboard", - "$ref": "groups/notifications.json#" - }, - "sinking": { - "description": "Vessel is sinking", - "$ref": "groups/notifications.json#" - }, - "flooding": { - "description": "Vessel is flooding", - "$ref": "groups/notifications.json#" - }, - "collision": { - "description": "In collision with another vessel or object", - "$ref": "groups/notifications.json#" - }, - "grounding": { - "description": "Vessel grounding", - "$ref": "groups/notifications.json#" - }, - "listing": { - "description": "Vessel is listing", - "$ref": "groups/notifications.json#" - }, - "adrift": { - "description": "Vessel is adrift", - "$ref": "groups/notifications.json#" - }, - "piracy": { - "description": "Under attack or danger from pirates", - "$ref": "groups/notifications.json#" - }, - "abandon": { - "description": "Abandon ship", - "$ref": "groups/notifications.json#" - } - }, - "patternProperties": { - "(^[A-Za-z0-9-]+$)": { - "description": "This regex pattern is used for validation of the path of the alarm", - "$ref": "groups/notifications.json#" - } - } - }, - - "steering": { - "description": "Vessel steering data", - "$ref": "groups/steering.json#" - }, - - "tanks": { - "$ref": "groups/tanks.json#" - }, - - "design": { - "description": "Design data of this vessel", - "$ref": "groups/design.json#" - }, - - "sails": { - "description": "Sails data", - "$ref": "groups/sails.json#" - }, - - "sensors": { - "type": "object", - "title": "sensors", - "description": "Sensors, their state, and data.", - "patternProperties": { - "(^[A-Za-z0-9]+$)": { - "description": "This regex pattern is used for validation UUID identifier for the sensor", - "$ref": "groups/sensors.json#" - } - } - }, + }, - "performance": { - "description": "Performance data", - "$ref": "groups/performance.json#" + "performance": { + "description": "Performance Sailing data including VMG, Polar Speed, tack angle, etc.", + "$ref": "groups/performance.json#" + } } - } } From 22a67cef2b91aae28a9693d0a64f09becaae3121 Mon Sep 17 00:00:00 2001 From: rob42 Date: Sat, 11 Jun 2016 11:40:04 +1200 Subject: [PATCH 2/6] Added examples, and tidied descriptions --- schemas/definitions.json | 31 +++++++++++++++++++++---------- schemas/delta.json | 7 +++++-- schemas/signalk.json | 3 ++- schemas/vessel.json | 8 +++++--- 4 files changed, 33 insertions(+), 16 deletions(-) diff --git a/schemas/definitions.json b/schemas/definitions.json index 2edfd1dac..07718a195 100644 --- a/schemas/definitions.json +++ b/schemas/definitions.json @@ -13,41 +13,50 @@ }, "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", + "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": { @@ -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..4bf60639a 100644 --- a/schemas/delta.json +++ b/schemas/delta.json @@ -8,7 +8,8 @@ "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": { @@ -40,7 +41,9 @@ "required": ["path", "value"], "properties": { "path": { - "type": "string" + "type": "string", + "description":"The local path to the data value", + "example":"navigation.courseOverGroundMagnetic" }, "value": { diff --git a/schemas/signalk.json b/schemas/signalk.json index d45a9987a..1e53479dd 100644 --- a/schemas/signalk.json +++ b/schemas/signalk.json @@ -8,7 +8,8 @@ "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 (MMSI or other unique ID) of this vessel, the actual data is in the vessels array.", + "example":"urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5" }, "vessels": { diff --git a/schemas/vessel.json b/schemas/vessel.json index c810889b3..4cd0287be 100644 --- a/schemas/vessel.json +++ b/schemas/vessel.json @@ -30,7 +30,8 @@ "name": { "type": "string", - "description": "The common name of the vessel" + "description": "The common name of the vessel", + "example":"Motu" }, "flag": { @@ -164,7 +165,7 @@ "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", @@ -209,8 +210,9 @@ }, "patternProperties": { "(^[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 elements of the notification", "$ref": "groups/notifications.json#" + "example":"engine" } } }, From c63e699ecae86313dd57b5cf54b0d1c4c58e095e Mon Sep 17 00:00:00 2001 From: rob42 Date: Sun, 12 Jun 2016 12:05:37 +1200 Subject: [PATCH 3/6] I hate commas --- schemas/definitions.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/definitions.json b/schemas/definitions.json index ff28a01d1..91a5746c9 100644 --- a/schemas/definitions.json +++ b/schemas/definitions.json @@ -27,7 +27,7 @@ "type": { "type": "string", "description":"A human name to identify the type. NMEA0183, NMEA2000, signalk", - "default": "NMEA2000" + "default": "NMEA2000", "example": "NMEA2000" }, "src": { From 51a898e6b3e4aaa2f5356c797ee2d2e29c19bfca Mon Sep 17 00:00:00 2001 From: rob42 Date: Tue, 14 Jun 2016 21:18:08 +1200 Subject: [PATCH 4/6] Added descriptions and generally edited --- schemas/groups/environment.json | 15 +++++++++++---- schemas/groups/navigation.json | 4 ++-- schemas/groups/notifications.json | 8 ++++---- schemas/groups/propulsion.json | 18 +++++++++--------- schemas/groups/resources.json | 25 +++++++++++++++---------- schemas/groups/sources.json | 4 ++++ schemas/groups/steering.json | 4 ++-- 7 files changed, 47 insertions(+), 31 deletions(-) diff --git a/schemas/groups/environment.json b/schemas/groups/environment.json index b1e91dba8..416b3ad91 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 mean sea level(MSL)", "$ref": "../definitions.json#/definitions/numberValue", "units": "m" }, "heightNow": { - "description": "The current tide height", + "description": "The current tide height relative to mean sea level(MSL)", "$ref": "../definitions.json#/definitions/numberValue", "units": "m" }, "heightLow": { - "description": "The next low tide height", + "description": "The next low tide height relative to mean sea level(MSL)", "$ref": "../definitions.json#/definitions/numberValue", "units": "m" }, diff --git a/schemas/groups/navigation.json b/schemas/groups/navigation.json index b97963bc0..ea80a8fd3 100644 --- a/schemas/groups/navigation.json +++ b/schemas/groups/navigation.json @@ -372,7 +372,7 @@ }, "headingMagnetic": { "$ref": "../definitions.json#/definitions/numberValue", - "description": "Current magnetic heading of the vessels", + "description": "Current magnetic heading of the vessel", "units": "rad" }, "headingTrue": { @@ -497,7 +497,7 @@ "$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": { 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 4b6df3a1b..603d99e3d 100644 --- a/schemas/groups/propulsion.json +++ b/schemas/groups/propulsion.json @@ -79,12 +79,12 @@ "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" }, @@ -105,7 +105,7 @@ } }, "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" }, @@ -135,7 +135,7 @@ ] }, "trimState": { - "description": "Trim/tilt state", + "description": "Trim/tilt state, 0<=ratio<=1, 1 is 100% up", "$ref": "../definitions.json#/definitions/numberValue", "units": "ratio" }, @@ -146,12 +146,12 @@ }, "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" } @@ -182,17 +182,17 @@ "units": "Pa" }, "rate": { - "description": "Fuel rate", + "description": "Fuel rate of consumption", "$ref": "../definitions.json#/definitions/numberValue", "units": "m3/s" }, "economyRate": { - "description": "Economy Fuel rate", + "description": "Economy fuel rate of consumption", "$ref": "../definitions.json#/definitions/numberValue", "units": "m3/s" }, "averageRate": { - "description": "Average Fuel rate", + "description": "Average fuel rate of consumption", "$ref": "../definitions.json#/definitions/numberValue", "units": "m3/s" } 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 f86ab6040..cc511c6f1 100644 --- a/schemas/groups/sources.json +++ b/schemas/groups/sources.json @@ -13,9 +13,11 @@ { "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]$": { @@ -27,10 +29,12 @@ "type": "object", "properties": { "src": { + "description": "NMEA 2000 bus", "type": "string" }, "pgns": { "type": "object", + "description": "NMEA 2000 pgn numbere", "patternProperties": { "[0-9]*": { "$ref": "#/definitions/timestamp" 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" } } From e9114cd9b2bf2dc4b5f4bb7a2435103b7cbae2cf Mon Sep 17 00:00:00 2001 From: rob42 Date: Tue, 14 Jun 2016 21:25:06 +1200 Subject: [PATCH 5/6] Change mean sea level for chart datum/LAT --- schemas/groups/environment.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/groups/environment.json b/schemas/groups/environment.json index 416b3ad91..9a1fd6ab0 100644 --- a/schemas/groups/environment.json +++ b/schemas/groups/environment.json @@ -192,19 +192,19 @@ "description": "Tide data", "properties": { "heightHigh": { - "description": "Next high tide height relative to mean sea level(MSL)", + "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 relative to mean sea level(MSL)", + "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 relative to mean sea level(MSL)", + "description": "The next low tide height relative to lowest astronomical tide (LAT/Chart Datum)", "$ref": "../definitions.json#/definitions/numberValue", "units": "m" }, From a790c4473bdfbd2ab9b5bfe50366ea759a1473da Mon Sep 17 00:00:00 2001 From: rob42 Date: Wed, 29 Jun 2016 11:51:06 +1200 Subject: [PATCH 6/6] Added subscribe, unsubscribe, get, put, list message types --- schemas/delta.json | 157 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 136 insertions(+), 21 deletions(-) diff --git a/schemas/delta.json b/schemas/delta.json index 4d3800345..0057a2172 100644 --- a/schemas/delta.json +++ b/schemas/delta.json @@ -3,71 +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", + "description": "Schema for defining updates and subscriptions to parts of a SignalK data model, for example for communicating updates of data", "required": [ - "updates" - ], + "updates" ], "properties": { "context": { "type": "string", "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" - }, + "example": "vessels.urn:mrn:signalk:uuid:6b0e776f-811a-4b35-980e-b93405371bc5" }, "updates": { "type": "array", "description": "The updates", "items": { "type": "object", "required": [ - "values" - ], + "values" ], "properties": { "source": { "allOf": [ { - "$ref": "./definitions.json#/definitions/source" - }, + "$ref": "./definitions.json#/definitions/source" }, { "properties": { "instance": { - "type": "string" - } + "type": "string" } } } ] }, "timestamp": { - "$ref": "./definitions.json#/definitions/timestamp" - }, + "$ref": "./definitions.json#/definitions/timestamp" }, "values": { "type": "array", "items": { "type": "object", "required": [ "path", - "value" - ], + "value" ], "properties": { "path": { "type": "string", "description": "The local path to the data value", - "example": "navigation.courseOverGroundMagnetic" - }, + "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" ] + } + } } } }