{"id":25343960,"url":"https://github.com/ssilverman/rdm-schema","last_synced_at":"2025-07-25T06:04:45.352Z","repository":{"id":39990978,"uuid":"253639197","full_name":"ssilverman/rdm-schema","owner":"ssilverman","description":"The schema for the Parameter Metadata Language from Section 5 of E1.37-5.","archived":false,"fork":false,"pushed_at":"2024-03-23T04:33:25.000Z","size":238,"stargazers_count":10,"open_issues_count":18,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-05T04:31:46.311Z","etag":null,"topics":["json-schema","manufacturer-messages","rdm","rdm-schema"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ssilverman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-06T23:29:12.000Z","updated_at":"2024-09-18T10:30:45.000Z","dependencies_parsed_at":"2023-11-17T20:28:24.684Z","dependency_job_id":"8cd9c09c-ca31-4bd5-89a3-b1fb6b50ed85","html_url":"https://github.com/ssilverman/rdm-schema","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/ssilverman/rdm-schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssilverman%2Frdm-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssilverman%2Frdm-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssilverman%2Frdm-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssilverman%2Frdm-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ssilverman","download_url":"https://codeload.github.com/ssilverman/rdm-schema/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ssilverman%2Frdm-schema/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266963279,"owners_count":24013020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-schema","manufacturer-messages","rdm","rdm-schema"],"created_at":"2025-02-14T11:00:06.048Z","updated_at":"2025-07-25T06:04:45.322Z","avatar_url":"https://github.com/ssilverman.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# README for the RDM Schema Project\n\nVersion: 1.0.0\n\nThis project contains the schema for the Parameter Metadata Language from\nSection 5 of E1.37-5.\n\nThe schema is subject to change.\n\n## Table of contents\n\n1. [Project intent](#project-intent)\n2. [Design notes](#design-notes)\n   1. [Relation to other RDM types and structure](#relation-to-other-rdm-types-and-structure)\n   2. [Exceptions](#exceptions)\n   3. [Strings and string lengths](#strings-and-string-lengths)\n   4. [Names and displayable strings](#names-and-displayable-strings)\n3. [Usage notes](#usage-notes)\n   1. [Framing is at a different layer](#framing-is-at-a-different-layer)\n   2. [Arbitrary field sizes](#arbitrary-field-sizes)\n   3. [Constraints and errors](#constraints-and-errors)\n   4. [Defaults and the \"default\" annotation](#defaults-and-the-\"default\"-annotation)\n4. [Best practices](#best-practices)\n5. [Notes on the examples](#notes-on-the-examples)\n   1. [Manufacturer ID](#manufacturer-id)\n6. [Open questions](#open-questions)\n7. [TODOs](#todos)\n8. [Resources](#resources)\n   1. [References mentioned in the schema](#references-mentioned-in-the-schema)\n\n## Project intent\n\nThis project intends to provide a machine-readable way to describe\nmanufacturer-specific RDM messages. Controllers can then process, and perhaps\nprovide a meaningful UI for, these messages.\n\n## Design notes\n\nIt was chosen to use the latest version of the schema specification,\nDraft 2019-09 to take advantage of the latest features. It is intended that the\nschema will be updated as later drafts and releases come out, as appropriate.\n\nTo develop the schema, all known RDM messages were implemented as schema\ninstances so that every case in the specifications was accounted for. There were\ntwo exceptions, however, `QUEUED_MESSAGE` and `CAPTURE_PRESET`.\n\n### Relation to other RDM types and structure\n\nThe \"DS_*\" types in ANSI E1.20-202x, plus the types from related specifications,\nare not sufficient to describe a proper type system, so there is no direct\nmapping from ANSI E1.20-202x to this schema.\n\nWhilst this schema can be used to represent everything in the specifications,\nthe facilities in the specifications can't be used to represent everything\nRDM messages might wish to represent, manufacturer-specific or otherwise.\n\n### Exceptions\n\n`QUEUED_MESSAGE` is the only message that allows responses having a different\nPID. First experiments used a response type of `\"different_pid\"`.\n`CAPTURE_PRESET` is the only message with optional fields; the last few can\nbe present as a group or not.\n\nIt was decided that these features would not be included because they're so\nrare and they're not desirable features for representing manufacturer messages,\nthe original intent for this project.\n\n### Strings and string lengths\n\nThere are two facilities this schema provides for \"string length\". The first is\n\"length in characters\", defined by `\"minLength\"` and `\"maxLength\"`. A\n\"character\" is defined the same way that JSON defines a character: a single code\npoint, possibly composed using a UTF-16 surrogate pair.\n\nThe second facility is \"byte length\", expressed in `\"minBytes\"` and\n`\"maxBytes\"`. Strings will use the UTF-8 encoding and the length in bytes gives\nbounds on the storage requirements.\n\nFrom\n[Validation Keywords for Strings](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.6.3):\n\n\u003e The length of a string instance is defined as the number of its characters as\n\u003e defined by [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html).\n\nSpecifically, see\n[Section 7: Strings](https://www.rfc-editor.org/rfc/rfc8259.html#section-7) and\n[Section 8: String and Character Issues](https://www.rfc-editor.org/rfc/rfc8259.html#section-8).\n\nIn other words, \"length\" in this schema means the same things as \"string length\"\nper the JSON specification.\n\nThere are further considerations when using a string for display, say in a UI.\nHowever, this specification does not address those things. Those considerations\nmay include, but are not limited to, normalization, canonicalization, glyph\nsize, and character-to-display approaches. It is up to the manufacturer to\ndecide what to use for string content.\n\nSee the discussion at [What's the difference between a character, a code point,\na glyph and a grapheme?](https://stackoverflow.com/a/27331885).\n\nRelevant terms: UCS-4, UTF-8, Unicode, Basic Multilingual Plane, Unicode Plane.\n\n### Names and displayable strings\n\nFor nameable things, `\"name\"` is intended to be a unique ID and `\"displayName\"`\nis intended to be a name for display. Note that both are optional.\n\nIn the case that a manufacturer wishes to provide localized names, this design\ntakes a cue from how Java does localized strings. The name would be used as a\nlookup into some manufacturer-supplied table for the actual display string, and\nthe `\"displayName\"` value could be used as a fallback or as the actual\ndisplayable name in the case where a manufacturer does not provide that\nout-of-band table.\n\n## Usage notes\n\n### Framing is at a different layer\n\nThe schema can describe complete messages, but does not describe message\nframing. For example, if a message is larger than can fit inside a single RDM\npacket, then the underlying implementation would use\n`RESPONSE_TYPE_ACK_OVERFLOW` appropriately.\n\n### Arbitrary field sizes\n\nThere are several field types that can be non-fixed sizes. For example, \"a\nstring having a length in the range 0-32\" or \"a list of arbitrary size\". So that\nthere is no ambiguity, a message should contain at most one non-fixed-size\nfield, and that field should appear last, serially.\n\nIf a responder wishes for controllers to limit the number of bytes sent, then it\nshould set appropriate values for the `\"maxLength\"` field for strings and the\n`\"maxLength\"` field for bytes.\n\n### Constraints and errors\n\nNote that the schema does not capture every possible error. Some errors can only\nbe caught after processing a schema instance. Please see the\n[Best practices](#best-practices) section for more details about avoiding these\nkinds of errors.\n\n### Defaults and the \"default\" annotation\n\nIn JSON Schema, the \"default\" keyword is merely an annotation that applies to\nthe current schema location, if present; it does not describe the value to use\nwhen the property is absent. This is counterintuitive insofar as a \"default\"\nannotation does not provide a default value in the case of a missing property.\n\nAn implementation is expected to follow the usage notes in the description if a\ndefault value is needed. It can use the value of the \"default\" annotation, but\nthis is not a JSON Schema feature.\n\nIn other words, a JSON parser/validator will not return values for absent\nproperties; it is up to the application to supply values.\n\n## Best practices\n\nIt's certainly possible to create badly defined messages, even though they\nconform to the schema. These messages may just be ill-defined or may not be\ncompatible with the responder serving these messages. This section describes\nsome restrictions that, if followed, will prevent many of these kinds\nof problems.\n\n1. If a responder wishes for controllers to limit the number of bytes sent for\n   strings or bytes, then it should set appropriate values for the `\"maxBytes\"`\n   field for strings and the `\"maxLength\"` field for bytes. It's conceivable\n   that a responder doesn't need this, but many responders do because they're\n   implemented on smaller systems that may need to preallocate memory.\n2. Minimums should be less than maximums. For example, the \"bytes\" type has\n   `\"minLength\"` and `\"maxLength\"` fields; `\"minLength\"` should be less than or\n   equal to `\"maxLength\"`.\n3. A bit field size should be greater than or equal to the number of its\n   defined bits.\n4. A command should not refer to itself. For example, a `\"get_response\"` cannot\n   have a value of `\"get_response\"`. Please refer to the \"Command Duplicate\"\n   subschema under the \"command\" schema.\n5. References (\"$ref\") should refer to an object having a valid type. Also,\n   there should not be any circular references.\n6. String patterns should not contradict any minimum or maximum lengths, and\n   vice versa.\n7. The `\"format\"` value for bytes or strings, if a fixed-size type, should not\n   contradict any minimum or maximum lengths.\n\n## Notes on the examples\n\n### Manufacturer ID\n\nAll the example messages should use a manufacturer ID of zero or 0xFFFF because\nthose are ESTA's. However, those will not validate against the schema if the\nvalue is restricted to the range 0x0001-0x7FFFF. There was some discussion\non this:\n1. It is stated in several places that manufacturer IDs must be in the range\n   0x0001-0x7FFF, so we should restrict the range. See:\n   1. [ANSI E1.20](https://tsp.esta.org/tsp/documents/public_review_docs.php)\n   2. [ANSI E1.33](https://tsp.esta.org/tsp/documents/public_review_docs.php)\n   3. [Control Protocols Working Group - Manufacturer IDs](https://tsp.esta.org/tsp/working_groups/CP/mfctrIDs.php)\n2. There was some concern that developers will copy \u0026 paste the examples and not\n   choose their own manufacturer ID, so keeping the examples from validating\n   will prevent this.\n\nIt is the opinion of the author of this document that it is not reasonable to\nrestrict the schema just to prevent possible misuse. In addition, it's defined\nas a 16-bit value. Using the schema to restrict the value will cause future\nchanges and uses to be invalid. It may be beyond the scope of the schema to\naccomplish any restriction.\n\nIf the manufacturer ID is required, if it is restricted to 0x0001-0x7FFF, and if\nthe examples should validate, then there are two possible ways to express ESTA\nexamples. Either:\n1. Remove `\"manufacturer_id\"` from the examples and remove the field from the\n   list of required fields, or\n2. Use a valid manufacturer ID in the examples, such as 0x7FFF from the\n   prototyping/experimental use region.\n\nIn other words, we can't simultaneously have all the following things:\n1. Examples having manufacturer ID zero.\n2. Manufacturer ID's limited to the range 0x0001-0x7FFF.\n3. Examples that validate.\n4. `\"manufacturer_id\"` being a required property.\n\nFor now, the value in all the examples is set to 0 (0x7FFF).\n\n## Open questions\n\nSome open questions:\n1. Versioning. Perhaps we change the schema's $id each time there's an update?\n   We could include the version in the URI. Some possibilities:\n   1. https://estalink.us/schemas/v1.0.1/rdm-schema.json\n   2. https://estalink.us/schemas/rdm-schema-v1.0.1.json\n2. How to have examples with the ESTA manufacturer ID (zero), while at the same\n   time having them validate and requiring the manufacturer ID be a required\n   property. The temporary solution is the change all the example manufacturer\n   ID's to something in the prototyping/experimental use region (0x7FF0-0x7FFF).\n\n## TODOs\n\nWork that still needs to be done:\n1. Supply valid PIDs to some of the examples. Currently, they are using an\n   invalid value of -1 because the PIDs are unassigned.\n\n## Resources\n\n* [TSP Published Documents](https://tsp.esta.org/tsp/documents/published_docs.php)\n  * The latest ANSI E1.20 specification can be found here.\n* [TSP Public Review Documents](https://tsp.esta.org/tsp/documents/public_review_docs.php)\n  * ANSI E1.20-202x can be found here when it's released for public review.\n* [JSON Schema](https://json-schema.org)\n* RDM schema canonical URI (not necessarily a network locator):\n  http://estalink.us/rdm-schema.json\n* RDM schema main page (expected to be here, but not here yet):\n  http://estalink.us/rdm-schema\n* Online JSON schema validator:\n  [Hyperjump - JSON Schema Validator](https://json-schema.hyperjump.io/)\n* [JSON](https://www.rfc-editor.org/rfc/rfc8259.html)\n* [JSON Schema Validation: Validation Keywords for Strings](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.6.3)\n* [UTF-8](https://www.rfc-editor.org/rfc/rfc3629)\n* The discussion at\n  [What's the difference between a character, a code point, a glyph and a grapheme?](https://stackoverflow.com/a/27331885)\n\n### References mentioned in the schema\n\n* [URI Syntax](https://www.rfc-editor.org/rfc/rfc3986.html)\n* [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901.html)\n* [JSON](https://www.rfc-editor.org/rfc/rfc8259.html)\n  * [Section 7: Strings](https://www.rfc-editor.org/rfc/rfc8259.html#section-7)\n  * [Section 8: String and Character Issues](https://www.rfc-editor.org/rfc/rfc8259.html#section-8)\n* [JSON Schema Validation: Defined Formats](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.7.3)\n* Format \"hostname\":\n  * [Requirements for Internet Hosts: Host Names and Numbers](https://www.rfc-editor.org/rfc/rfc1123.html#section-2)\\\n    (You may need to scroll to Section 2.1.)\n  * [Application Techniques for Checking and Transformation of Names](https://www.rfc-editor.org/rfc/rfc3696.html#section-2)\n  * [Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework](https://www.rfc-editor.org/rfc/rfc5890.html)\n* Format \"json\" and string characters: [JSON](https://www.rfc-editor.org/rfc/rfc8259.html)\n* Format \"url\":\n  * [URI](https://www.rfc-editor.org/rfc/rfc3986.html)\\\n    See also (from [Section 1.1.3](https://www.rfc-editor.org/rfc/rfc3986.html#section-1.1.3)):\n    [URI, URL, URN Clarifications](https://www.rfc-editor.org/rfc/rfc3305.html)\n  * [URL](https://www.rfc-editor.org/rfc/rfc1738.html)\n* [ECMA-262](https://www.ecma-international.org/publications/standards/Ecma-262.htm)\n  (Regular Expressions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssilverman%2Frdm-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fssilverman%2Frdm-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fssilverman%2Frdm-schema/lists"}