Skip to content

Commit

Permalink
Split schema into core and sub schemas
Browse files Browse the repository at this point in the history
$schema is now required, otherwise still compatible with draft-01.

Change-Id: Ie3f8e33485cae97938e4b0d0c03faabaf406eac8
  • Loading branch information
Manuel Stahl committed Oct 22, 2024
1 parent ae9a493 commit 2db8c02
Show file tree
Hide file tree
Showing 12 changed files with 1,354 additions and 42 deletions.
73 changes: 35 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ connection but also supporting RPC (remote procedure call) like
[JSON-RPC](https://de.wikipedia.org/wiki/JSON-RPC).

OGRP is a protocol based on JSON [[RFC4627](#RFC4627)].
Valid messages are defined using [[json-schema](#json-schema)]. The core
protocol can be extended using an application specific schema, see [usage](#usage).

For the use in RPC, zerorpc (<http://zerorpc.dotcloud.com/>) is recommended as a transport mechanism.
Protocols that already provide message framing should use one JSON object per message.
Expand Down Expand Up @@ -105,35 +107,36 @@ Consider the following:
Message specification
=====================

An OGRP message is composed of one JSON object. Two mandatory fields
exist
An OGRP message is composed of one JSON object. Required fields are:
"$schema", "timestamp", "time_reference" and "protocol".

```
msg = {
"protocol": protocol,
"id": id,
{
"$schema": schema,
"protocol": "OGRP1_3",
"timestamp": 101,
"time_reference": "UTC",
...
}
protocol = "OGRP1"
id = string ; lower-case, underscore separated id, e.g. "measurement", ...
schema = "https://fraunhofer-iis.github.io/ogrp/draft-xx/measurement"
```

The additional content in the message is dependant on the message id.
The additional content in the message is dependent on the message schema.
Optional fields are allowed and must be ignored by parsers if unknown
(according to JSON).

Example definitions
-------------------

A message of id 'measurement' for raw measurements of a GNSS receiver,
A message of schema 'measurement' for raw measurements of a GNSS receiver,
e.g. including pseudorange and carrier phase measurements for multiple
satellites on different channels, can look like this:

```
measurement = {
"$schema": "https://fraunhofer-iis.github.io/ogrp/next/schema#",
"protocol": protocol,
"id": "measurement",
"sw_version": int / hex,
"timestamp": float / string, ; (see Representing time and date)
"time_status": time_status,
Expand Down Expand Up @@ -172,53 +175,47 @@ title element in the schema.
Usage
=====

The OGRP core schema can be extended by an application specific schema.
Applications using OGRP for input or output should define the supported messages
as JSON Schema [[json-schema](#json-schema)].

An example how to extend the OGRP core schema:

```JSON
{
"id": "http://example.org/pvt-input-schema#",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Minimum schema for a PVT application",
"type": "object",
"properties": {
"protocol": { "type": "string" },
"id": { "type": "string" },
"timestamp": { "$ref": "http://ogrp.org/definitions/timestamp" },
"channel_measurements": {
"$schema": "https://json-schema.org/draft-07/schema#",
"$id": "https://example.com/my/application",
"title": "My OGRP application",
"allOf": [ { "$ref": "https://fraunhofer-iis.github.io/ogrp/draft-xx/schema#" },
{ "$ref": "#my_element" }
],
"definitions": {
"my_element": {
"$id": "#my_element",
"type": "object",
"properties": {
"satellite_id": {
"my_integer": {
"type": "integer",
"minimum": 1
},
"pseudorange": {
"type": "number"
}
}
},
"satellites": {
"type": "object",
"properties": {
"satellite_id": {
"type": "integer",
"minimum": 1
"my_string": {
"type": "string"
},
"position": {
"type": "object",
"properties": {
"x": { "type": "number" },
"y": { "type": "number" },
"z": { "type": "number" }
}
"my_time": {
"$ref": "https://fraunhofer-iis.github.io/ogrp/draft-xx/schema#gnss_time"
}
}
}
}
}
```

The important line here is `"allOf": [ { "$ref": "https://fraunhofer-iis.github.io/ogrp/draft-xx/schema#" } ],`,
as it imports all properties of the OGRP core schema. An application schema should not link to the "experimental"
schema, as this might often change, but instead use a frozen draft as a baseline.

See also [hyper-schema](http://json-schema.org/hyper-schema) as an example how to extend an existing schema.

Security considerations
=======================

Expand Down
9 changes: 5 additions & 4 deletions draft-01/measurement.ogrp
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
{
"$schema": "https://fraunhofer-iis.github.io/ogrp/draft-01/schema#",
"$schema": "https://fraunhofer-iis.github.io/ogrp/next/schema.json#",
"protocol": "OGRP1_3",
"timestamp": 101,
"time_status": "SYSTEM",
"time_reference": "UTC",
"channel_measurements": [{
"channel_measurements": [
{
"doppler": 1200,
"sw_channel_number": 0,
"hw_channel_number": 0,
Expand All @@ -16,7 +17,7 @@
"snr": 32,
"satellite_id": 1,
"pseudo_range": 20000000,
"time_of_transmission" : 0.0
"time_of_transmission": 0.0
},
{
"doppler": -1100.3,
Expand All @@ -30,7 +31,7 @@
"snr": 45.5,
"satellite_id": 50,
"pseudo_range": 20340000,
"time_of_transmission" : 0.0
"time_of_transmission": 0.0
}
],
"id": "measurement"
Expand Down
144 changes: 144 additions & 0 deletions next/imu.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://fraunhofer-iis.github.io/ogrp/next/imu.json",
"title": "OGRP IMU schema",
"description": "Measurements of an IMU",
"type": "object",
"additionalProperties": true,
"properties": {
"$schema": {
"const": "https://fraunhofer-iis.github.io/ogrp/next/imu.json"
},
"acceleration": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "(m/s^2)"
},
"y": {
"type": "number",
"description": "(m/s^2)"
},
"z": {
"type": "number",
"description": "(m/s^2)"
}
},
"description": "The acceleration vector as reported from the IMU"
},
"angular_rate": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "(rad/s)"
},
"y": {
"type": "number",
"description": "(rad/s)"
},
"z": {
"type": "number",
"description": "(rad/s)"
}
},
"description": "The angular rate as reported from the IMU"
},
"delta_theta": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "(rad)"
},
"y": {
"type": "number",
"description": "(rad)"
},
"z": {
"type": "number",
"description": "(rad)"
}
},
"description": "Integral of angular rate over measurement interval"
},
"delta_velocity": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "(m/s)"
},
"y": {
"type": "number",
"description": "(m/s)"
},
"z": {
"type": "number",
"description": "(m/s)"
}
},
"description": "Integral of acceleration over measurement interval"
},
"magnetic_field": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "(Gs)"
},
"y": {
"type": "number",
"description": "(Gs)"
},
"z": {
"type": "number",
"description": "(Gs)"
}
},
"description": "The magnetic field as reported from the IMU"
},
"gps_correlation_timestamp": {
"type": "object",
"properties": {
"gps_tow": {
"type": "number",
"description": "GPS time of week (s)"
},
"gps_week_number": {
"type": "number",
"description": "GPS week number"
},
"pps_beacon_good": {
"type": "boolean",
"description": "If set, GNSS PPS is present"
},
"gps_time_refresh": {
"type": "number",
"description": "PPS pulse counter"
},
"gps_time_initialized": {
"type": "boolean",
"description": "Is set once upon the first valid GPS time record"
}
},
"required": [
"gnss_tow",
"gnss_week_number",
"pps_beacon_good",
"gps_time_refresh",
"gps_time_initialized"
]
},
"pressure": {
"type": "number",
"description": "Pressure (hPa)"
},
"measurement_interval": {
"type": "number",
"title": "Time since last measurement",
"description": "(s)"
}
}
}
Loading

0 comments on commit 2db8c02

Please sign in to comment.