diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index 23475d118b..6fa1b2469a 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -71,3 +71,11 @@ jobs: run: | echo Pubber output logs: cat pubber.out || true + + docs: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v2 + - name: schema docs + run: bin/gendocs check diff --git a/bin/gendocs b/bin/gendocs new file mode 100755 index 0000000000..e9fc9152c2 --- /dev/null +++ b/bin/gendocs @@ -0,0 +1,53 @@ +#!/bin/bash -e + +ROOT_DIR=$(realpath $(dirname $0)/..) +cd $ROOT_DIR + +OUTPUT_DIR=$ROOT_DIR/gencode/docs +TMP_DIR=$ROOT_DIR/tmp/schema + +schema_files=`ls schema/*.json` + +if [ "$1" == check ]; then + mkdir -p $TMP_DIR + sha1sum $schema_files > $TMP_DIR/schema.hash + diff $TMP_DIR/schema.hash $OUTPUT_DIR/schema.hash + echo Schema hashes in $OUTPUT_DIR/schema.hash are up-to-date. + git diff --exit-code $OUTPUT_DIR/schema.hash + exit 0 +fi + +rm -rf $OUTPUT_DIR +mkdir -p $OUTPUT_DIR + +sha1sum $schema_files > $OUTPUT_DIR/schema.hash + +# Make a copy of the schema files into a tmp folder for any pre generator fixes +rm -rf $TMP_DIR +mkdir -p $TMP_DIR +cp -r schema/. $TMP_DIR + +# Remove file: prefix from references so document generator works +find $TMP_DIR -type f -exec sed -i '' 's/file://' {} \; + +schemas="state event_system event_pointset event_discovery config metadata envelope" + +for schema in $schemas; do + python3 bin/gendocs.py $schema $TMP_DIR $OUTPUT_DIR +done + +rm -rf $TMP_DIR + +# Convert github doc links to relative links for hosted/downloaded docs +#RELATIVE_LINK="..\/" +#find $OUTPUT_DIR -type f -exec sed -i '' "s/$ABSOLUTE_LINK/$RELATIVE_LINK/" {} \; +#ABSOLUTE_LINK="https:\/\/github.com\/faucetsdn\/udmi\/blob\/master\/docs\/" + +# Create index page with links to different schemas +cp etc/schema_index_template.html $OUTPUT_DIR/index.html + +for schema in $schemas; do + sed -i '' "s//\ +
$schema<\/a><\/div>/"\ + $OUTPUT_DIR/index.html +done diff --git a/bin/gendocs.py b/bin/gendocs.py new file mode 100644 index 0000000000..7401a73e7c --- /dev/null +++ b/bin/gendocs.py @@ -0,0 +1,18 @@ +import sys + +from json_schema_for_humans.generate import generate_from_filename +from json_schema_for_humans.generation_configuration import GenerationConfiguration + +config = GenerationConfiguration(copy_css=True, + expand_buttons=True, + minify=False, + link_to_reused_ref=False) + +schema = sys.argv[1] +source_dir = sys.argv[2] +output_dir = sys.argv[3] + +schema_path = source_dir + "/" + schema + ".json" +output_path = output_dir + "/" + schema + ".html" + +generate_from_filename(schema_path, output_path, config=config) diff --git a/etc/requirements.txt b/etc/requirements.txt new file mode 100644 index 0000000000..454ceb70a4 --- /dev/null +++ b/etc/requirements.txt @@ -0,0 +1 @@ +json-schema-for-humans \ No newline at end of file diff --git a/etc/schema_index_template.html b/etc/schema_index_template.html new file mode 100644 index 0000000000..0c8226b9fa --- /dev/null +++ b/etc/schema_index_template.html @@ -0,0 +1,26 @@ + + + + + + + + + + + + UDMI Schema + + +

UDMI Schema

+
+ + + \ No newline at end of file diff --git a/gencode/docs/config.html b/gencode/docs/config.html new file mode 100644 index 0000000000..b4a4491a57 --- /dev/null +++ b/gencode/docs/config.html @@ -0,0 +1,6 @@ + Config

Config

Type: object

The config block controls a device's intended behavior. Read more: https://github.com/faucetsdn/udmi/blob/master/docs/config.md

No Additional Properties

root timestamp
Type: string

RFC 3339 timestamp the configuration was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: integer

Major version of the UDMI schema

Value must be greater or equal to 1 and lesser or equal to 1

root system
Type: object
No Additional Properties

root system min_loglevel
Type: integer

The minimum loglevel for reporting log messages below which log entries should not be sent.

Value must be greater or equal to 100 and lesser or equal to 800

root system auth_key
Type: object
No Additional Properties

root system auth_key private
Type: string

root gateway
Type: object
No Additional Properties

root gateway proxy_ids
Type: array of string

An array of all the device IDs which are bound to the device

Each item of this array must be:

root gateway proxy_ids items
Type: string
Must match regular expression: ^[A-Z]{3}-[1-9][0-9]{0,2}$

Example:

[
+    "AHU-22"
+]
+

root localnet
Type: object
No Additional Properties

root localnet subsystem
Type: object

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z0-9-]+$
root localnet subsystem ^[a-z0-9-]+$
Type: object
No Additional Properties

root blobset
Type: object
No Additional Properties

root blobset blobs
Type: object
No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root blobset blobs config_blobset_blob.json#
Type: object
No Additional Properties

root pointset
Type: object
No Additional Properties

root pointset state_etag
Type: string

Must be at most 32 characters long

root pointset set_value_expiry
Type: string

An expiry for the the device reverts to its operational state, and sends a state update to notify the cloud of the state change. Read more: https://github.com/faucetsdn/udmi/blob/master/docs/writeback.md

root pointset sample_limit_sec
Type: integer

Minimum time between sample updates for the device (including complete and COV updates). Updates more frequent than this should be coalesced into one update.

Value must be greater or equal to 1 and lesser or equal to 86400

root pointset sample_rate_sec
Type: integer

Maximum time between samples for the device to send out a complete update. It can send out updates more frequently than this.

Value must be greater or equal to 1 and lesser or equal to 86400

root pointset points
Type: object

The points defined in this dictionary is the authoritative source indicating the representative points for the device (in both telemetry and state messages). Read more: https://github.com/faucetsdn/udmi/blob/master/docs/pointset.md

 No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root pointset points config_pointset_point.json#
Type: object
No Additional Properties

root pointset points Point Pointset Config set_value
Type: object

Used for cloud writeback functionality, this field specifies the value for a given point in the device's current units.
Example:

22.4
+
\ No newline at end of file diff --git a/gencode/docs/envelope.html b/gencode/docs/envelope.html new file mode 100644 index 0000000000..8827578c3c --- /dev/null +++ b/gencode/docs/envelope.html @@ -0,0 +1 @@ + Envelope

Envelope

Type: object

