Scope

This Administrative Guideline specifies selected uses of the JavaScript Object Notation (JSON) in SMPTE Engineering Documents.

SMPTE JSON structures

Overview (informative)

The JSON Schema resource applicable to a JSON structure can specify constraints to which the structure is expected to conform.

SMPTE JSON Structures

A SMPTE JSON structure is any data structure that (a) is specified by an Engineering Document and (b) conforms to (i.e., a JSON document), whether within the prose or as an Additional Element.

The structure of each SMPTE JSON structure shall be normatively specified the Engineering Document.

Each SMPTE JSON structure should be informatively specified by a JSON Schema resource, which may be a SMPTE JSON Schema resource (see section 5), using the JSON Schema language as specified in .

Encoding

A SMPTE JSON structure is encoded using UTF-8 and does not include a byte order mark (BOM), as specified in .

Example Instances

All example instance JSON structures shall be informative.

All example instance SMPTE JSON structures shall be valid with respect to the corresponding SMPTE JSON Schema resource, where one is provided.

If a SMPTE JSON Schema resource is provided, it should be used to validate each corresponding example instance SMPTE JSON structure, as a test of both the instance and the resource.

SMPTE JSON Schema resources

Introduction (informative)

Using the formal language of JSON Schema, descriptions of conformance requirements for JSON structures can avoid some of the ambiguity inherent with using English prose alone, while allowing the use of existing commercial tools to facilitate testing and validation. It can also represent a significant convenience to implementers, for example by supporting the ability to automatically validate structures.

A JSON Schema resource is identified by its canonical URI. Canonical URIs provide an unambiguous and human-readable link to the specifications define these schemas.

Where a JSON Schema resource relies on another JSON Schema resource to specify constraints on substructures, the other JSON Schema is identified by its canonical URI.

Canonical URI

$id Keyword

A SMPTE JSON Schema resource shall use the $id keyword in the root schema object, thereby providing the canonical URI for the JSON root schema.

Canonical URI Syntax

The canonical URI shall conform to the SCHEMAID syntax below, specified using and and conforming to .
SCHEMAID = %s"https://www.smpte-ra.org/json-schema/" PUBNUM "/" REVISION [ "/" SHORTNAME]
SHORTNAME = 1*4("/" 1*(ALPHA / DIGIT / "-" / "_" / ".") )
PUBNUM = 1*(DIGIT) ["-" 1*(DIGIT)]
REVISION = STABLEREV
STABLEREV = 4(DIGIT) [2(DIGIT)]

PUBNUM shall represent the official publication number of the Engineering Document, without leading zeroes and including a part number, if any, separated by a hyphen, e.g., 456-1.

SHORTNAME is used when the Engineering Document defines more than one JSON Schema. It may provide a human meaningful designation of the schema, but shall not include any version information.

A stable SMPTE JSON Schema canonical URI is a SMPTE JSON Schema canonical URI whose name is such that REVISION:

  • conforms to STABLEREV, which consists of a year encoded as 4 decimal digits, optionally followed by a month encoded as 2 decimal digits in the range 01-12; and
  • represents the date that the JSON Schema canonical URI first appeared in the Engineering Document, which might be as a Public Committee Draft.

The REVISION component of a stable SMPTE JSON Schema canonical URI does not necessarily correspond to the publication date of its defining Engineering Document. For instance, the defining Engineering Document can be revised in such a way that the contents of the JSON Schema remain unchanged.

No changes to SMPTE JSON Schema canonical URI are necessary following a Draft Publication ballot since SMPTE JSON Schema canonical URI are constructed independently of the publication date of the Engineering Document.

Examples (informative)

The following is an example SMPTE JSON Schema resource canonical URI:
https://www.smpte-ra.org/json-schema/456/2021/foo

One can immediately see that the schema "foo" is defined in a SMPTE Engineering Document numbered "456" and initially appeared in the year "2021". One would assume that a "foo" was a well-known artifact to SMPTE members, at least for those that have read Engineering Document number "456".

The following is an example SMPTE JSON Schema resource canonical URI, defined in a document with a part designation and that originally appeared in September of 2022:

https://www.smpte-ra.org/json-schema/456-1/202209/foo

The following is a SMPTE JSON Schema resource canonical URI defined in a draft version of the same specification:

https://www.smpte-ra.org/json-schema/456-1/experimental-20211001/foo

The following is not equivalent to the previous name since it is missing the string "www" (though the two URIs can nevertheless resolve to the same resource when used in an HTTP GET query):

https://smpte-ra.org/json-schema/456-1/experimental-20141001/

The following is not a valid SMPTE JSON Schema resource canonical URI, since a fragment is used:

https://www.smpte-ra.org/json-schema/456-1/experimental-20141001/foo#hello

Registration (informative)

The SMPTE JSON Schema resource canonical URI syntax ensures uniqueness across Engineering Documents, and thus no specific registration steps are required.

Change Policy

