@bkp7/schema-js-api v0.0.7

Signal K Schema API (Javascript)

This repository contains the (working) specification for the Signal K Schema API, writen in Javascript.

Signal K

The Free and Open Source universal marine data exchange.

Signal K is about publishing a common modern and open data format for marine use. A format for the modern boat, compatible with NMEA, friendly to WiFi, cellphones, tablets, and the Internet. A format available to everyone, where anyone can contribute.

Find out more at signalk.org. Then join the mailinglist by sending an email to signalk+subscribe@googlegroups.com or follow the discussion via the Signal K Google Groups forum.

Contents

• Install
• Signal K API
  • FullSignalK Class(#FullSignalK Class)
  • Validation functions(#Validation functions)

Install

npm install @bkp7/schema-js-api

Getting Started

var skApi = require('@bkp7/schema-js-api')
var skJson = {
  "self": "urn:mrn:imo:mmsi:366982330",
  "version": "1.0.0",
  "vessels": {
    "urn:mrn:imo:mmsi:366982330": {
      "uuid": "urn:mrn:signalk:uuid:b7590868-1d62-47d9-989c-32321b349fb9",
}}};
console.log(skApi.validateFull(skJson).valid) // => true

Signal K API

###Full Signal K Object

new FullSignalK(id ,defaults) -> Object

Initialise the fullSignalK object with options as required. Defaults are: id = "", type = vessel, defaults = TODO

var sk = fullSignalK("366982330", "vessel", TODO)

If id is supplied, it will be added to the schema within the type (default is vessel) specified. It will also be used to identify "self". The result will be valid full Signal K json. If no id is supplied an invalid skeleton will be created and TODO - what happens then?

.retrieve

Returns the valid full Signal K message

.addDelta(delta)

Adds the supplied delta to the full SignalK message

.updateLastModified(contextKey)

TODO

.pruneContexts(seconds)

TODO

.deleteContext(contextKey)

TODO

.addUpdates(context, contextPath, updates)

TODO

.addUpdate(context, contextPath, update)

TODO

.updateDollarSource(context, dollarSource, timestamp)

TODO

.updateSource(context, source, timestamp)

TODO

index.js API

Validation Functions

All validation functions return a results object:

{
  valid: true/false,
  err: ""
  errors: [...],
  missing: [...],
  toString(),
}

• valid is a boolean indicating the test result
• err is a summarised human friendly string representation of the errors. Note that err can have contents even when the message is valid due to errors in oneOff/anyOff directives. Do not use err==='' as a test for validity
• errors/missing are arrays containing detailed information, see tv4 documentation for details
• toString is a function which (doesn't work due to a bug in tv4) should return either 'valid' or an explanation of the error(s).

validateFull(tree)

validateVessel(vesselData)

validateDelta(delta, ignoreContext)

validateWithSchema(msg, schemaName)

Validation functions can be called either directly or via chai.

const skSchemaApi = require('../src/index.js')
var msg = {
  "self": "urn:mrn:imo:mmsi:366982330",
  "version": "1.0.0",
  "vessels": {
    "urn:mrn:imo:mmsi:366982330": {
      "uuid": "urn:mrn:signalk:uuid:b7590868-1d62-47d9-989c-32321b349fb9",
}}};
var result = skSchemaApi.validateFull(msg);
console.log(result.valid); // true

var chai = require('chai'); chai.Should();
chai.use(require('../dist/').chaiModule);
const skSchemaApi = require('../src/index.js')
var msg = {
  "self": "urn:mrn:imo:mmsi:366982330",
  "version": "1.0.0",
  "vessels": {
    "urn:mrn:imo:mmsi:366982330": {
      "uuid": "urn:mrn:signalk:uuid:b7590868-1d62-47d9-989c-32321b349fb9",
}}};

console.assert(msg.should.be.validSignalK);

NB The validate functions require that you have a set of schema files to validate agains located in schemas folder. These can be found in the SignalK specification reposity here

Helper Functions

deltaToFullVessel(delta)

returns a Signal K vessel object

deltaToFull(delta)

returns a full Signal K message

fillIdentityField(vesselData, identity)

TODO

fillIdentity(full)

TODO

chaiModule(chai, utils)

TODO

subSchemas()

returns an object containing all the subSchemas

units()

returns the Json Schema for units

{
  "type": "string",
  "description": "Allowed units of physical quantities. Units should be (derived) SI units where possible.",
  "properties": {
    "deg": {
      "display": "\u00b0",
      "quantity": "Angle",
      "quantityDisplay": "\u2220",
      "description": "Latitude or longitude in decimal degrees"
    },
    "V": {
      "display": "V",
      "quantity": "Voltage",
      "quantityDisplay": "V",
      "description": "Electrical potential in volt"
    },
    ...
  }
}

metadata

returns an object containing a list of all Signal K keys along with metadata about each key including description, etc.

{
  "/vessels/*": {
    "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"
  },
  "/vessels/*/communication/callsignVhf": {
    "description": "Callsign for VHF communication"
  },
  "/vessels/*/environment/outside/temperature": {
    "units": "K",
    "description": "Current outside air temperature"
  },
  ...
}

FullsignalK

TODO

fakeMmsiId()

returns a string containing a valid (but fake) mmsi number:

"urn:mrn:imo:mmsi:230099999"

getSourceId(source)

TODO

keyForSourceIdPath(sourceID, path)

TODO

getUnits(path)

TODO

getMetadata(path)

TODO

getAISShipTypeName(id)

TODO

getAtonTypeName(id)

TODO

delta.js API

deltaToNested(delta)

TODO

Contributing

Include test data and tests

See the tests here.

Any changes should include some test data that use the proposed changes with real world data.

Any schema changes should be checked against the existing set of tests:

• install Node (and npm with it)
• install dependencies with npm install
• run the tests with npm test

The master branch contains the latest version of the API. When making changes, please clone this repo to your local machine and set up a new branch (git checkout -b branch_name). Send in a pull request for every change, put it up for discussion in the mailing list and then (when a consensus has been reached) merge it into master.