The UDMI envelope is not a message itself, per se, but the attributes and other information that is delivered along with a message. Read more: https://github.com/faucetsdn/udmi/blob/master/docs/envelope.md

root deviceId
Type: string
Must match regular expression: ^[A-Z]{2,6}-[0-9]{1,6}$

root deviceNumId
Type: string
Must match regular expression: ^[0-9]+$

root deviceRegistryId
Type: string
Must match regular expression: ^[a-zA-Z][-a-zA-Z0-9._+~%]*[a-zA-Z0-9]$

root projectId
Type: string
Must match regular expression: ^([.a-z]+:)?[a-z][-a-z0-9]*[a-z0-9]$

root subFolder
Type: enum (of string)

Must be one of:

  • "config"
  • "discovery"
  • "system"
  • "metadata"
  • "pointset"
  • "state"

Additional Properties of any type are allowed.

root additionalProperties
Type: object
\ No newline at end of file diff --git a/gencode/docs/event_discovery.html b/gencode/docs/event_discovery.html new file mode 100644 index 0000000000..4dd8c31cac --- /dev/null +++ b/gencode/docs/event_discovery.html @@ -0,0 +1,2 @@ + Discovery

Discovery

Type: object

Read more: https://github.com/faucetsdn/udmi/blob/master/docs/discovery.md

 No Additional Properties

root timestamp
Type: string

RFC 3339 timestamp the discover telemetry event was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: enum (of integer)

Major version of the UDMI schema

Must be one of:

  • 1

root families
Type: object
No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root families event_discovery_family.json
Type: object
No Additional Properties

root families Family Discovery Event id
Type: string
Must match regular expression: ^[-_.:/0-9a-zA-Z]+$

\ No newline at end of file diff --git a/gencode/docs/event_pointset.html b/gencode/docs/event_pointset.html new file mode 100644 index 0000000000..016654d7d7 --- /dev/null +++ b/gencode/docs/event_pointset.html @@ -0,0 +1,5 @@ + Pointset Event

Pointset Event

Type: object

A set of points reporting telemetry data

 No Additional Properties

root timestamp
Type: string

RFC 3339 timestamp the telemetry event was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: integer

Major version of the UDMI schema

Value must be greater or equal to 1 and lesser or equal to 1

root points
Type: object

Collection of point names, defining the representative point set for this device.

 No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root points event_pointset_point.json#
Type: object

Object representation for for a single point

 No Additional Properties

root points Point Pointset Event present_value
Type: object

The specific point data reading
Examples:

24.1
+
true
+
4
+
\ No newline at end of file diff --git a/gencode/docs/event_system.html b/gencode/docs/event_system.html new file mode 100644 index 0000000000..248cd0afba --- /dev/null +++ b/gencode/docs/event_system.html @@ -0,0 +1,6 @@ + System Event

System Event

Type: object
No Additional Properties

root timestamp
Type: string

RFC 3339 timestamp the event payload was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: integer

Major version of the UDMI schema

Value must be greater or equal to 1 and lesser or equal to 1

root logentries
Type: array

Each item of this array must be:

root logentries entry
Type: object
No Additional Properties

root logentries Entry message
Type: string

A one-line representation of the triggering condition.
Example:

"Point is not writable"
+

root logentries Entry detail
Type: string

An optional be multi-line entry which can include more detail, e.g. a complete program stack-trace.

root logentries Entry category
Type: string

A device-specific representation of which sub-system the message comes from. In a Java environment, for example, it would be the fully qualified path name of the Class triggering the message.

Must match regular expression: ^[a-z][._a-zA-Z]*[a-zA-Z]$
Example:

"state.pointset.points.config.invalid"
+

root logentries Entry timestamp
Type: string

Ttimestamp the condition was triggered, or most recently updated. It might be different than the top-level message timestamp if the condition is not checked often or is sticky until it's cleared.
Example:

"2018-08-26T21:39:28.364Z"
+

root logentries Entry level
Type: integer

The status level should conform to the numerical Stackdriver LogEntry levels. The DEFAULT value of 0 is not allowed (lowest value is 100, maximum 800).

Value must be greater or equal to 100 and lesser or equal to 800 and a multiple of 1


Example:

600
+
\ No newline at end of file diff --git a/gencode/docs/index.html b/gencode/docs/index.html new file mode 100644 index 0000000000..12674bda4b --- /dev/null +++ b/gencode/docs/index.html @@ -0,0 +1,26 @@ + + + + + + + + + + + + UDMI Schema + + +

UDMI Schema

+
+
state
event_system
event_pointset
event_discovery
config
metadata
envelope
+ + diff --git a/gencode/docs/metadata.html b/gencode/docs/metadata.html new file mode 100644 index 0000000000..61740614ce --- /dev/null +++ b/gencode/docs/metadata.html @@ -0,0 +1,9 @@ + Metadata

Metadata

Type: object
No Additional Properties

root timestamp
Type: string

RFC 3339 timestamp the metadata was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: integer

Major version of the UDMI schema

Value must be greater or equal to 1 and lesser or equal to 1

root hash
Type: string

Automatically generated field that contains the hash of file contents.

Must match regular expression: ^[0-9a-z]{8}$

root cloud
Type: object

Information specific to how the device communicates with the cloud.

 No Additional Properties

root cloud auth_type
Type: enum (of string)

The key type used for cloud communication.

Must be one of:

  • "ES256"
  • "ES256_X509"
  • "RS256"
  • "RS256_X509"

root cloud device_key
Type: boolean

root cloud is_gateway
Type: boolean

If the device functions as an IoT Gateway, proxying for other devices using a single logical connection

root system
Type: object

High-level sytem informaiton about the device.

 No Additional Properties

root system location
Type: object

Properties the expected physical location of the device.

 No Additional Properties

root system location site
Type: string

The site name according to the site model in which a device is installed in

Must match regular expression: ^[A-Z]{2}-[A-Z]{3}-[A-Z0-9]{2,9}$
Example:

"US-SFO-XYY"
+

root system location section
Type: string
Must match regular expression: ^[A-Z0-9-]+$

root system location position
Type: object
No Additional Properties

root system location position x
Type: number

root system location position y
Type: number

root system physical_tag
Type: object

Information used to print a physical QR code label.

 No Additional Properties

root system physical_tag asset
Type: object
No Additional Properties

root system physical_tag asset guid
Type: string
Must match regular expression: ^[a-z]+://[-0-9a-zA-Z_$]+$

root system physical_tag asset site
Type: string
Must match regular expression: ^[A-Z]{2}-[A-Z]{3}-[A-Z0-9]{2,9}$

root system physical_tag asset name
Type: string
Must match regular expression: ^[A-Z]{2,6}-[0-9]{1,6}$

root system aux
Type: object
No Additional Properties

root system aux suffix
Type: string
Must match regular expression: ^[a-zA-Z0-9-]+$

