Version: 0.35.0
This project contains the schema for the Parameter Metadata Language from Section 5 of E1.37-5.
The schema is subject to change.
This project intends to provide a machine-readable way to describe manufacturer-specific RDM messages. Controllers can then process, and perhaps provide a meaningful UI for, these messages.
It was chosen to use the latest version of the schema specification, Draft 2019-09 to take advantage of the latest features. It is intended that the schema will be updated as later drafts and releases come out, as appropriate.
To develop the schema, all known RDM messages were implemented as schema
instances so that every case in the specifications was accounted for. There were
two exceptions, however, QUEUED_MESSAGE and CAPTURE_PRESET.
The "DS_*" types in ANSI E1.20-202x, plus the types from related specifications, are not sufficient to describe a proper type system, so there is no direct mapping from ANSI E1.20-202x to this schema.
Whilst this schema can be used to represent everything in the specifications, the facilities in the specifications can't be used to represent everything RDM messages might wish to represent, manufacturer-specific or otherwise.
QUEUED_MESSAGE is the only message that allows responses having a different
PID. First experiments used a response type of "different_pid".
CAPTURE_PRESET is the only message with optional fields; the last few can
be present as a group or not.
It was decided that these features would not be included because they're so rare and they're not desirable features for representing manufacturer messages, the original intent for this project.
There are two facilities this schema provides for "string length". The first is
"length in characters", defined by "minLength" and "maxLength". A
"character" is defined the same way that JSON defines a character: a single code
point, possibly composed using a UTF-16 surrogate pair.
The second facility is "byte length", expressed in "minBytes" and
"maxBytes". Strings will use the UTF-8 encoding and the length in bytes gives
bounds on the storage requirements.
From Validation Keywords for Strings:
The length of a string instance is defined as the number of its characters as defined by RFC 8259.
Specifically, see Section 7: Strings and Section 8: String and Character Issues.
In other words, "length" in this schema means the same things as "string length" per the JSON specification.
There are further considerations when using a string for display, say in a UI. However, this specification does not address those things. Those considerations may include, but are not limited to, normalization, canonicalization, glyph size, and character-to-display approaches. It is up to the manufacturer to decide what to use for string content.
See the discussion at What's the difference between a character, a code point, a glyph and a grapheme?.
Relevant terms: UCS-4, UTF-8, Unicode, Basic Multilingual Plane, Unicode Plane.
For nameable things, "name" is intended to be a unique ID and "displayName"
is intended to be a name for display. Note that both are optional.
In the case that a manufacturer wishes to provide localized names, this design
takes a cue from how Java does localized strings. The name would be used as a
lookup into some manufacturer-supplied table for the actual display string, and
the "displayName" value could be used as a fallback or as the actual
displayable name in the case where a manufacturer does not provide that
out-of-band table.
The schema can describe complete messages, but does not describe message
framing. For example, if a message is larger than can fit inside a single RDM
packet, then the underlying implementation would use
RESPONSE_TYPE_ACK_OVERFLOW appropriately.
There are several field types that can be non-fixed sizes. For example, "a string having a length in the range 0-32" or "a list of arbitrary size". So that there is no ambiguity, a message should contain at most one non-fixed-size field, and that field should appear last, serially.
If a responder wishes for controllers to limit the number of bytes sent, then it
should set appropriate values for the "maxLength" field for strings and the
"maxLength" field for bytes.
Note that the schema does not capture every possible error. Some errors can only be caught after processing a schema instance. Please see the Best practices section for more details about avoiding these kinds of errors.
In JSON Schema, the "default" keyword is merely an annotation that applies to the current schema location, if present; it does not describe the value to use when the property is absent. This is counterintuitive insofar as a "default" annotation does not provide a default value in the case of a missing property.
An implementation is expected to follow the usage notes in the description if a default value is needed. It can use the value of the "default" annotation, but this is not a JSON Schema feature.
In other words, a JSON parser/validator will not return values for absent properties; it is up to the application to supply values.
It's certainly possible to create badly defined messages, even though they conform to the schema. These messages may just be ill-defined or may not be compatible with the responder serving these messages. This section describes some restrictions that, if followed, will prevent many of these kinds of problems.
- If a responder wishes for controllers to limit the number of bytes sent for
strings or bytes, then it should set appropriate values for the
"maxBytes"field for strings and the"maxLength"field for bytes. It's conceivable that a responder doesn't need this, but many responders do because they're implemented on smaller systems that may need to preallocate memory. - Minimums should be less than maximums. For example, the "bytes" type has
"minLength"and"maxLength"fields;"minLength"should be less than or equal to"maxLength". - A bit field size should be greater than or equal to the number of its defined bits.
- A command should not refer to itself. For example, a
"get_response"cannot have a value of"get_response". Please refer to the "Command Duplicate" subschema under the "command" schema. - References ("$ref") should refer to an object having a valid type. Also, there should not be any circular references.
- String patterns should not contradict any minimum or maximum lengths, and vice versa.
- The
"format"value for bytes or strings, if a fixed-size type, should not contradict any minimum or maximum lengths.
Some open questions:
- Versioning. Perhaps we change the schema's $id each time there's an update? We could include the version in the URI. Some possibilities:
Work that still needs to be done:
- Supply valid PIDs to some of the examples. Currently, they are using an invalid value of -1.
- TSP Published Documents
- The latest ANSI E1.20 specification can be found here.
- TSP Public Review Documents
- ANSI E1.20-202x can be found here when it's released for public review.
- JSON Schema
- RDM schema canonical URI (not necessarily a network locator): http://estalink.us/rdm-schema.json
- RDM schema main page (expected to be here, but not here yet): http://estalink.us/rdm-schema
- Online JSON schema validator: Hyperjump - JSON Schema Validator
- JSON
- JSON Schema Validation: Validation Keywords for Strings
- UTF-8
- The discussion at What's the difference between a character, a code point, a glyph and a grapheme?
- URI Syntax
- JSON Pointer
- JSON
- JSON Schema Validation: Defined Formats
- Format "hostname":
- Format "json" and string characters: JSON
- Format "url":
- URI
See also (from Section 1.1.3): URI, URL, URN Clarifications - URL
- URI
- ECMA-262 (Regular Expressions)