SMPTE   AG   25
Administrative Guideline

Use of JSON in Engineering Documents

Published - Approved: 2023-04-09

Copyright © 2023 , Society of Motion Picture and Television Engineers . All rights reserved. No part of this material may be reproduced, by any means whatsoever, without the prior written permission of the Society of Motion Picture and Television Engineers.

Table of contents 🔗

  1. Foreword
  2. 1 Scope
  3. 2 Conformance
  4. 3 Normative references
  5. 4 Terms and definitions
  6. 5 SMPTE JSON structures
    1. 5.1 Overview (informative)
    2. 5.2 SMPTE JSON Structure
    3. 5.3 Encoding
    4. 5.4 Example Instances
  7. 6 SMPTE JSON Schema Resources
    1. 6.1 Introduction (informative)
    2. 6.2 Canonical URI
      1. 6.2.1 $id Keyword
      2. 6.2.2 Canonical URI Syntax
      3. 6.2.3 Examples (informative)
      4. 6.2.4 Registration (informative)
    3. 6.3 Change Policy
    4. 6.4 Using a SMPTE JSON Schema Resource
    5. 6.5 Precedence
    6. 6.6 Avoiding Discrepancies
    7. 6.7 Version
    8. 6.8 External Definitions
    9. 6.9 Valid Definitions
    10. 6.10 Publication
    11. 6.11 Keyword Order
  8. 7 Copyright and License
    1. 7.1 License
    2. 7.2 Copyright and License in SMPTE JSON Schema Resources
  9. Annex A JSON Document License
  10. Annex B Copyright and License Element
  11. Bibliography

Foreword 🔗

SMPTE (the The Society of Motion Picture and Television Engineers) Engineers (SMPTE) is an internationally-recognized standards developing organization. Headquartered and incorporated in the United States of America, SMPTE has members in over 80 countries on six continents. SMPTE’s Engineering Documents, including Standards, Recommended Practices, and Engineering Guidelines, are prepared by SMPTE’s Technology Committees. Participation in these Committees is open to all with a bona fide interest in their work. SMPTE cooperates closely with other standards-developing organizations, including ISO, IEC and ITU. SMPTE Engineering Documents are drafted in accordance with the rules given in its Standards Operations Manual. For more information, please visit www.smpte.org .

This Standards Administrative Guideline forms an adjunct to the use and interpretation of the SMPTE Standards Operations Manual. In the event of a conflict, the Operations Manual shall prevail.

Copyright © The Society of Motion Picture and Television Engineers.

1 Scope 🔗

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

2 Conformance 🔗

Normative text is text that describes elements of the design that are indispensable or contains the conformance language keywords: "shall", "should", or "may". Informative text is text that is potentially helpful to the user, but not indispensable, and can be removed, changed, or added editorially without affecting interoperability. Informative text does not contain any conformance keywords. All text in this document is, by default, normative, except: the Introduction, any section explicitly labeled as "Informative" or individual paragraphs that start with "Note:" The following keywords "shall" and "shall not" indicate requirements strictly to be followed have a specific meaning in order to conform to the document context of this document:

3 Normative references 🔗

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

4 Terms and definitions 🔗

No terms and definitions are listed in this document.

5 SMPTE JSON structures 🔗

5.1 Overview (informative) 🔗

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

5.2 SMPTE JSON Structure 🔗

A SMPTE JSON Structure is any data structure that (a) is specified by an Engineering Document and (b) conforms to IETF RFC 8259 (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 Clause 6 ), using the JSON Schema language as specified in "JSON Schema: A Media Type for Describing JSON Documents" .

5.3 Encoding 🔗

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

5.4 Example Instances 🔗

All example instance JSON structures shall be informative.

All example instance SMPTE JSON Structure s 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.

6 SMPTE JSON Schema Resource s 🔗

6.1 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.

6.2 Canonical URI 🔗

6.2.1 $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.

6.2.2 Canonical URI Syntax 🔗

The canonical URI shall conform to the SCHEMAID syntax below, specified using IETF RFC 5234 and IETF RFC 7405 and conforming to IETF RFC 3986 . 

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.

NOTE 1 — —⁠ 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.

NOTE 2 — —⁠ 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.

6.2.3 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

6.2.4 Registration (informative) 🔗

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

6.3 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 .

6.4 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.

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

6.5 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.

6.6 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.

NOTE 1 — —⁠ 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 Resource s specified in appendices or Additional Elements.

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

NOTE 2 — —⁠ 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.

6.7 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: A Media Type for Describing JSON Documents" ).

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

NOTE 1 — —⁠ 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.

NOTE 2 — —⁠ 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.

6.8 External Definitions 🔗

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

6.9 Valid Definitions 🔗

All SMPTE JSON Schema Resource s 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 Resource s should be validated against the meta-schema specified by their $schema keyword(s).

6.10 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.

6.11 Keyword Order 🔗

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

Annex A
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.

Annex B
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 Annex A . 

"$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 7.2 , with the initial keyword order recommended in 6.11 . 

{
  "$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" ]
}

Bibliography 🔗