root gateway
Type: object

Read more: https://github.com/faucetsdn/udmi/blob/master/docs/gateway.md

 No Additional Properties

root gateway oneOf item 0
Type: object

The following properties are required:

  • gateway_id
root gateway oneOf item 1
Type: object

The following properties are required:

  • proxy_ids

root gateway gateway_id
Type: string

Present in devices which are proxied by a gateway, this identifies the device ID of the gateway the device is bound to

Must match regular expression: ^[A-Z]{2,6}-[0-9]{1,6}$
Example:

"GAT-100"
+

root gateway subsystem
Type: string
Must match regular expression: ^[a-z0-9-]+$

root gateway proxy_ids
Type: array of string

Present in devices which are IoT gateways, this is an array of all the device IDs which are bound to the device

Each item of this array must be:

root gateway proxy_ids items
Type: string
Must match regular expression: ^[A-Z]{2,6}-[0-9]{1,6}$

Example:

[
+    "AHU-22"
+]
+

root localnet
Type: object
No Additional Properties

root localnet subsystem
Type: object
No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z0-9-]+$
root localnet subsystem metadata_localnet_subsystem.json
Type: object
No Additional Properties

root pointset
Type: object

Pointset representing the abstract system expectation for what the device should be doing, and how it should be configured and operated. This block specifies the expected points that a device holds

 No Additional Properties

root pointset points
Type: object

Information about a specific point name of the device.

 No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root pointset points metadata_pointset_point.json#
Type: object

Information about a specific point name of the device.

 No Additional Properties

root pointset points Point Pointset Metadata units
Type: enum (of string)

Expected unit configuration for the point.

Must be one of:

  • "Square-meters"
  • "Square-feet"
  • "Milliamperes"
  • "Amperes"
  • "Ohms"
  • "Volts"
  • "Kilo-volts"
  • "Mega-volts"
  • "Volt-amperes"
  • "Kilo-volt-amperes"
  • "Mega-volt-amperes"
  • "Volt-amperes-reactive"
  • "Kilo-volt-amperes-reactive"
  • "Mega-volt-amperes-reactive"
  • "Volt-amperes-reactive-hours"
  • "Degrees-phase"
  • "Power-factor"
  • "Joules"
  • "Kilojoules"
  • "Watt-hours"
  • "Kilowatt-hours"
  • "BTUs"
  • "Therms"
  • "Ton-hours"
  • "Joules-per-kilogram-dry-air"
  • "BTUs-per-pound-dry-air"
  • "Cycles-per-hour"
  • "Cycles-per-minute"
  • "Hertz"
  • "Grams-of-water-per-kilogram-dry-air"
  • "Percent-relative-humidity"
  • "Millimeters"
  • "Meters"
  • "Inches"
  • "Feet"
  • "Watts-per-square-foot"
  • "Watts-per-square-meter"
  • "Lumens"
  • "Luxes"
  • "Foot-candles"
  • "Kilograms"
  • "Pounds-mass"
  • "Tons"
  • "Kilograms-per-second"
  • "Kilograms-per-minute"
  • "Kilograms-per-hour"
  • "Pounds-mass-per-minute"
  • "Pounds-mass-per-hour"
  • "Watts"
  • "Kilowatts"
  • "Megawatts"
  • "BTUs-per-hour"
  • "Horsepower"
  • "Tons-refrigeration"
  • "Pascals"
  • "Kilopascals"
  • "Bars"
  • "Pounds-force-per-square-inch"
  • "Centimeters-of-water"
  • "Inches-of-water"
  • "Millimeters-of-mercury"
  • "Centimeters-of-mercury"
  • "Inches-of-mercury"
  • "Degrees-Celsius"
  • "Degrees-Kelvin"
  • "Degrees-Fahrenheit"
  • "Degree-days-Celsius"
  • "Degree-days-Fahrenheit"
  • "Years"
  • "Months"
  • "Weeks"
  • "Days"
  • "Hours"
  • "Minutes"
  • "Seconds"
  • "Meters-per-second"
  • "Kilometers-per-hour"
  • "Feet-per-second"
  • "Feet-per-minute"
  • "Miles-per-hour"
  • "Cubic-feet"
  • "Cubic-meters"
  • "Imperial-gallons"
  • "Liters"
  • "Us-gallons"
  • "Cubic-feet-per-minute"
  • "Cubic-meters-per-second"
  • "Imperial-gallons-per-minute"
  • "Liters-per-second"
  • "Liters-per-minute"
  • "Us-gallons-per-minute"
  • "Degrees-angular"
  • "Degrees-Celsius-per-hour"
  • "Degrees-Celsius-per-minute"
  • "Degrees-Fahrenheit-per-hour"
  • "Degrees-Fahrenheit-per-minute"
  • "No-units"
  • "Parts-per-million"
  • "Parts-per-billion"
  • "Percent"
  • "Percent-per-second"
  • "Per-minute"
  • "Per-second"
  • "Psi-per-Degree-Fahrenheit"
  • "Radians"
  • "Revolutions-per-minute"
  • "Currency1"
  • "Currency2"
  • "Currency3"
  • "Currency4"
  • "Currency5"
  • "Currency6"
  • "Currency7"
  • "Currency8"
  • "Currency9"
  • "Currency10"
  • "Square-inches"
  • "Square-centimeters"
  • "BTUs-per-pound"
  • "Centimeters"
  • "Pounds-mass-per-second"
  • "Delta-Degrees-Fahrenheit"
  • "Delta-Degrees-Kelvin"
  • "Kilohms"
  • "Megohms"
  • "Millivolts"
  • "Kilojoules-per-kilogram"
  • "Megajoules"
  • "Joules-per-degree-Kelvin"
  • "Joules-per-kilogram-degree-Kelvin"
  • "Kilohertz"
  • "Megahertz"
  • "Per-hour"
  • "Milliwatts"
  • "Hectopascals"
  • "Millibars"
  • "Cubic-meters-per-hour"
  • "Liters-per-hour"
  • "Kilowatt-hours-per-square-meter"
  • "Kilowatt-hours-per-square-foot"
  • "Megajoules-per-square-meter"
  • "Megajoules-per-square-foot"
  • "Watts-per-square-meter-Degree-Kelvin"
  • "Cubic-feet-per-second"
  • "Percent-obscuration-per-foot"
  • "Percent-obscuration-per-meter"
  • "Milliohms"
  • "Megawatt-hours"
  • "Kilo-BTUs"
  • "Mega-BTUs"
  • "Kilojoules-per-kilogram-dry-air"
  • "Megajoules-per-kilogram-dry-air"
  • "Kilojoules-per-degree-Kelvin"
  • "Megajoules-per-degree-Kelvin"
  • "Newton"
  • "Grams-per-second"
  • "Grams-per-minute"
  • "Tons-per-hour"
  • "Kilo-BTUs-per-hour"
  • "Hundredths-seconds"
  • "Milliseconds"
  • "Newton-meters"
  • "Millimeters-per-second"
  • "Millimeters-per-minute"
  • "Meters-per-minute"
  • "Meters-per-hour"
  • "Cubic-meters-per-minute"
  • "Meters-per-second-per-second"
  • "Amperes-per-meter"
  • "Amperes-per-square-meter"
  • "Ampere-square-meters"
  • "Farads"
  • "Henrys"
  • "Ohm-meters"
  • "Siemens"
  • "Siemens-per-meter"
  • "Teslas"
  • "Volts-per-degree-Kelvin"
  • "Volts-per-meter"
  • "Webers"
  • "Candelas"
  • "Candelas-per-square-meter"
  • "Degrees-Kelvin-per-hour"
  • "Degrees-Kelvin-per-minute"
  • "Joule-seconds"
  • "Square-meters-per-Newton"
  • "Kilograms-per-cubic-meter"
  • "Newton-seconds"
  • "Newtons-per-meter"
  • "Watts-per-meter-per-degree-Kelvin"