An Engineering Document that defines a SMPTE JSON Schema resource should specify whether the schema is mutable, i.e., whether the schema is allowed to change substantially over time without also changing the canonical URI of the SMPTE JSON Schema resource.

Using a SMPTE JSON Schema Resource

A SMPTE JSON Schema resource can be used informatively by an Engineering Document, either by inclusion or by reference.

The current specification of JSON Schema, though well-supported, is not a normatively referenceable document per the Standards Operations Manual (section 10 Normative References) and AG-03. Thus, provision of SMPTE JSON Schema resources, at this time, is strictly informative.

Precedence

Engineering Documents normatively describe the constraints on a SMPTE JSON structure, including names and values, by their prose. Any Engineering Document providing a SMPTE JSON Schema resource to help validate a structure against those constraints should point out that, in case of a conflict between prose and the JSON Schema resource, the prose takes precedence.

Avoiding Discrepancies

To help avoid discrepancies between the English prose and a SMPTE JSON Schema resource, prose sections should be bound to the related portion of the resource, so that one cannot be modified without the other.

One method to bind prose to a SMPTE JSON Schema resource is to include the resource definitions inline within the prose. Another method is for the prose to refer to SMPTE JSON Schema resources specified in appendices or Additional Elements.

Any Additional Element that duplicates a SMPTE JSON Schema resource specified in the Prose Element, shall be informative.

Informative JSON Schema resource definitions can be provided as examples, e.g., to demonstrate how to define an extension to another JSON Schema resource through the “additionalProperties” or “additionalItems” keywords.

Version

Whenever a SMPTE JSON Schema resource is provided, the Engineering Document shall provide an informative reference to the JSON Schema language specification to which it conforms (e.g., JSON Schema, as shown in the Bibliography).

A SMPTE JSON Schema resource shall use the $schema keyword in the root schema object.

the $schema keyword is both used as JSON Schema dialect identifier and as the identifier of a resource which is itself a JSON Schema resource to evaluate conformance to that dialect.

JSON Schema resources can comprise subschemas, where portions of a root schema document are separately identifiable by a URI-reference that are not absolute and/or contain non-empty fragments. For example, https://smpte-ra.org/schemas/2120-2/2021/smpte-tlx-items/definitions/rationalType is a reference to a subschema within the SMPTE JSON Schema resource https://smpte-ra.org/schemas/2120-2/2021/smpte-tlx-items where the subschema represents the constraints for a JSON structure representing a rational value.

External Definitions

The defining document of any externally-defined JSON Schema resource shall be included as an informative reference.

Valid Definitions

All SMPTE JSON Schema resources specified in an Engineering Document shall be valid with respect to the JSON Schema resource(s) identified by the value of the $schema keyword(s) therein.

All SMPTE JSON Schema resources should be validated against the meta-schema specified by their $schema keyword(s).

Publication

All Additional Elements of Engineering Documents conforming to JSON Schema shall be publicly retrievable at an HTTP URI chosen by the Director of Engineering.

Keyword Order

The following keywords should appear as the first keywords in any SMPTE JSON Schema resource in this order:

Copyright and License

License

Any SMPTE JSON structure or SMPTE JSON Schema resource, whether provided within the prose or as an Additional Element of an Engineering Document, shall be licensed according to .

The license portion of Annex A is verbatim the BSD-3-Clause license available at https://spdx.org/licenses/BSD-3-Clause.html.

Copyright and License in SMPTE JSON Schema resources

Any SMPTE JSON Schema resource shall include the copyright and license provided in in the form of the $comment element specified in .

JSON Document License

Copyright (c), Society of Motion Pictures and Television Engineers. 

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met: 

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution. 

3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright and License Element

The following JSON elements present the SMPTE copyright notice and the JSON Schema identifier, a URI, which is useable as a URL to access the JSON Schema Definition Document which presents, among other things, the JSON Document License shown in .

"$comment": "Copyright (c), Society of Motion Pictures and Television Engineers. Licensed under BSD-3-Clause (https://spdx.org/licenses/BSD-3-Clause.html)."

The following example JSON Schema incorporates the above element in accordance with , with the initial keyword order recommended in .

{
  "$schema": "https://json-schema.org/draft/2020-12/meta/core",
  "$id": "https://smpte-ra.org/json-schema/2199-1/2022/foo",
  "$comment": "Copyright (c), Society of Motion Pictures and Television Engineers. Licensed under BSD-3-Clause (https://spdx.org/licenses/BSD-3-Clause.html).",
  "title": "foo",
  "type": "object",
  "description": "This is an example schema for a fictitious foo object.",
  "examples": [
    {
      "bar": "zyzx"
    }
  ],
  "properties": {
    "bar": {
      "$id": "#bar",
      "title": "bar",
      "type": "string",
      "description": "A fictitious short string element.",
      "minLength":1,
      "maxLength":4
    }
  },
  "required": [ "bar" ]
}