From 6a7fc2b146c172af562fe8e7a37e3b8a54d07686 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 6 Apr 2019 16:32:43 +1030 Subject: [PATCH 01/17] Add `group` and `author` attributes to Notes schema Update description of `region`, `position` and `geohash` to clarify the use of `region` in addition to `position` and `geohash` --- schemas/groups/resources.json | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index 731101530..a7db95d75 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -202,14 +202,14 @@ }, "region": { "type": "string", - "description": "Region related to note. A pointer to a region UUID. Alternative to position or geohash" + "description": "Region related to note. A pointer to a region UUID. Can be defined in additon to position or geohash" }, "position": { - "description": "Position related to note. Alternative to region or geohash", + "description": "Position related to note. Alternative to geohash", "$ref": "../definitions.json#/definitions/position" }, "geohash": { - "description": "Position related to note. Alternative to region or position", + "description": "Position related to note. Alternative to position", "$ref": "../definitions.json#/definitions/geohash" }, "mimeType": { @@ -220,6 +220,14 @@ "type": "string", "description": "Location of the note" }, + "group": { + "type": "string", + "description": "Name of a group or collection to which the note is attached" + }, + "author": { + "type": "string", + "description": "Name of the creator of the note" + }, "timestamp": { "description": "Timestamp of the last update to this data", "$ref": "../definitions.json#/definitions/timestamp" From 9470675af4c5da25f8a7e0dd965725a0beecea0c Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Tue, 9 Apr 2019 08:11:50 +0930 Subject: [PATCH 02/17] Additional `Note` attributes `readOnly` & `published` --- schemas/groups/resources.json | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index a7db95d75..a690bb84d 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -227,7 +227,15 @@ "author": { "type": "string", "description": "Name of the creator of the note" - }, + }, + "readOnly": { + "type": "boolean", + "description": "Indicates whether the whether the content of the Note is permitted to be changed." + }, + "published": { + "type": "boolean", + "description": "Indicates whether the note is available only for use on this server or shared with others." + }, "timestamp": { "description": "Timestamp of the last update to this data", "$ref": "../definitions.json#/definitions/timestamp" From f4b80a789acbcf2d3b0f5d9403b578de92e08498 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 27 Apr 2019 16:42:19 +0930 Subject: [PATCH 03/17] Updated `region`, `position` and `geohash` property descriptions to allow all to be present. --- schemas/groups/resources.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index a690bb84d..df71eee09 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -202,14 +202,14 @@ }, "region": { "type": "string", - "description": "Region related to note. A pointer to a region UUID. Can be defined in additon to position or geohash" + "description": "A pointer to a region UUID to which the Note is related. Can be defined in addition to position or geohash" }, "position": { - "description": "Position related to note. Alternative to geohash", + "description": "Position related to note.", "$ref": "../definitions.json#/definitions/position" }, "geohash": { - "description": "Position related to note. Alternative to position", + "description": "Area related to note. Geohash area should encompass the position value (if it is defined).", "$ref": "../definitions.json#/definitions/geohash" }, "mimeType": { From c4fcc2304cc3f649b1dae1990f6db409875439e1 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 27 Apr 2019 16:45:09 +0930 Subject: [PATCH 04/17] Updated `authors` property to align to `package.json` `contributors` definition. Changed `published` to `draft` for clarity. --- schemas/groups/resources.json | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index df71eee09..eac9d55c8 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -224,17 +224,38 @@ "type": "string", "description": "Name of a group or collection to which the note is attached" }, - "author": { - "type": "string", - "description": "Name of the creator of the note" + "authors": { + "type": "array", + "description": "List of note author(s)", + "anyOf": [ + { + "$ref": "../definitions.json#/definitions/commonValueFields" + }, + { + "properties": { + "name": { + "type": "string", + "description": "Name of author" + }, + "email": { + "type": "string", + "description": "E-mail address of author" + }, + "url": { + "type": "string", + "description": "Link to author details" + } + } + } + ] }, "readOnly": { "type": "boolean", - "description": "Indicates whether the whether the content of the Note is permitted to be changed." + "description": "Indicates whether the content of the Note is permitted to be changed." }, - "published": { + "draft": { "type": "boolean", - "description": "Indicates whether the note is available only for use on this server or shared with others." + "description": "Indicates whether the note is available only for use on the local server." }, "timestamp": { "description": "Timestamp of the last update to this data", From 3cd382f4a1ae4dd91ea5f31ff781b1e13b0791c9 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Thu, 2 May 2019 09:13:43 +0930 Subject: [PATCH 05/17] Added `properties` attribute to hold application / use case specific key/value pairs. Removed `readOnly` and `draft` properties. --- schemas/groups/resources.json | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index eac9d55c8..689f4b16a 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -249,14 +249,10 @@ } ] }, - "readOnly": { - "type": "boolean", - "description": "Indicates whether the content of the Note is permitted to be changed." - }, - "draft": { - "type": "boolean", - "description": "Indicates whether the note is available only for use on the local server." - }, + "properties": { + "type": "object", + "description": "Extension properties placholder for use by applications." + }, "timestamp": { "description": "Timestamp of the last update to this data", "$ref": "../definitions.json#/definitions/timestamp" From f461b55b2a4cd899b9ec0ecc865a017c0e42aade Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 11 May 2019 18:49:08 +0930 Subject: [PATCH 06/17] Added example notes to test/data/full-valid --- schemas/groups/resources.json | 3 +- .../full-valid/resources-note-sample.json | 87 +++++++++++++++++++ 2 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 test/data/full-valid/resources-note-sample.json diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index 689f4b16a..bbd9cd901 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -251,7 +251,8 @@ }, "properties": { "type": "object", - "description": "Extension properties placholder for use by applications." + "description": "Extension properties placholder for use by applications.", + "additionalProperties": true }, "timestamp": { "description": "Timestamp of the last update to this data", diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json new file mode 100644 index 000000000..fa75c463f --- /dev/null +++ b/test/data/full-valid/resources-note-sample.json @@ -0,0 +1,87 @@ +{ + "resources": { + "notes": { + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021d": { + "title": "Big Island", + "description": "Big Island Approach notes.....", + "mimeType": "text/html", + "url": "https://myhost.com/bigisland.html", + "group": "Islands", + "authors": [ + { + "name": "Joe Smith", + "email": "joe.smith@mail.com", + "url": "www.joesmith.org" + } + ], + "geohash": "rbejg:Big Island", + "position": { + "timestamp": "2015-03-06T16:57:53.643Z", + "$source": "self", + "value": { + "longitude": 173.17, + "latitude": -41.157, + "altitude": 0 + } + }, + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "properties": { + "draft": true + }, + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021a": { + "title": "Small Island", + "description": "Small Island Approach notes.....", + "mimeType": "text/html", + "group": "Islands", + "authors": [ + { + "name": "Jane Brown", + "email": "jane.brown@mail.com", + "url": "www.janeb.org" + } + ], + "position": { + "timestamp": "2015-03-06T16:57:53.643Z", + "$source": "self", + "value": { + "longitude": 173.17, + "latitude": -41.157, + "altitude": 0 + } + }, + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021f": { + "title": "Dusky Shoal", + "description": "Anchoring information for Dsuky Shoal.....", + "authors": [ + { + "name": "Ian West" + } + ], + "geohash": "rbejg:Big Island", + "properties": { + "draft": true + }, + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + } + } + }, + "version": "1.0.0", + "self": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d" + } + \ No newline at end of file From 654149315a0c5eaa3351c2f24d45d114d4fa8e23 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 10:52:24 +0930 Subject: [PATCH 07/17] Fix geohash values in test/data/full-valid --- test/data/full-valid/resources-note-sample.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index fa75c463f..ed15dfc01 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -14,7 +14,7 @@ "url": "www.joesmith.org" } ], - "geohash": "rbejg:Big Island", + "geohash": "rbejg", "position": { "timestamp": "2015-03-06T16:57:53.643Z", "$source": "self", @@ -69,7 +69,7 @@ "name": "Ian West" } ], - "geohash": "rbejg:Big Island", + "geohash": "rbejg", "properties": { "draft": true }, From f87f37e84df2c529848e52b68ffb89bbd7412272 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 11:17:52 +0930 Subject: [PATCH 08/17] Add author definition and use for note authors property --- schemas/groups/resources.json | 41 +++++++++++++++++------------------ 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index bbd9cd901..2860102f3 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -227,27 +227,7 @@ "authors": { "type": "array", "description": "List of note author(s)", - "anyOf": [ - { - "$ref": "../definitions.json#/definitions/commonValueFields" - }, - { - "properties": { - "name": { - "type": "string", - "description": "Name of author" - }, - "email": { - "type": "string", - "description": "E-mail address of author" - }, - "url": { - "type": "string", - "description": "Link to author details" - } - } - } - ] + "items": { "$ref": "#/definitions/author" } }, "properties": { "type": "object", @@ -266,6 +246,25 @@ } } }, + "definitions": { + "author": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of author" + }, + "email": { + "type": "string", + "description": "E-mail address of author" + }, + "url": { + "type": "string", + "description": "Link to author details" + } + } + } + }, "regions": { "type": "object", "title": "region", From 2da0b36d8a64369dd00c25f029b60240a6f730ff Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 11:31:42 +0930 Subject: [PATCH 09/17] re-position #definitions section --- schemas/groups/resources.json | 664 +++++++++++++++++----------------- 1 file changed, 332 insertions(+), 332 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index 2860102f3..4e01e9313 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -1,250 +1,347 @@ { - "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", - "id": "https://signalk.org/specification/1.0.0/schemas/groups/resources.json#", - "title": "resources", - "description": "Resources to aid in navigation and operation of the vessel", - "properties": { - "charts": { - "type": "object", - "title": "chart", - "description": "A holder for charts, each named with their chart code", - "patternProperties": { - "(^[A-Za-z0-9_-]{8,}$)": { - "type": "object", - "description": "A chart", - "properties": { - "name": { - "type": "string", - "description": "Chart common name", - "example":"NZ615 Marlborough Sounds" - }, - "identifier": { - "type": "string", - "description": "Chart number", - "example":"NZ615" - }, - "description": { - "type": "string", - "description": "A description of the chart" - }, - "tilemapUrl": { - "type": "string", - "description": "A url to the tilemap of the chart for use in TMS chartplotting apps", - "example":"http://{server}:8080/mapcache/NZ615" - }, - "region": { - "type": "string", - "description": "Region related to note. A pointer to a region UUID. Alternative to geohash" - }, - "geohash": { - "description": "Position related to chart. Alternative to region", - "$ref": "../definitions.json#/definitions/geohash" - }, - "chartUrl": { - "type": "string", - "description": "A url to the chart file's storage location", - "example":"file:///home/pi/freeboard/mapcache/NZ615" - }, - "scale": { - "type": "integer", - "description": "The scale of the chart, the larger number from 1:200000" - }, - "chartLayers": { - "type": "array", - "description": "If the chart format is WMS, the layers enabled for the chart.", - "items": { - "type": "string", - "description": "Identifier for the layer." - } - }, - "bounds": { - "type": "array", - "description": "The bounds of the chart. An array containing the position of the upper left corner, and the lower right corner. Useful when the chart isn't inherently geo-referenced.", - "items": { - "$ref": "../definitions.json#/definitions/position", - "description": "Position of a corner of the chart" - } - }, - "chartFormat": { - "type": "string", - "description": "The format of the chart", - "enum": [ - "gif", - "geotiff", - "kap", - "png", - "jpg", - "kml", - "wkt", - "topojson", - "geojson", - "gpx", - "tms", - "wms", - "S-57", - "S-63", - "svg", - "other" - ] - }, - "timestamp": { - "description": "timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" + "type": "object", + "$schema": "http://json-schema.org/draft-04/schema#", + "id": "https://signalk.org/specification/1.0.0/schemas/groups/resources.json#", + "title": "resources", + "description": "Resources to aid in navigation and operation of the vessel", + "properties": { + "charts": { + "type": "object", + "title": "chart", + "description": "A holder for charts, each named with their chart code", + "patternProperties": { + "(^[A-Za-z0-9_-]{8,}$)": { + "type": "object", + "description": "A chart", + "properties": { + "name": { + "type": "string", + "description": "Chart common name", + "example":"NZ615 Marlborough Sounds" + }, + "identifier": { + "type": "string", + "description": "Chart number", + "example":"NZ615" + }, + "description": { + "type": "string", + "description": "A description of the chart" + }, + "tilemapUrl": { + "type": "string", + "description": "A url to the tilemap of the chart for use in TMS chartplotting apps", + "example":"http://{server}:8080/mapcache/NZ615" + }, + "region": { + "type": "string", + "description": "Region related to note. A pointer to a region UUID. Alternative to geohash" + }, + "geohash": { + "description": "Position related to chart. Alternative to region", + "$ref": "../definitions.json#/definitions/geohash" + }, + "chartUrl": { + "type": "string", + "description": "A url to the chart file's storage location", + "example":"file:///home/pi/freeboard/mapcache/NZ615" + }, + "scale": { + "type": "integer", + "description": "The scale of the chart, the larger number from 1:200000" + }, + "chartLayers": { + "type": "array", + "description": "If the chart format is WMS, the layers enabled for the chart.", + "items": { + "type": "string", + "description": "Identifier for the layer." + } + }, + "bounds": { + "type": "array", + "description": "The bounds of the chart. An array containing the position of the upper left corner, and the lower right corner. Useful when the chart isn't inherently geo-referenced.", + "items": { + "$ref": "../definitions.json#/definitions/position", + "description": "Position of a corner of the chart" + } + }, + "chartFormat": { + "type": "string", + "description": "The format of the chart", + "enum": [ + "gif", + "geotiff", + "kap", + "png", + "jpg", + "kml", + "wkt", + "topojson", + "geojson", + "gpx", + "tms", + "wms", + "S-57", + "S-63", + "svg", + "other" + ] + }, + "timestamp": { + "description": "timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" + } + } } - } - } - } - }, - "routes": { - "type": "object", - "title": "route", - "description": "A holder for routes, each named with a UUID", - "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A route, named with a UUID", - "properties": { - "name": { - "type": "string", - "description": "Route's common name", - "example":"Nelson Harbour to Adele Is" - }, - "description": { - "type": "string", - "description": "A description of the route" - }, - "distance": { - "description": "Total distance from start to end", - "type": "number", - "units": "m" - }, - "start": { - "type": "string", - "description": "The waypoint UUID at the start of the route" - }, - "end": { - "type": "string", - "description": "The waypoint UUID at the end of the route" - }, - "feature": { - "title": "Feature", - "description": "A Geo JSON feature object which describes the route between the waypoints", - "required": [ - "geometry", - "properties" - ], - "properties": { - "type": { - "enum": [ - "Feature" - ] - }, - "geometry": { - "title": "LineString", - "properties": { + } + }, + "routes": { + "type": "object", + "title": "route", + "description": "A holder for routes, each named with a UUID", + "patternProperties": { + "^urn:mrn:signalk: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}$": { + "type": "object", + "description": "A route, named with a UUID", + "properties": { + "name": { + "type": "string", + "description": "Route's common name", + "example":"Nelson Harbour to Adele Is" + }, + "description": { + "type": "string", + "description": "A description of the route" + }, + "distance": { + "description": "Total distance from start to end", + "type": "number", + "units": "m" + }, + "start": { + "type": "string", + "description": "The waypoint UUID at the start of the route" + }, + "end": { + "type": "string", + "description": "The waypoint UUID at the end of the route" + }, + "feature": { + "title": "Feature", + "description": "A Geo JSON feature object which describes the route between the waypoints", + "required": [ + "geometry", + "properties" + ], + "properties": { "type": { - "enum": [ - "LineString" - ] + "enum": [ + "Feature" + ] + }, + "geometry": { + "title": "LineString", + "properties": { + "type": { + "enum": [ + "LineString" + ] + }, + "coordinates": { + "$ref": "../external/geojson/geometry.json#/definitions/lineString" + } + } + }, + "properties": { + "type": [ + "object", + "null" + ], + "description": "Additional data of any type", + "additionalProperties": true }, - "coordinates": { - "$ref": "../external/geojson/geometry.json#/definitions/lineString" + "id": { + "FIXME": "may be there, type not known (string? number?)" + } + } - } }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" + } + } + } + } + }, + "notes": { + "type": "object", + "title": "notes", + "description": "A holder for notes about regions, each named with a UUID. Notes might include navigation or cruising info, images, or anything", + "patternProperties": { + "^urn:mrn:signalk: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}$": { + "type": "object", + "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", + "properties": { + "title": { + "type": "string", + "description": "Note's common name" + }, + "description": { + "type": "string", + "description": "A textual description of the note" + }, + "region": { + "type": "string", + "description": "A pointer to a region UUID to which the Note is related. Can be defined in addition to position or geohash" + }, + "position": { + "description": "Position related to note.", + "$ref": "../definitions.json#/definitions/position" + }, + "geohash": { + "description": "Area related to note. Geohash area should encompass the position value (if it is defined).", + "$ref": "../definitions.json#/definitions/geohash" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the note" + }, + "url": { + "type": "string", + "description": "Location of the note" + }, + "group": { + "type": "string", + "description": "Name of a group or collection to which the note is attached" + }, + "authors": { + "type": "array", + "description": "List of note author(s)", + "items": { "$ref": "#/definitions/author" } + }, "properties": { - "type": [ - "object", - "null" - ], - "description": "Additional data of any type", - "additionalProperties": true - }, - "id": { - "FIXME": "may be there, type not known (string? number?)" + "type": "object", + "description": "Extension properties placholder for use by applications.", + "additionalProperties": true + }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$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" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" } - } - } - } - }, - "notes": { - "type": "object", - "title": "notes", - "description": "A holder for notes about regions, each named with a UUID. Notes might include navigation or cruising info, images, or anything", - "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", - "properties": { - "title": { - "type": "string", - "description": "Note's common name" - }, - "description": { - "type": "string", - "description": "A textual description of the note" - }, - "region": { - "type": "string", - "description": "A pointer to a region UUID to which the Note is related. Can be defined in addition to position or geohash" - }, - "position": { - "description": "Position related to note.", - "$ref": "../definitions.json#/definitions/position" - }, - "geohash": { - "description": "Area related to note. Geohash area should encompass the position value (if it is defined).", - "$ref": "../definitions.json#/definitions/geohash" - }, - "mimeType": { - "type": "string", - "description": "MIME type of the note" - }, - "url": { - "type": "string", - "description": "Location of the note" - }, - "group": { - "type": "string", - "description": "Name of a group or collection to which the note is attached" - }, - "authors": { - "type": "array", - "description": "List of note author(s)", - "items": { "$ref": "#/definitions/author" } - }, - "properties": { + } + }, + "regions": { + "type": "object", + "title": "region", + "description": "A holder for regions, each named with UUID", + "patternProperties": { + "^urn:mrn:signalk: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}$": { "type": "object", - "description": "Extension properties placholder for use by applications.", - "additionalProperties": true - }, - "timestamp": { - "description": "Timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" + "description": "A region of interest, each named with a UUID", + "properties": { + "geohash": { + "description": "geohash of the approximate boundary of this region", + "$ref:": "../definitions.json#/definitions/geohash" + }, + "feature": { + "title": "Feature", + "description": "A Geo JSON feature object which describes the regions boundary", + "required": [ + "geometry", + "properties" + ], + "properties": { + "type": { + "enum": [ + "Feature" + ] + }, + "geometry": { + "oneOf": [ + { + "title": "Polygon", + "properties": { + "type": { + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + }, + { + "title": "MultiPolygon", + "properties": { + "type": { + "enum": [ + "MultiPolygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + } + } + ] + }, + "properties": { + "type": [ + "object", + "null" + ], + "description": "Additional data of any type", + "additionalProperties": true + }, + "id": { + "FIXME": "may be there, type not known (string? number?)" + } + + } + }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" + } + } + } + } + }, + "waypoints": { + "type": "object", + "title": "waypoints", + "description": "A holder for waypoints, each named with a UUID", + "patternProperties": { + "^urn:mrn:signalk: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}$": { + "description": "A waypoint, named with a UUID", + "$ref": "../definitions.json#/definitions/waypoint" + } } - } } - } }, "definitions": { "author": { @@ -264,102 +361,5 @@ } } } - }, - "regions": { - "type": "object", - "title": "region", - "description": "A holder for regions, each named with UUID", - "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A region of interest, each named with a UUID", - "properties": { - "geohash": { - "description": "geohash of the approximate boundary of this region", - "$ref:": "../definitions.json#/definitions/geohash" - }, - "feature": { - "title": "Feature", - "description": "A Geo JSON feature object which describes the regions boundary", - "required": [ - "geometry", - "properties" - ], - "properties": { - "type": { - "enum": [ - "Feature" - ] - }, - "geometry": { - "oneOf": [ - { - "title": "Polygon", - "properties": { - "type": { - "enum": [ - "Polygon" - ] - }, - "coordinates": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" - } - } - }, - { - "title": "MultiPolygon", - "properties": { - "type": { - "enum": [ - "MultiPolygon" - ] - }, - "coordinates": { - "type": "array", - "items": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" - } - } - } - } - ] - }, - "properties": { - "type": [ - "object", - "null" - ], - "description": "Additional data of any type", - "additionalProperties": true - }, - "id": { - "FIXME": "may be there, type not known (string? number?)" - } - - } - }, - "timestamp": { - "description": "Timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" - } - } - } - } - }, - "waypoints": { - "type": "object", - "title": "waypoints", - "description": "A holder for waypoints, each named with a UUID", - "patternProperties": { - "^urn:mrn:signalk: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}$": { - "description": "A waypoint, named with a UUID", - "$ref": "../definitions.json#/definitions/waypoint" - } - } } - } } From cd8220f5a89280398ad6ff24dc6ddaeffe3bbe90 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 15:48:48 +0930 Subject: [PATCH 10/17] Added Notes document --- gitbook-docs/resources_notes.md | 249 ++++++++++++++++++++++++++++++++ schemas/groups/resources.json | 246 +++++++++++++++---------------- 2 files changed, 372 insertions(+), 123 deletions(-) create mode 100644 gitbook-docs/resources_notes.md diff --git a/gitbook-docs/resources_notes.md b/gitbook-docs/resources_notes.md new file mode 100644 index 000000000..49bf3b38a --- /dev/null +++ b/gitbook-docs/resources_notes.md @@ -0,0 +1,249 @@ +# Notes + +Notes are a Signal K resource type that provide a means to attach information to a geographic location or area. They are accessed via the Signal K API path `/signalk/v1/api/resources/notes`. + +Notes are associated to a geographic location (position), area (Geohash) or feature (`Region`) and therefore at least one of the `position`, `geohash` or `region` properties need to be defined. + +Additionally, notes can be associated with other notes to form a collection. This is done by assigning the same `group` value to each of the notes considered to be part of the collection. + +--- + +### Note Properties: + +`title`: Text containing the title of the note. + +`description`: Text describing the object that the note is associated with. + +`mimeType`: MIME type of the note. If this property is `null` or `undefined` then the note is considered plain text. + +`url`: Link to additional note content. If this property is `null` or `undefined` then the `description` should be considred the content of the note. + +`group`: Text representing the name of a collection that this note is part of. Notes with the same `group` value are considered part of the collection. If this property is `null` or `undefined` then the note is not part of any collection. + +`authors`: A list containing the details of the authors / contributors to the note content. Each author entry can contain one or more of the following: `name`, `email`, `url`. + +`geohash`: Geographic area to which the note is attached. + +`position`: Geographic position to which the note is attached. If defined in conjunction with `geohash`, it should be within the `geohash` area. + +`region`: The UUID of a `region` resource to which the Note is attached. + +`properties`: An object that is a placeholder for application / use case specific values. + +_Example: Define a `draft` property to indicate the note has not been finalised._ +```json +{ + "title": "Big Island", + "description": "Big Island Approach notes.....", + "geohash": "rbejg", + "properties": { + "draft": true + } +} +``` + +### Example: Combining `region` and `group` + +Using a combination of `region` and `group` the following notes contain information about safe anchorages in the Great Barrier Reef _(defined in a `region` resource)_. + +```json +{ + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc4123b" : { + "title": "Whitehaven Beach", + "description": "Whitehaven Beach is a pristinebeach on Whitsunday Island.....", + "geohash": "rk3uv", + "group": "GBR Safe Anchorages", + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e" + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc4123b" : { + "title": "Shute Harbour", + "description": "is a sheltered port for small vessels located approximately 10 km east of Airlie Beach.....", + "geohash": "rk3u9", + "group": "GBR Safe Anchorages", + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e" + } +} +``` + +### Example: Combining `region`, `geohash` and `position` + +By using a combination of `region`, `geohash` and `position` notes can be assigned to specific geolocations within an area. +```json +{ + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc4123b" : { + "title": "Big Harbour etry", + "description": "...is a sheltered port .....", + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "geohash": "rk3u9", + "position":{ + "latitude": -20.2919444444, + "longitude": 148.785 + } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc4123b" : { + "title": "Big Harbour Jetty", + "description": "...", + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "geohash": "rk3u9", + "position":{ + "latitude": -20.2913, + "longitude": 148.779 + } + } +} +``` + +--- + +## Working with Notes + +The retrieval, creation, updating or deletion of notes is done by making the appropriate request to the Signal K server. + +See [Request/Response](request_response.md) for more details on request/response behaviour in Signal K. + +_Note: Resource requests do not require a `context`._ + +--- +#### RETRIEVING NOTES +To retrieve a list of notes from the server make a __GET__ request to the notes path. _e.g. `/signalk/v1/api/resources/notes`_ + +To retrieve an individual note make a __GET__ request to its path. + +__via HTTP:__ +``` +GET `/signalk/v1/api/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ +``` + +__via Delta:__ +``` +"get": [{ + "path": "resources.notes" +}] + +"get": [{ + "path": "resources.notes.urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd" +}] +``` +--- +#### CREATING NOTES + +__via HTTP:__ + +Send a __POST__ request containing the note's details. +```json +POST http://localhost:3000/signalk/v1/api/vessels/resources/notes +{ + "value": { + "title": "Dusky Shoal", + "description": "Anchoring information for Dsuky Shoal.....", + "authors": [ + { + "name": "Ian West" + } + ], + "geohash": "rbejg:Big Island", + "properties": { + "draft": true + }, + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + } +} +``` + +__via Delta:__ + +Send a __PUT__ request containing the note's details. +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes", + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + } + }] +} +``` +--- + +#### UPDATING NOTES + +To update a note send a __PUT__ request containing the note's details, via either an HTTP or Delta request, to the path of the note. + +The note to be updated is identified by its __uuid__. + +__via HTTP:__ +```json +PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd +{ + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + }, + "source": "myApp", +} +``` + +__via Delta:__ + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes.urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd", + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + } + }] +} +``` +--- + +#### DELETING NOTES + +__via HTTP:__ + +To delete a note send a __DELETE__ request to the note's path. + +``` +DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd +``` + +__via Delta:__ + +Send a PUT message to the path of the note to be removed with a value of `null`. + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes.urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd", + "value": null + }] +} +``` +--- diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index 4e01e9313..f960f8941 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -188,158 +188,158 @@ "title": "notes", "description": "A holder for notes about regions, each named with a UUID. Notes might include navigation or cruising info, images, or anything", "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", - "properties": { - "title": { - "type": "string", - "description": "Note's common name" - }, - "description": { - "type": "string", - "description": "A textual description of the note" - }, - "region": { - "type": "string", - "description": "A pointer to a region UUID to which the Note is related. Can be defined in addition to position or geohash" - }, - "position": { - "description": "Position related to note.", - "$ref": "../definitions.json#/definitions/position" - }, - "geohash": { - "description": "Area related to note. Geohash area should encompass the position value (if it is defined).", - "$ref": "../definitions.json#/definitions/geohash" - }, - "mimeType": { - "type": "string", - "description": "MIME type of the note" - }, - "url": { - "type": "string", - "description": "Location of the note" - }, - "group": { - "type": "string", - "description": "Name of a group or collection to which the note is attached" - }, - "authors": { - "type": "array", - "description": "List of note author(s)", - "items": { "$ref": "#/definitions/author" } - }, - "properties": { + "^urn:mrn:signalk: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}$": { "type": "object", - "description": "Extension properties placholder for use by applications.", - "additionalProperties": true - }, - "timestamp": { - "description": "Timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" - } + "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", + "properties": { + "title": { + "type": "string", + "description": "Note's common name" + }, + "description": { + "type": "string", + "description": "A textual description of the note" + }, + "region": { + "type": "string", + "description": "A pointer to a region UUID to which the Note is related. Can be defined in addition to position or geohash" + }, + "position": { + "description": "Position related to note.", + "$ref": "../definitions.json#/definitions/position" + }, + "geohash": { + "description": "Area related to note. Geohash area should encompass the position value (if it is defined).", + "$ref": "../definitions.json#/definitions/geohash" + }, + "mimeType": { + "type": "string", + "description": "MIME type of the note" + }, + "url": { + "type": "string", + "description": "Location of the note" + }, + "group": { + "type": "string", + "description": "Name of a group or collection to which the note is attached" + }, + "authors": { + "type": "array", + "description": "List of note author(s)", + "items": { "$ref": "#/definitions/author" } + }, + "properties": { + "type": [ "object", "null" ], + "description": "Extension properties placholder for use by applications.", + "additionalProperties": true + }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" + } + } } } - } }, "regions": { "type": "object", "title": "region", "description": "A holder for regions, each named with UUID", "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A region of interest, each named with a UUID", - "properties": { - "geohash": { - "description": "geohash of the approximate boundary of this region", - "$ref:": "../definitions.json#/definitions/geohash" - }, - "feature": { - "title": "Feature", - "description": "A Geo JSON feature object which describes the regions boundary", - "required": [ - "geometry", - "properties" - ], + "^urn:mrn:signalk: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}$": { + "type": "object", + "description": "A region of interest, each named with a UUID", "properties": { - "type": { - "enum": [ - "Feature" - ] - }, - "geometry": { - "oneOf": [ - { - "title": "Polygon", - "properties": { - "type": { - "enum": [ - "Polygon" - ] - }, - "coordinates": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" - } - } + "geohash": { + "description": "geohash of the approximate boundary of this region", + "$ref:": "../definitions.json#/definitions/geohash" }, - { - "title": "MultiPolygon", + "feature": { + "title": "Feature", + "description": "A Geo JSON feature object which describes the regions boundary", + "required": [ + "geometry", + "properties" + ], "properties": { "type": { "enum": [ - "MultiPolygon" + "Feature" ] }, - "coordinates": { - "type": "array", - "items": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" + "geometry": { + "oneOf": [ + { + "title": "Polygon", + "properties": { + "type": { + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + }, + { + "title": "MultiPolygon", + "properties": { + "type": { + "enum": [ + "MultiPolygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + } } + ] + }, + "properties": { + "type": [ + "object", + "null" + ], + "description": "Additional data of any type", + "additionalProperties": true + }, + "id": { + "FIXME": "may be there, type not known (string? number?)" } + } + }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" } - ] - }, - "properties": { - "type": [ - "object", - "null" - ], - "description": "Additional data of any type", - "additionalProperties": true - }, - "id": { - "FIXME": "may be there, type not known (string? number?)" } - - } - }, - "timestamp": { - "description": "Timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" - } } } - } }, "waypoints": { "type": "object", "title": "waypoints", "description": "A holder for waypoints, each named with a UUID", "patternProperties": { - "^urn:mrn:signalk: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}$": { - "description": "A waypoint, named with a UUID", - "$ref": "../definitions.json#/definitions/waypoint" - } + "^urn:mrn:signalk: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}$": { + "description": "A waypoint, named with a UUID", + "$ref": "../definitions.json#/definitions/waypoint" + } } } }, From a2193724d1564bb913034d7a0788bbb3abce555e Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 15:55:50 +0930 Subject: [PATCH 11/17] Update sample --- .../full-valid/resources-note-sample.json | 34 +++---------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index ed15dfc01..6dfe31bf2 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -6,14 +6,7 @@ "description": "Big Island Approach notes.....", "mimeType": "text/html", "url": "https://myhost.com/bigisland.html", - "group": "Islands", - "authors": [ - { - "name": "Joe Smith", - "email": "joe.smith@mail.com", - "url": "www.joesmith.org" - } - ], + "group": "Islands", "geohash": "rbejg", "position": { "timestamp": "2015-03-06T16:57:53.643Z", @@ -38,22 +31,10 @@ "title": "Small Island", "description": "Small Island Approach notes.....", "mimeType": "text/html", - "group": "Islands", - "authors": [ - { - "name": "Jane Brown", - "email": "jane.brown@mail.com", - "url": "www.janeb.org" - } - ], + "group": "Islands", "position": { - "timestamp": "2015-03-06T16:57:53.643Z", - "$source": "self", - "value": { - "longitude": 173.17, - "latitude": -41.157, - "altitude": 0 - } + "longitude": 173.17, + "latitude": -41.157 }, "timestamp": "2015-03-06T16:57:53.643Z", "source": { @@ -63,12 +44,7 @@ }, "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021f": { "title": "Dusky Shoal", - "description": "Anchoring information for Dsuky Shoal.....", - "authors": [ - { - "name": "Ian West" - } - ], + "description": "Anchoring information for Dsuky Shoal.....", "geohash": "rbejg", "properties": { "draft": true From ed8d1b795ec7db61ff3ae1a05d91fa45451f6a67 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 16:02:01 +0930 Subject: [PATCH 12/17] add timestamp to sample --- .../full-valid/resources-note-sample.json | 30 +------------------ 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index 6dfe31bf2..ed3592dc8 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -1,7 +1,7 @@ { "resources": { "notes": { - "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021d": { + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021b": { "title": "Big Island", "description": "Big Island Approach notes.....", "mimeType": "text/html", @@ -26,34 +26,6 @@ "label": "note", "type": "manual" } - }, - "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021a": { - "title": "Small Island", - "description": "Small Island Approach notes.....", - "mimeType": "text/html", - "group": "Islands", - "position": { - "longitude": 173.17, - "latitude": -41.157 - }, - "timestamp": "2015-03-06T16:57:53.643Z", - "source": { - "label": "note", - "type": "manual" - } - }, - "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021f": { - "title": "Dusky Shoal", - "description": "Anchoring information for Dsuky Shoal.....", - "geohash": "rbejg", - "properties": { - "draft": true - }, - "timestamp": "2015-03-06T16:57:53.643Z", - "source": { - "label": "note", - "type": "manual" - } } } }, From e587e7170fce56b5e7e937ce34ec29f4fcacfcce Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 12 May 2019 16:07:20 +0930 Subject: [PATCH 13/17] update sample --- test/data/full-valid/resources-note-sample.json | 3 --- 1 file changed, 3 deletions(-) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index ed3592dc8..e427dbd91 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -18,9 +18,6 @@ } }, "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", - "properties": { - "draft": true - }, "timestamp": "2015-03-06T16:57:53.643Z", "source": { "label": "note", From 6b12cf304c2e24c779ec9ede44b540ca7e5b05f5 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Mon, 13 May 2019 13:35:47 +0930 Subject: [PATCH 14/17] Updated sample --- test/data/full-valid/resources-note-sample.json | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index e427dbd91..262e84785 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -1,7 +1,7 @@ { "resources": { "notes": { - "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021b": { + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021d": { "title": "Big Island", "description": "Big Island Approach notes.....", "mimeType": "text/html", @@ -18,6 +18,12 @@ } }, "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "authors": [ + {"name": "John Smith"} + ], + "properties": { + "draft": true + }, "timestamp": "2015-03-06T16:57:53.643Z", "source": { "label": "note", From d05d1f00f40e7c51510b7e70174eff82c6dde5bb Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Mon, 13 May 2019 13:49:03 +0930 Subject: [PATCH 15/17] Added `vessels` to sample --- .../data/full-valid/resources-note-sample.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index 262e84785..f189eeefd 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -1,4 +1,22 @@ { + "vessels": { + "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d": { + "uuid": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d", + "navigation": { + "position": { + "timestamp": "2015-03-06T16:57:53.643Z", + "$source": "nmea2.II", + "sentence": "RMC", + "value": { + "longitude": 173.1693, + "latitude": -41.156426, + "altitude": 0 + } + } + } + } + }, + "resources": { "notes": { "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021d": { From 05c326ee99e8bedc9849eae17e36f69e6c7f3e61 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Tue, 14 May 2019 12:15:20 +0930 Subject: [PATCH 16/17] update schema to require `anyOf` `region`, `geohash`, `position` --- schemas/groups/resources.json | 423 +++++++++--------- .../full-valid/resources-note-sample.json | 32 +- 2 files changed, 245 insertions(+), 210 deletions(-) diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index f960f8941..49dd0119f 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -10,177 +10,176 @@ "title": "chart", "description": "A holder for charts, each named with their chart code", "patternProperties": { - "(^[A-Za-z0-9_-]{8,}$)": { - "type": "object", - "description": "A chart", - "properties": { - "name": { - "type": "string", - "description": "Chart common name", - "example":"NZ615 Marlborough Sounds" - }, - "identifier": { - "type": "string", - "description": "Chart number", - "example":"NZ615" - }, - "description": { - "type": "string", - "description": "A description of the chart" - }, - "tilemapUrl": { - "type": "string", - "description": "A url to the tilemap of the chart for use in TMS chartplotting apps", - "example":"http://{server}:8080/mapcache/NZ615" - }, - "region": { - "type": "string", - "description": "Region related to note. A pointer to a region UUID. Alternative to geohash" - }, - "geohash": { - "description": "Position related to chart. Alternative to region", - "$ref": "../definitions.json#/definitions/geohash" - }, - "chartUrl": { - "type": "string", - "description": "A url to the chart file's storage location", - "example":"file:///home/pi/freeboard/mapcache/NZ615" - }, - "scale": { - "type": "integer", - "description": "The scale of the chart, the larger number from 1:200000" - }, - "chartLayers": { - "type": "array", - "description": "If the chart format is WMS, the layers enabled for the chart.", - "items": { - "type": "string", - "description": "Identifier for the layer." - } - }, - "bounds": { - "type": "array", - "description": "The bounds of the chart. An array containing the position of the upper left corner, and the lower right corner. Useful when the chart isn't inherently geo-referenced.", - "items": { - "$ref": "../definitions.json#/definitions/position", - "description": "Position of a corner of the chart" + "(^[A-Za-z0-9_-]{8,}$)": { + "type": "object", + "description": "A chart", + "properties": { + "name": { + "type": "string", + "description": "Chart common name", + "example":"NZ615 Marlborough Sounds" + }, + "identifier": { + "type": "string", + "description": "Chart number", + "example":"NZ615" + }, + "description": { + "type": "string", + "description": "A description of the chart" + }, + "tilemapUrl": { + "type": "string", + "description": "A url to the tilemap of the chart for use in TMS chartplotting apps", + "example":"http://{server}:8080/mapcache/NZ615" + }, + "region": { + "type": "string", + "description": "Region related to note. A pointer to a region UUID. Alternative to geohash" + }, + "geohash": { + "description": "Position related to chart. Alternative to region", + "$ref": "../definitions.json#/definitions/geohash" + }, + "chartUrl": { + "type": "string", + "description": "A url to the chart file's storage location", + "example":"file:///home/pi/freeboard/mapcache/NZ615" + }, + "scale": { + "type": "integer", + "description": "The scale of the chart, the larger number from 1:200000" + }, + "chartLayers": { + "type": "array", + "description": "If the chart format is WMS, the layers enabled for the chart.", + "items": { + "type": "string", + "description": "Identifier for the layer." + } + }, + "bounds": { + "type": "array", + "description": "The bounds of the chart. An array containing the position of the upper left corner, and the lower right corner. Useful when the chart isn't inherently geo-referenced.", + "items": { + "$ref": "../definitions.json#/definitions/position", + "description": "Position of a corner of the chart" + } + }, + "chartFormat": { + "type": "string", + "description": "The format of the chart", + "enum": [ + "gif", + "geotiff", + "kap", + "png", + "jpg", + "kml", + "wkt", + "topojson", + "geojson", + "gpx", + "tms", + "wms", + "S-57", + "S-63", + "svg", + "other" + ] + }, + "timestamp": { + "description": "timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" + } } - }, - "chartFormat": { - "type": "string", - "description": "The format of the chart", - "enum": [ - "gif", - "geotiff", - "kap", - "png", - "jpg", - "kml", - "wkt", - "topojson", - "geojson", - "gpx", - "tms", - "wms", - "S-57", - "S-63", - "svg", - "other" - ] - }, - "timestamp": { - "description": "timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" - } } } - } }, "routes": { "type": "object", "title": "route", "description": "A holder for routes, each named with a UUID", "patternProperties": { - "^urn:mrn:signalk: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}$": { - "type": "object", - "description": "A route, named with a UUID", - "properties": { - "name": { - "type": "string", - "description": "Route's common name", - "example":"Nelson Harbour to Adele Is" - }, - "description": { - "type": "string", - "description": "A description of the route" - }, - "distance": { - "description": "Total distance from start to end", - "type": "number", - "units": "m" - }, - "start": { - "type": "string", - "description": "The waypoint UUID at the start of the route" - }, - "end": { - "type": "string", - "description": "The waypoint UUID at the end of the route" - }, - "feature": { - "title": "Feature", - "description": "A Geo JSON feature object which describes the route between the waypoints", - "required": [ - "geometry", - "properties" - ], + "^urn:mrn:signalk: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}$": { + "type": "object", + "description": "A route, named with a UUID", "properties": { - "type": { - "enum": [ - "Feature" - ] - }, - "geometry": { - "title": "LineString", - "properties": { - "type": { - "enum": [ - "LineString" - ] + "name": { + "type": "string", + "description": "Route's common name", + "example":"Nelson Harbour to Adele Is" }, - "coordinates": { - "$ref": "../external/geojson/geometry.json#/definitions/lineString" - } + "description": { + "type": "string", + "description": "A description of the route" + }, + "distance": { + "description": "Total distance from start to end", + "type": "number", + "units": "m" + }, + "start": { + "type": "string", + "description": "The waypoint UUID at the start of the route" + }, + "end": { + "type": "string", + "description": "The waypoint UUID at the end of the route" + }, + "feature": { + "title": "Feature", + "description": "A Geo JSON feature object which describes the route between the waypoints", + "required": [ + "geometry", + "properties" + ], + "properties": { + "type": { + "enum": [ + "Feature" + ] + }, + "geometry": { + "title": "LineString", + "properties": { + "type": { + "enum": [ + "LineString" + ] + }, + "coordinates": { + "$ref": "../external/geojson/geometry.json#/definitions/lineString" + } + } + }, + "properties": { + "type": [ + "object", + "null" + ], + "description": "Additional data of any type", + "additionalProperties": true + }, + "id": { + "FIXME": "may be there, type not known (string? number?)" + } + } + }, + "timestamp": { + "description": "Timestamp of the last update to this data", + "$ref": "../definitions.json#/definitions/timestamp" + }, + "source": { + "description": "Source of this data", + "$ref": "../definitions.json#/definitions/source" } - }, - "properties": { - "type": [ - "object", - "null" - ], - "description": "Additional data of any type", - "additionalProperties": true - }, - "id": { - "FIXME": "may be there, type not known (string? number?)" - } - } - }, - "timestamp": { - "description": "Timestamp of the last update to this data", - "$ref": "../definitions.json#/definitions/timestamp" - }, - "source": { - "description": "Source of this data", - "$ref": "../definitions.json#/definitions/source" } - } - } } }, "notes": { @@ -191,6 +190,17 @@ "^urn:mrn:signalk: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}$": { "type": "object", "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", + "anyOf": [ + { + "required": ["region"] + }, + { + "required": ["position"] + }, + { + "required": ["geohash"] + } + ], "properties": { "title": { "type": "string", @@ -230,7 +240,7 @@ "items": { "$ref": "#/definitions/author" } }, "properties": { - "type": [ "object", "null" ], + "type": [ "object", "null"], "description": "Extension properties placholder for use by applications.", "additionalProperties": true }, @@ -263,60 +273,59 @@ "title": "Feature", "description": "A Geo JSON feature object which describes the regions boundary", "required": [ - "geometry", - "properties" + "geometry", + "properties" ], "properties": { - "type": { - "enum": [ - "Feature" - ] - }, - "geometry": { - "oneOf": [ - { - "title": "Polygon", - "properties": { - "type": { - "enum": [ - "Polygon" - ] - }, - "coordinates": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" - } - } + "type": { + "enum": [ + "Feature" + ] }, - { - "title": "MultiPolygon", - "properties": { - "type": { - "enum": [ - "MultiPolygon" - ] - }, - "coordinates": { - "type": "array", - "items": { - "$ref": "../external/geojson/geometry.json#/definitions/polygon" + "geometry": { + "oneOf": [ + { + "title": "Polygon", + "properties": { + "type": { + "enum": [ + "Polygon" + ] + }, + "coordinates": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + }, + { + "title": "MultiPolygon", + "properties": { + "type": { + "enum": [ + "MultiPolygon" + ] + }, + "coordinates": { + "type": "array", + "items": { + "$ref": "../external/geojson/geometry.json#/definitions/polygon" + } + } + } } - } - } + ] + }, + "properties": { + "type": [ + "object", + "null" + ], + "description": "Additional data of any type", + "additionalProperties": true + }, + "id": { + "FIXME": "may be there, type not known (string? number?)" } - ] - }, - "properties": { - "type": [ - "object", - "null" - ], - "description": "Additional data of any type", - "additionalProperties": true - }, - "id": { - "FIXME": "may be there, type not known (string? number?)" - } - } }, "timestamp": { diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index f189eeefd..8f10d87d4 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -37,7 +37,11 @@ }, "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", "authors": [ - {"name": "John Smith"} + { + "name": "John Smith", + "email": "john.smith@mail.com", + "url": "https://jsmith.org" + } ], "properties": { "draft": true @@ -47,9 +51,31 @@ "label": "note", "type": "manual" } - } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8022d": { + "title": "Little Island", + "description": "Little Island Approach notes.....", + "geohash": "rbejg", + "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8023d": { + "title": "Other Island", + "description": "Other Island Approach notes.....", + "geohash": "rbejg", + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + } } - }, + }, + "version": "1.0.0", "self": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d" } From ef4a0f222cc293663e2d7fa3dda8b495282b827b Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Wed, 15 May 2019 08:36:48 +0930 Subject: [PATCH 17/17] remove `anyOf` requirement for `position`, `region`, `geohash` to return notes to being geo-location independent. --- gitbook-docs/resources_notes.md | 9 ++++++--- schemas/groups/resources.json | 11 ----------- test/data/full-valid/resources-note-sample.json | 13 ++++++++++++- 3 files changed, 18 insertions(+), 15 deletions(-) diff --git a/gitbook-docs/resources_notes.md b/gitbook-docs/resources_notes.md index 49bf3b38a..a09f1819e 100644 --- a/gitbook-docs/resources_notes.md +++ b/gitbook-docs/resources_notes.md @@ -1,10 +1,13 @@ # Notes -Notes are a Signal K resource type that provide a means to attach information to a geographic location or area. They are accessed via the Signal K API path `/signalk/v1/api/resources/notes`. +Notes are a Signal K resource type that provide a means to capture and display additional information in a variety of formats. They are accessed via the Signal K API path `/signalk/v1/api/resources/notes`. -Notes are associated to a geographic location (position), area (Geohash) or feature (`Region`) and therefore at least one of the `position`, `geohash` or `region` properties need to be defined. +Notes can contian both text and / or a link to additional text, images, etc. -Additionally, notes can be associated with other notes to form a collection. This is done by assigning the same `group` value to each of the notes considered to be part of the collection. +They can stand alone or be associated with: +- a geographic location by assigning a value to `position` +- an area by assigning a value to `geohash` or `region` +- other notes by entering the same value in `group` for each of the related notes. --- diff --git a/schemas/groups/resources.json b/schemas/groups/resources.json index 49dd0119f..e95dc80a7 100644 --- a/schemas/groups/resources.json +++ b/schemas/groups/resources.json @@ -190,17 +190,6 @@ "^urn:mrn:signalk: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}$": { "type": "object", "description": "A note about a region, named with a UUID. Notes might include navigation or cruising info, images, or anything", - "anyOf": [ - { - "required": ["region"] - }, - { - "required": ["position"] - }, - { - "required": ["geohash"] - } - ], "properties": { "title": { "type": "string", diff --git a/test/data/full-valid/resources-note-sample.json b/test/data/full-valid/resources-note-sample.json index 8f10d87d4..c5a61dace 100644 --- a/test/data/full-valid/resources-note-sample.json +++ b/test/data/full-valid/resources-note-sample.json @@ -57,6 +57,8 @@ "description": "Little Island Approach notes.....", "geohash": "rbejg", "region": "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8021e", + "properties": {}, + "authors": [], "timestamp": "2015-03-06T16:57:53.643Z", "source": { "label": "note", @@ -72,7 +74,16 @@ "label": "note", "type": "manual" } - } + }, + "urn:mrn:signalk:uuid:c0d79335-4e25-4245-8892-54e8ccc8024d": { + "title": "Simple Note", + "description": "Just a simple, unattached note.....", + "timestamp": "2015-03-06T16:57:53.643Z", + "source": { + "label": "note", + "type": "manual" + } + } } },