root pointset points Point Pointset Metadata ref
Type: string

A local network reference for a point, e.g. BACnet address or Modbus register
Examples:

"AI3.Present_Value"
+
"400070"
+
\ No newline at end of file diff --git a/gencode/docs/schema.hash b/gencode/docs/schema.hash new file mode 100644 index 0000000000..3faae209b9 --- /dev/null +++ b/gencode/docs/schema.hash @@ -0,0 +1,34 @@ +77dcb0fef471c7418306353a2cbb802b72679255 schema/common.json +d3ce94976a6c3f23fee2c41e2347101cf7e36c01 schema/config.json +2af1ef06afc81e2e6d0286afceb66a5dcbea999a schema/config_blobset.json +e9151e7c87ac1e880a1312cc7e49b435be6cbd0a schema/config_blobset_blob.json +4e316a61bf169d000474c8787a40b40ebee17eee schema/config_gateway.json +2701c5a05dd612d32b60d185948c80edaf7318b6 schema/config_localnet.json +7a8bf6da800d28f9acc3e2e10e6d6a9694b2da24 schema/config_pointset.json +5df53504219c90a3cc89c9e2129afe6d6c91ab58 schema/config_pointset_point.json +ac6e9424c5d367dbb7101a4160c7847321968457 schema/config_system.json +e725fac71ca69ee42362e215fef0e49ef081dd98 schema/envelope.json +c8c82c16099231d81bda86e0cb6a47bc0e607d1e schema/event.json +86d2445f4be9256b10f1053ce1f440ffe83f4706 schema/event_audit.json +6ce954ba12235ce4ea1e342045c9f6a64211375b schema/event_discovery.json +90ba67e6f487cdb47b2b92cf663186a200a0a829 schema/event_discovery_family.json +b00bb8e5305001df21c8c4f7d24ec42e23580d96 schema/event_pointset.json +daaa5b31ad385c27024cc915412e0f27d5102306 schema/event_pointset_point.json +5586b408ff7a59210c2c6a3a1f883583b30dae4e schema/event_system.json +dc1d3c4896ed03f645db0942dd47095188e5adf6 schema/metadata.json +ec5e11c52c11edc9d3398859cfa89f4e740fe6fb schema/metadata_cloud.json +7ade1337df6951cc645421512d3664b7e5adeced schema/metadata_gateway.json +e11e038b06c5778a5050c6a1bcf4f8b6e6fd8b89 schema/metadata_localnet.json +8aab0be292001048f19c79ec1b0a0726db297fab schema/metadata_localnet_subsystem.json +76f0a73a81c19a913125ba8113383b94730aabf1 schema/metadata_pointset.json +320bb8d21a21537c94b09acd974f4d8079490144 schema/metadata_pointset_point.json +28e5fb6ebe6e4824934161d5b5e20ca7881133c0 schema/metadata_system.json +5b497358a2253e8d72cf3ca5d8af2740e86149e0 schema/properties.json +0514d620dd98474fc42a2e19f08b2bc985285a99 schema/state.json +68e22a220aa6e2a8d30e68f0155134a000344e24 schema/state_blobset.json +e5ab83b6e18a5dc0673e43e9f5acd1d5b13636a7 schema/state_blobset_blob.json +f7b02ad613c0c3816728ad2d3237158ac9a6472e schema/state_gateway.json +920d82f3da7788f45ba6cf018beecd4076666b91 schema/state_pointset.json +22d16398260a743c3feea1d41d2fff924ed4c8d3 schema/state_pointset_point.json +b9542e4aecd1e21943702993612bba35b5ce7efe schema/state_system.json +d435fc6b94c3e19cd13535d3a1371af367aab355 schema/units.json diff --git a/gencode/docs/schema_doc.css b/gencode/docs/schema_doc.css new file mode 100644 index 0000000000..83897d896b --- /dev/null +++ b/gencode/docs/schema_doc.css @@ -0,0 +1,180 @@ +body { + font: 16px/1.5em "Overpass", "Open Sans", Helvetica, sans-serif; + color: #333; + font-weight: 300; + padding: 40px; +} + +.btn.btn-link { + font-size: 18px; +} + +.jsfh-animated-property { + animation: eclair; + animation-iteration-count: 1; + animation-fill-mode: forwards; + animation-duration: .75s; + +} + +@keyframes eclair { + 0%,100% { + transform: scale(1); + } + 50% { + transform: scale(1.03); + } +} + +.btn.btn-primary { + margin: 10px; +} + +.btn.example-show.collapsed:before { + content: "show" +} + +.btn.example-show:before { + content: "hide" +} + +.description.collapse:not(.show) { + max-height: 100px !important; + overflow: hidden; + + display: -webkit-box; + -webkit-line-clamp: 2; + -webkit-box-orient: vertical; +} + +.description.collapsing { + min-height: 100px !important; +} + +.collapse-description-link.collapsed:after { + content: '+ Read More'; +} + +.collapse-description-link:not(.collapsed):after { + content: '- Read Less'; +} + +.badge { + font-size: 100%; + margin-bottom: 0.5rem; + margin-top: 0.5rem; +} + +.badge.value-type { + font-size: 120%; + margin-right: 5px; + margin-bottom: 10px; +} + + +.badge.default-value { + font-size: 120%; + margin-left: 5px; + margin-bottom: 10px; +} + +.badge.restriction { + display: inline-block; +} + +.badge.required-property,.badge.deprecated-property,.badge.pattern-property,.badge.no-additional { + font-size: 100%; + margin-left: 10px; +} + +.accordion div.card:only-child { + border-bottom: 1px solid rgba(0, 0, 0, 0.125); +} + +.examples { + padding: 1rem !important; +} + +.examples pre { + margin-bottom: 0; +} + +.highlight.jumbotron { + padding: 1rem !important; +} + +.generated-by-footer { + margin-top: 1em; + text-align: right; +} + +/* From https://github.com/richleland/pygments-css/blob/master/friendly.css, see https://github.com/trentm/python-markdown2/wiki/fenced-code-blocks */ +.highlight { background: #e9ecef; } /* Changed from #f0f0f0 in the original style to be the same as bootstrap's jumbotron */ +.highlight .hll { background-color: #ffffcc } +.highlight .c { color: #60a0b0; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #888888 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #40a070 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #40a070 } /* Literal.Number.Bin */ +.highlight .mf { color: #40a070 } /* Literal.Number.Float */ +.highlight .mh { color: #40a070 } /* Literal.Number.Hex */ +.highlight .mi { color: #40a070 } /* Literal.Number.Integer */ +.highlight .mo { color: #40a070 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #40a070 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/gencode/docs/schema_doc.min.js b/gencode/docs/schema_doc.min.js new file mode 100644 index 0000000000..0d9c7882d8 --- /dev/null +++ b/gencode/docs/schema_doc.min.js @@ -0,0 +1 @@ +function flashElement(t){myElement=document.getElementById(t),myElement.classList.add("jsfh-animated-property"),setTimeout(function(){myElement.classList.remove("jsfh-animated-property")},1e3)}function setAnchor(t){history.pushState({},"",t)}function anchorOnLoad(){let t=window.location.hash.split("?")[0].split("&")[0];"#"===t[0]&&(t=t.substr(1)),t.length>0&&anchorLink(t)}function anchorLink(t){$("#"+t).parents().addBack().filter(".collapse:not(.show), .tab-pane, [role='tab']").each(function(t){if($(this).hasClass("collapse"))$(this).collapse("show");else if($(this).hasClass("tab-pane")){const t=$("a[href='#"+$(this).attr("id")+"']");t&&t.tab("show")}else"tab"===$(this).attr("role")&&$(this).tab("show")}),setTimeout(function(){let e=document.getElementById(t);e&&(e.scrollIntoView({block:"center",behavior:"smooth"}),setTimeout(function(){flashElement(t)},500))},1e3)}$(document).on("click",'a[href^="#"]',function(t){t.preventDefault(),history.pushState({},"",this.href)}); \ No newline at end of file diff --git a/gencode/docs/state.html b/gencode/docs/state.html new file mode 100644 index 0000000000..7c24b13483 --- /dev/null +++ b/gencode/docs/state.html @@ -0,0 +1,19 @@ + State

State

Type: object
No Additional Properties

root timestamp
Type: string

RFC 3339 Timestamp the state payload was generated
Example:

"2019-01-17T14:02:29.364Z"
+

root version
Type: integer

Major version of the UDMI schema

Value must be greater or equal to 1 and lesser or equal to 1

root system
Type: object
No Additional Properties

root system make_model
Type: string

The make and model of the physical device
Examples:

"Delta Controls O3-DIN-SRC"
+
"Arup Gateway"
+

root system serial_no
Type: string

The serial number of the physical device
Examples:

"A1B2C3D4"
+
"00001"
+

root system auth_key
Type: object
No Additional Properties

root system auth_key private_hash
Type: string

root system firmware
Type: object

Information about the physical device firmware

 No Additional Properties

root system firmware version
Type: string

Version of the local firmware

root system last_config
Type: string

Time from the timestamp field of the last successfully parsed config message (not the timestamp the message was received/processed).
Example:

"2019-01-17T14:02:29.364Z"
+

root system operational
Type: boolean

root system statuses
Type: object

A map of 'sticky' conditions that are keyed on a value that can be used to manage updates by a particular (device dependent) subsystem.

 No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root system statuses entry
Type: object
No Additional Properties

root system statuses Entry message
Type: string

A one-line representation of the triggering condition.
Example:

"Point is not writable"
+

root system statuses Entry detail
Type: string

An optional be multi-line entry which can include more detail, e.g. a complete program stack-trace.

root system statuses Entry category
Type: string

A device-specific representation of which sub-system the message comes from. In a Java environment, for example, it would be the fully qualified path name of the Class triggering the message.

Must match regular expression: ^[a-z][._a-zA-Z]*[a-zA-Z]$
Example:

"state.pointset.points.config.invalid"
+

root system statuses Entry timestamp
Type: string

Ttimestamp the condition was triggered, or most recently updated. It might be different than the top-level message timestamp if the condition is not checked often or is sticky until it's cleared.
Example:

"2018-08-26T21:39:28.364Z"
+

root system statuses Entry level
Type: integer

The status level should conform to the numerical Stackdriver LogEntry levels. The DEFAULT value of 0 is not allowed (lowest value is 100, maximum 800).

Value must be greater or equal to 100 and lesser or equal to 800 and a multiple of 1


Example:

600
+

root gateway
Type: object

Read more: https://github.com/faucetsdn/udmi/blob/master/docs/gateway.md

 No Additional Properties

root gateway error_ids
Type: array of string

Each item of this array must be:

root gateway error_ids items
Type: string
Must match regular expression: ^[A-Z]{3}-[1-9][0-9]{0,2}$

root blobset
Type: object
No Additional Properties

root blobset state_etag
Type: string

Must be at most 32 characters long

root blobset blobs
Type: object
No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root blobset blobs state_blobset_blob.json#
Type: object
No Additional Properties

root blobset blobs Blob Blobset State status
Type: object
No Additional Properties

root system statuses Entry message
Type: string

A one-line representation of the triggering condition.
Example:

"Point is not writable"
+

root system statuses Entry detail
Type: string

An optional be multi-line entry which can include more detail, e.g. a complete program stack-trace.

root system statuses Entry category
Type: string

A device-specific representation of which sub-system the message comes from. In a Java environment, for example, it would be the fully qualified path name of the Class triggering the message.

Must match regular expression: ^[a-z][._a-zA-Z]*[a-zA-Z]$
Example:

"state.pointset.points.config.invalid"
+

root system statuses Entry timestamp
Type: string

Ttimestamp the condition was triggered, or most recently updated. It might be different than the top-level message timestamp if the condition is not checked often or is sticky until it's cleared.
Example:

"2018-08-26T21:39:28.364Z"
+

root system statuses Entry level
Type: integer

The status level should conform to the numerical Stackdriver LogEntry levels. The DEFAULT value of 0 is not allowed (lowest value is 100, maximum 800).

Value must be greater or equal to 100 and lesser or equal to 800 and a multiple of 1


Example:

600
+

root pointset
Type: object

A set of points reporting telemetry data.

 No Additional Properties

root pointset state_etag
Type: string

An identifier which uniquely represents the state, and used by a device avoid race conditions where the incoming config is based off an obsolete state. Additional information on implementation: https://github.com/faucetsdn/udmi/blob/master/docs/writeback.md

Must be at most 32 characters long

root pointset points
Type: object

Collection of point names, defining the representative point set for this device.

 No Additional Properties

All property whose name matches the following regular expression must respect the following conditions

Property name regular expression: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
root pointset points state_pointset_point.json#
Type: object

Object representation for for a single point

 No Additional Properties

root pointset points Point Pointset State value_state
Type: enum (of string)

Optional enumeration indicating the state of the points value. Valid value_state settings include:
* : No set_value config has been specified, the source is device-native.
* applied: The set_value config has been successfully applied.
* overridden: The config setting is being overridden by another source.
* invalid: A problem has been identified with the config setting.
* failure: The config is fine, but a problem has been encountered applying the setting.
When the value state indicates an error state, an assosciated status entry should be included

Must be one of:

  • "applied"
  • "updating"
  • "overridden"
  • "invalid"
  • "failure"

root pointset points Point Pointset State status
Type: object

Optional status information about this point, subject to log severity level

 No Additional Properties

root system statuses Entry message
Type: string

A one-line representation of the triggering condition.
Example:

"Point is not writable"
+

root system statuses Entry detail
Type: string

An optional be multi-line entry which can include more detail, e.g. a complete program stack-trace.

root system statuses Entry category
Type: string

A device-specific representation of which sub-system the message comes from. In a Java environment, for example, it would be the fully qualified path name of the Class triggering the message.

Must match regular expression: ^[a-z][._a-zA-Z]*[a-zA-Z]$
Example:

"state.pointset.points.config.invalid"
+

root system statuses Entry timestamp
Type: string

Ttimestamp the condition was triggered, or most recently updated. It might be different than the top-level message timestamp if the condition is not checked often or is sticky until it's cleared.
Example:

"2018-08-26T21:39:28.364Z"
+

root system statuses Entry level
Type: integer

The status level should conform to the numerical Stackdriver LogEntry levels. The DEFAULT value of 0 is not allowed (lowest value is 100, maximum 800).

Value must be greater or equal to 100 and lesser or equal to 800 and a multiple of 1


Example:

600
+
\ No newline at end of file diff --git a/schema/common.json b/schema/common.json index 5aa814fc7f..787de6d964 100644 --- a/schema/common.json +++ b/schema/common.json @@ -1,6 +1,6 @@ { "title": "Common", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "entry": { "title": "Entry", @@ -8,25 +8,35 @@ "additionalProperties": false, "properties": { "message": { - "type": "string" + "description": "A one-line representation of the triggering condition.", + "type": "string", + "examples": ["Point is not writable"] }, "detail": { + "description": "An optional be multi-line entry which can include more detail, e.g. a complete program stack-trace.", "type": "string" }, "category": { + "description": "A device-specific representation of which sub-system the message comes from. In a Java environment, for example, it would be the fully qualified path name of the Class triggering the message.", "type": "string", - "pattern": "^[a-z][._a-zA-Z]*[a-zA-Z]$" + "pattern": "^[a-z][._a-zA-Z]*[a-zA-Z]$", + "examples": ["state.pointset.points.config.invalid"] }, "timestamp": { + "description": "Ttimestamp the condition was triggered, or most recently updated. It might be different than the top-level message `timestamp` if the condition is not checked often or is sticky until it's cleared.", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2018-08-26T21:39:28.364Z"] + }, "level": { "$comment": "https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity", + "description": "The status `level` should conform to the numerical [Stackdriver LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity) levels. The `DEFAULT` value of 0 is not allowed (lowest value is 100, maximum 800).", "type": "integer", "multipleOf": 1, "minimum": 100, - "maximum": 800 + "maximum": 800, + "examples": [600] } }, "required": [ diff --git a/schema/config.json b/schema/config.json index 9fa6c70446..f0bb87b6d5 100644 --- a/schema/config.json +++ b/schema/config.json @@ -1,7 +1,8 @@ { "title": "Config", + "description": "The config block controls a device's intended behavior. Read more: ", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "timestamp", @@ -9,10 +10,13 @@ ], "properties": { "timestamp": { + "description": "RFC 3339 timestamp the configuration was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "type": "integer", "minimum": 1, "maximum": 1 diff --git a/schema/config_blobset.json b/schema/config_blobset.json index 271c01c090..a45eb3aff5 100644 --- a/schema/config_blobset.json +++ b/schema/config_blobset.json @@ -1,7 +1,7 @@ { "title": "Blobset Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "blobs": { diff --git a/schema/config_blobset_blob.json b/schema/config_blobset_blob.json index 67d130483d..c2aecbfa8a 100644 --- a/schema/config_blobset_blob.json +++ b/schema/config_blobset_blob.json @@ -1,7 +1,7 @@ { "title": "Blob Blobset Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "stage": { diff --git a/schema/config_gateway.json b/schema/config_gateway.json index 0c7b58fbd2..5124c12b08 100644 --- a/schema/config_gateway.json +++ b/schema/config_gateway.json @@ -1,18 +1,20 @@ { "title": "Gateway Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "proxy_ids" ], "properties": { "proxy_ids": { + "description": "An array of all the device IDs which are bound to the device", "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}-[1-9][0-9]{0,2}$" - } + }, + "examples": [["AHU-22"]] } } } diff --git a/schema/config_localnet.json b/schema/config_localnet.json index 37f7f0fec7..43d91020e6 100644 --- a/schema/config_localnet.json +++ b/schema/config_localnet.json @@ -1,7 +1,7 @@ { "title": "Localnet Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "subsystem": { diff --git a/schema/config_pointset.json b/schema/config_pointset.json index 4113dacbbd..636938813c 100644 --- a/schema/config_pointset.json +++ b/schema/config_pointset.json @@ -1,7 +1,7 @@ { "title": "Pointset Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "state_etag": { @@ -9,20 +9,24 @@ "maxLength": 32 }, "set_value_expiry": { + "description": "An expiry for the the device reverts to its operational state, and sends a state update to notify the cloud of the state change. Read more: ", "type": "string", "format": "date-time" }, "sample_limit_sec": { + "description": "Minimum time between sample updates for the device (including complete and COV updates). Updates more frequent than this should be coalesced into one update.", "type": "integer", "minimum": 1, "maximum": 86400 }, "sample_rate_sec": { + "description": "Maximum time between samples for the device to send out a complete update. It can send out updates more frequently than this.", "type": "integer", "minimum": 1, "maximum": 86400 }, "points": { + "description": "The points defined in this dictionary is the authoritative source indicating the representative points for the device (in both `telemetry` and `state` messages). Read more: ", "additionalProperties": false, "existingJavaType": "java.util.HashMap", "patternProperties": { diff --git a/schema/config_pointset_point.json b/schema/config_pointset_point.json index 93fc7aa74d..96cef88c04 100644 --- a/schema/config_pointset_point.json +++ b/schema/config_pointset_point.json @@ -1,13 +1,15 @@ { "title": "Point Pointset Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "ref": { "type": "string" }, "set_value": { + "description": "Used for cloud writeback functionality, this field specifies the value for a given point in the device's current units.", + "examples": [22.4] } } } diff --git a/schema/config_system.json b/schema/config_system.json index 27d52a322b..5d007820b3 100644 --- a/schema/config_system.json +++ b/schema/config_system.json @@ -1,10 +1,11 @@ { "title": "System Config", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "min_loglevel": { + "description": "The minimum loglevel for reporting log messages below which log entries should not be sent.", "type": "integer", "minimum": 100, "maximum": 800 diff --git a/schema/envelope.json b/schema/envelope.json index a1e988d6e2..eee23bec14 100644 --- a/schema/envelope.json +++ b/schema/envelope.json @@ -1,5 +1,6 @@ { "title": "Envelope", + "description": "The UDMI `envelope` is not a message itself, per se, but the attributes and other information that is delivered along with a message. Read more: ", "additionalProperties": true, "properties": { "deviceId": { diff --git a/schema/event.json b/schema/event.json index 94f03020bc..ccc54e6c38 100644 --- a/schema/event.json +++ b/schema/event.json @@ -2,7 +2,7 @@ "title": "Event", "description": "Container object for all event schemas, not directly used.", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "system": { diff --git a/schema/event_audit.json b/schema/event_audit.json index ed74ae53f9..42c3694984 100644 --- a/schema/event_audit.json +++ b/schema/event_audit.json @@ -1,7 +1,7 @@ { "title": "Audit", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "timestamp": { diff --git a/schema/event_discovery.json b/schema/event_discovery.json index 8dc3d513ab..f9d6647a6e 100644 --- a/schema/event_discovery.json +++ b/schema/event_discovery.json @@ -1,14 +1,18 @@ { "title": "Discovery", + "description": "Read more: ", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "timestamp": { + "description": "RFC 3339 timestamp the discover telemetry event was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "enum": [ 1 ] diff --git a/schema/event_discovery_family.json b/schema/event_discovery_family.json index 725165db76..10d5d07d95 100644 --- a/schema/event_discovery_family.json +++ b/schema/event_discovery_family.json @@ -1,7 +1,7 @@ { "title": "Family Discovery Event", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "id": { diff --git a/schema/event_pointset.json b/schema/event_pointset.json index eff0758d3e..b64d834ba0 100644 --- a/schema/event_pointset.json +++ b/schema/event_pointset.json @@ -1,19 +1,24 @@ { "title": "Pointset Event", + "description": "A set of points reporting telemetry data", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "timestamp": { + "description": " RFC 3339 timestamp the telemetry event was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "type": "integer", "minimum": 1, "maximum": 1 }, "points": { + "description": "Collection of point names, defining the representative point set for this device.", "additionalProperties": false, "existingJavaType": "java.util.HashMap", "patternProperties": { diff --git a/schema/event_pointset_point.json b/schema/event_pointset_point.json index 94f7ac820c..dd976cd521 100644 --- a/schema/event_pointset_point.json +++ b/schema/event_pointset_point.json @@ -1,10 +1,13 @@ { "title": "Point Pointset Event", + "description": "Object representation for for a single point", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "present_value": { + "description": "The specific point data reading", + "examples": [24.1, true, 4] } }, "required": [ diff --git a/schema/event_system.json b/schema/event_system.json index 2622541ec0..8b69538e78 100644 --- a/schema/event_system.json +++ b/schema/event_system.json @@ -1,14 +1,17 @@ { "title": "System Event", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "timestamp": { + "description": "RFC 3339 timestamp the event payload was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "type": "integer", "minimum": 1, "maximum": 1 diff --git a/schema/metadata.json b/schema/metadata.json index 9aba14eb0f..4130ade88c 100644 --- a/schema/metadata.json +++ b/schema/metadata.json @@ -1,7 +1,7 @@ { "title": "Metadata", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "timestamp", @@ -10,15 +10,19 @@ ], "properties": { "timestamp": { + "description": "RFC 3339 timestamp the metadata was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "type": "integer", "minimum": 1, "maximum": 1 }, "hash": { + "description": "Automatically generated field that contains the hash of file contents.", "type": "string", "pattern": "^[0-9a-z]{8}$" }, diff --git a/schema/metadata_cloud.json b/schema/metadata_cloud.json index 5314d1ee5f..26b3940b67 100644 --- a/schema/metadata_cloud.json +++ b/schema/metadata_cloud.json @@ -1,10 +1,12 @@ { "title": "Cloud Metadata", + "description": "Information specific to how the device communicates with the cloud.", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "auth_type": { + "description": "The key type used for cloud communication.", "enum": [ "ES256", "ES256_X509", @@ -16,6 +18,7 @@ "type": "boolean" }, "is_gateway": { + "description": "If the device functions as an IoT Gateway, proxying for other devices using a single logical connection", "type": "boolean" } }, diff --git a/schema/metadata_gateway.json b/schema/metadata_gateway.json index 8858e26264..940c042336 100644 --- a/schema/metadata_gateway.json +++ b/schema/metadata_gateway.json @@ -1,23 +1,28 @@ { "title": "Gateway Metadata", + "description": "Read more: ", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "gateway_id": { + "description": "Present in devices which are proxied by a gateway, this identifies the device ID of the gateway the device is bound to", "type": "string", - "pattern": "^[A-Z]{2,6}-[0-9]{1,6}$" + "pattern": "^[A-Z]{2,6}-[0-9]{1,6}$", + "examples": ["GAT-100"] }, "subsystem": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "proxy_ids": { + "description": "Present in devices which are IoT gateways, this is an array of all the device IDs which are bound to the device", "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2,6}-[0-9]{1,6}$" - } + }, + "examples": [["AHU-22"]] } }, "oneOf": [ diff --git a/schema/metadata_localnet.json b/schema/metadata_localnet.json index c0f65eb321..f10244edb0 100644 --- a/schema/metadata_localnet.json +++ b/schema/metadata_localnet.json @@ -1,7 +1,7 @@ { "title": "Localnet Metadata", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "subsystem": { diff --git a/schema/metadata_localnet_subsystem.json b/schema/metadata_localnet_subsystem.json index b834a05aaf..c6b334fe80 100644 --- a/schema/metadata_localnet_subsystem.json +++ b/schema/metadata_localnet_subsystem.json @@ -1,7 +1,7 @@ { "title": "Subsystem Localnet Metadata", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "local_id": { diff --git a/schema/metadata_pointset.json b/schema/metadata_pointset.json index 5e656296f4..4c5c6dee73 100644 --- a/schema/metadata_pointset.json +++ b/schema/metadata_pointset.json @@ -1,10 +1,12 @@ { "title": "Pointset Metadata", + "description": "Pointset representing the abstract system expectation for what the device should be doing, and how it should be configured and operated. This block specifies the expected points that a device holds", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "points": { + "description": "Information about a specific point name of the device.", "additionalProperties": false, "maxProperties": 150, "existingJavaType": "java.util.HashMap", diff --git a/schema/metadata_pointset_point.json b/schema/metadata_pointset_point.json index d7a65f1c25..7b03893f2b 100644 --- a/schema/metadata_pointset_point.json +++ b/schema/metadata_pointset_point.json @@ -1,14 +1,18 @@ { "title": "Point Pointset Metadata", + "description": "Information about a specific point name of the device.", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "units": { + "description": "Expected unit configuration for the point.", "$ref": "file:units.json#" }, "ref": { - "type": "string" + "description": "A local network reference for a point, e.g. BACnet address or Modbus register", + "type": "string", + "examples": ["AI3.Present_Value", "400070"] } } } diff --git a/schema/metadata_system.json b/schema/metadata_system.json index 1c4b5a8fa0..ddd77f60c3 100644 --- a/schema/metadata_system.json +++ b/schema/metadata_system.json @@ -1,16 +1,20 @@ { "title": "System Metadata", + "description": "High-level sytem informaiton about the device.", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "location": { + "description": "Properties the expected physical location of the device.", "type": "object", "additionalProperties": false, "properties": { "site": { + "description": "The site name according to the site model in which a device is installed in", "type": "string", - "pattern": "^[A-Z]{2}-[A-Z]{3}-[A-Z0-9]{2,9}$" + "pattern": "^[A-Z]{2}-[A-Z]{3}-[A-Z0-9]{2,9}$", + "examples": ["US-SFO-XYY"] }, "section": { "type": "string", @@ -38,6 +42,7 @@ ] }, "physical_tag": { + "description": "Information used to print a physical QR code label.", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/properties.json b/schema/properties.json index 99e18356cd..e49a8c9faa 100644 --- a/schema/properties.json +++ b/schema/properties.json @@ -1,7 +1,7 @@ { "title": "Properties", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "key_type", diff --git a/schema/state.json b/schema/state.json index 4d9780488c..b5093d46be 100644 --- a/schema/state.json +++ b/schema/state.json @@ -1,7 +1,7 @@ { "title": "State", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "timestamp", @@ -10,10 +10,13 @@ ], "properties": { "timestamp": { + "description": "RFC 3339 Timestamp the state payload was generated", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "version": { + "description": "Major version of the UDMI schema", "type": "integer", "minimum": 1, "maximum": 1 diff --git a/schema/state_blobset.json b/schema/state_blobset.json index 692fa59d03..004747e689 100644 --- a/schema/state_blobset.json +++ b/schema/state_blobset.json @@ -1,7 +1,7 @@ { "title": "Blobset State", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "state_etag": { diff --git a/schema/state_blobset_blob.json b/schema/state_blobset_blob.json index e5aac3d59a..b8120ec07d 100644 --- a/schema/state_blobset_blob.json +++ b/schema/state_blobset_blob.json @@ -1,7 +1,7 @@ { "title": "Blob Blobset State", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "stage": { diff --git a/schema/state_gateway.json b/schema/state_gateway.json index d402fb81e6..79ace4551c 100644 --- a/schema/state_gateway.json +++ b/schema/state_gateway.json @@ -1,7 +1,8 @@ { "title": "Gateway State", + "description": "Read more: ", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "required": [ "error_ids" diff --git a/schema/state_pointset.json b/schema/state_pointset.json index 955cf25cc4..c6e40cba45 100644 --- a/schema/state_pointset.json +++ b/schema/state_pointset.json @@ -1,18 +1,22 @@ { "title": "Pointset State", + "description": "A set of points reporting telemetry data.", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "state_etag": { + "description": "An identifier which uniquely represents the state, and used by a device avoid race conditions where the incoming config is based off an obsolete state. Additional information on implementation: ", "type": "string", "maxLength": 32 }, "points": { + "description": "Collection of point names, defining the representative point set for this device.", "additionalProperties": false, "existingJavaType": "java.util.HashMap", "patternProperties": { "^[a-z][a-z0-9]*(_[a-z0-9]+)*$": { + "description": "Object representation for for a single point", "$ref": "file:state_pointset_point.json#" } } diff --git a/schema/state_pointset_point.json b/schema/state_pointset_point.json index 78ff561f52..702e8514f3 100644 --- a/schema/state_pointset_point.json +++ b/schema/state_pointset_point.json @@ -1,10 +1,12 @@ { "title": "Point Pointset State", + "description": "Object representation for for a single point", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "value_state": { + "description": "Optional enumeration indicating the state of the points value. Valid `value_state` settings include:\n* __: No `set_value` _config_ has been specified, the source is device-native.\n* _applied_: The `set_value` _config_ has been successfully applied.\n* _overridden_: The _config_ setting is being overridden by another source.\n* _invalid_: A problem has been identified with the _config_ setting.\n* _failure_: The _config_ is fine, but a problem has been encountered applying the setting.\nWhen the value state indicates an error state, an assosciated status entry should be included", "enum": [ "applied", "updating", @@ -14,6 +16,7 @@ ] }, "status": { + "description": "Optional status information about this point, subject to log severity level", "$ref": "file:common.json#/definitions/entry" } } diff --git a/schema/state_system.json b/schema/state_system.json index b133873376..4702ca372b 100644 --- a/schema/state_system.json +++ b/schema/state_system.json @@ -1,14 +1,18 @@ { "title": "System State", "type": "object", - "$schema": "http://json-schema.org/draft-04/schema#", + "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "make_model": { - "type": "string" + "description": "The make and model of the physical device", + "type": "string", + "examples": ["Delta Controls O3-DIN-SRC", "Arup Gateway"] }, "serial_no": { - "type": "string" + "description": "The serial number of the physical device", + "type": "string", + "examples": ["A1B2C3D4", "00001"] }, "auth_key": { "type": "object", @@ -23,10 +27,12 @@ ] }, "firmware": { + "description": "Information about the physical device firmware", "type": "object", "additionalProperties": false, "properties": { "version": { + "description": "Version of the local firmware", "type": "string" } }, @@ -35,13 +41,17 @@ ] }, "last_config": { + "description": "Time from the `timestamp` field of the last successfully parsed `config` message (not the timestamp the message was received/processed).", "type": "string", - "format": "date-time" + "format": "date-time", + "examples": ["2019-01-17T14:02:29.364Z"] }, "operational": { + "$comment": "whatis", "type": "boolean" }, "statuses": { + "description": "A map of 'sticky' conditions that are keyed on a value that can be used to manage updates by a particular (device dependent) subsystem.", "type": "object", "additionalProperties": false, "existingJavaType": "java.util.HashMap",