Skip to content

Commit 67f6103

Browse files
palemieuxpalemieux
committed
Initial commit
0 parents  commit 67f6103

8 files changed

+366
-0
lines changed

‎.gitmodules

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "tooling"]
2+
path = tooling
3+
url = https://github.com/SMPTE/html-pub.git

‎CONFIDENTIALITY.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# CONFIDENTIALITY
2+
3+
This repository is not SMPTE Confidential Information and is not subject to the
4+
confidentiality policy specified by the SMPTE Standards Operations Manual.

‎CONTRIBUTING.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# CONTRIBUTING
2+
3+
Please be aware that all contributions to this material are being conducted in accordance with the SMPTE Standards Operations
4+
Manual, which is accessible on the SMPTE website with the Society Bylaws: https://www.smpte.org/about/policies-and-governance.
5+
6+
Your comments and contributions, whether as a member or guest, are governed by these provisions and any comment or contribution made
7+
by you indicates your acknowledgement that you understand and are complying with the full form of the Operations Manual. Please take
8+
careful note of the sections requiring contributors to inform the Committee of personal knowledge of any claims under any issued
9+
patent or any patent application that likely would be infringed by an implementation of this material. This general reminder is not
10+
a substitute for a contributor’s responsibility to fully read, understand, and comply with the full Standards Operations Manual.

‎LICENSE.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# LICENSE
2+
3+
Copyright © by the Society of Motion Picture and Television Engineers. All rights reserved. No part of this material may be
4+
reproduced, by any means whatsoever, without the prior written permission of the Society of Motion Picture and Television Engineers.

‎PATENTS.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# PATENTS
2+
3+
Attention is drawn to the possibility that some of the elements of this material may be the subject of patent rights. SMPTE shall
4+
not be held responsible for identifying any or all such patent rights.

‎README.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# SMPTE _DOC NUMBER_ - _TITLE_
2+
3+
_This repository is *public*._
4+
5+
Rendered at [https://smpte.github.io/NAMEOFREPO/](https://smpte.github.io/NAMEOFREPO/).
6+
7+
Please consult [CONTRIBUTING.md](./CONTRIBUTING.md), [CONFIDENTIALITY.md](./CONFIDENTIALITY.md), [LICENSE.md](./LICENSE.md) and
8+
[PATENTS.md](./PATENTS.md) for important notices.

‎index.html

+332
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
<!DOCTYPE html lang="en">
2+
<html>
3+
4+
<head itemscope="itemscope" itemtype="http://smpte.org/standards/documents">
5+
<meta charset="utf-8" />
6+
<meta http-equiv="x-ua-compatible" content="ie=edge" />
7+
<meta name="viewport" content="width=device-width, initial-scale=1" />
8+
<script src="tooling/smpte.js"></script>
9+
<link rel="stylesheet" href="tooling/smpte.css" />
10+
<meta itemprop="pubType" content="AG" />
11+
<meta itemprop="pubNumber" content="25" />
12+
<meta itemprop="pubState" content="published" />
13+
<meta itemprop="pubDateTime" content="2022-07-05" />
14+
<title>Use of JSON in Engineering Documents</title>
15+
</head>
16+
17+
<body>
18+
19+
<section id="sec-foreword" class="unnumbered"></section>
20+
21+
<section id="sec-toc" class="unnumbered"></section>
22+
23+
<section id="sec-scope">
24+
<h2>Scope</h2>
25+
<p>This Administrative Guideline specifies selected uses of the JavaScript Object Notation (JSON) in SMPTE
26+
Engineering Documents.</p>
27+
</section>
28+
29+
<section id="sec-conformance"></section>
30+
31+
<section id="sec-normative-references">
32+
<ul>
33+
<li><cite id="bib-ietf-rfc-3986">IETF RFC 3986</cite>, Uniform Resource
34+
Identifiers (URI): Generic Syntax, T. Berners-Lee, et al., January 2005. <a>http://www.ietf.org/rfc/rfc3986.txt</a></li>
35+
<li><cite id="bib-ietf-rfc-5234">IETF RFC 5234</cite>, “Augmented BNF for
36+
Syntax Specifications: ABNF”, D. Crocker, January 2008. <a>https://www.rfc-editor.org/rfc/rfc5234.txt</a></li>
37+
<li><cite id="bib-ietf-rfc-7405">IETF RFC 7405</cite>, “Case-Sensitive
38+
String Support in ABNF”, P. Kyzivat, December 2014. <a>https://datatracker.ietf.org/doc/html/rfc7405.txt</a></li>
39+
<li><cite id="bib-ietf-rfc-8259">IETF RFC 8259</cite>, The JavaScript
40+
Object Notation (JSON) Data Interchange Format, T. Bray, <a>http://www.ietf.org/rfc/rfc8259.txt</a></li>
41+
</ul>
42+
</section>
43+
44+
<section id="sec-smpte-json-structures">
45+
<h2>SMPTE JSON structures</h2>
46+
<section id="sec-overview">
47+
<h3>Overview (informative)</h3>
48+
The JSON Schema resource applicable to a JSON structure can specify constraints to which the structure is expected to conform.
49+
</section>
50+
51+
<section id="sec-json-structures">
52+
<h3>JSON Structures</h3>
53+
54+
<p>
55+
A <dfn>SMPTE JSON structure</dfn> is any data structure that (a) is specified by an
56+
Engineering Document and (b) conforms to <a
57+
href="#bib-ietf-rfc-8259"></a> (i.e., a JSON document), whether within
58+
the prose or as an Additional Element.
59+
</p>
60+
61+
<p>
62+
The structure of each <a>SMPTE JSON structure</a> shall be normatively specified
63+
the Engineering Document.
64+
</p>
65+
<p>
66+
Each SMPTE JSON structure should be informatively specified by a JSON Schema
67+
resource, which may be a SMPTE JSON Schema resource (see section 5), using
68+
the JSON Schema language as specified in <a href="#bib-draft-bhutton-json-schema-00"></a>.
69+
</p>
70+
</section>
71+
72+
</section>
73+
74+
<section id="sec-smpte-json-schema-resources">
75+
<h2>SMPTE JSON Schema resources</h2>
76+
77+
<section id="sec-introduction">
78+
<h3>Introduction (informative)</h3>
79+
80+
<p>Using the formal language of JSON Schema, descriptions of conformance
81+
requirements for JSON structures can avoid some of the ambiguity inherent with
82+
using English prose alone, while allowing the use of existing commercial tools
83+
to facilitate testing and validation. It can also represent a significant
84+
convenience to implementers, for example by supporting the ability to
85+
automatically validate structures.</p>
86+
87+
<p>Sample relative link to a <a href="sample.png">picture</a>.</p>
88+
89+
</section>
90+
91+
<section id="sec-canonical-uri">
92+
<h3>Canonical URI</h3>
93+
94+
<section id="sec-id-keyword">
95+
<h4><code>$id</code> Keyword</h4>
96+
97+
<p>A SMPTE JSON Schema resource shall use the <code>$id</code> keyword in the root schema
98+
object, thereby providing the canonical URI for the JSON root schema.</p>
99+
</section>
100+
101+
<section id="sec-canonical-uri-syntax">
102+
<h4>Canonical URI Syntax</h4>
103+
104+
The canonical URI shall conform to the <code>SCHEMAID</code> syntax below,
105+
specified using <a href="#bib-ietf-rfc-5234"></a> and <a
106+
href="#bib-ietf-rfc-7405"></a> and conforming to <a
107+
href="#bib-ietf-rfc-3986"></a>.
108+
109+
<pre>
110+
SCHEMAID = %s"https://www.smpte-ra.org/json-schema/" PUBNUM "/" REVISION [ "/" SHORTNAME]
111+
SHORTNAME = 1*4("/" 1*(ALPHA / DIGIT / "-" / "_" / ".") )
112+
PUBNUM = 1*(DIGIT) ["-" 1*(DIGIT)]
113+
REVISION = STABLEREV
114+
STABLEREV = 4(DIGIT) [2(DIGIT)]
115+
</pre>
116+
117+
<p><code>PUBNUM</code> shall represent the official publication number of the
118+
Engineering Document, without leading zeroes and including a part number, if
119+
any, separated by a hyphen, e.g., 456-1.</p>
120+
121+
<p class="note">The <code>REVISION</code> component of a stable SMPTE JSON
122+
Schema canonical URI does not necessarily correspond to the publication
123+
date of its defining Engineering Document. For instance, the defining
124+
Engineering Document can be revised in such a way that the contents of the
125+
JSON Schema remain unchanged.</p>
126+
127+
<p class="note">
128+
No changes to SMPTE JSON Schema canonical URI are necessary following a Draft
129+
Publication ballot since SMPTE JSON Schema canonical URI are constructed
130+
independently of the publication date of the Engineering Document.
131+
</p>
132+
</section>
133+
134+
<section id="sec-examples">
135+
<h4>Examples (informative)</h4>
136+
The following is an example SMPTE JSON Schema resource canonical URI:
137+
138+
<pre>https://www.smpte-ra.org/json-schema/456/2021/foo</pre>
139+
140+
<p><a href="#table-examples"></a> lists examples.</p>
141+
142+
<table id="table-examples">
143+
<caption>Examples</caption>
144+
<thead>
145+
<tr>
146+
<th>Name</th>
147+
<th>URI</th>
148+
</tr>
149+
</thead>
150+
<tbody>
151+
<tr>
152+
<td>Hello</td>
153+
<td>https://www.smpte-ra.org/json-schema/456/2021/foo</td>
154+
</tr>
155+
</tbody>
156+
</table>
157+
</section>
158+
159+
<section id="sec-registration">
160+
<h4>Registration (informative)</h4>
161+
162+
<p>
163+
The SMPTE JSON Schema resource canonical URI syntax ensures uniqueness across
164+
Engineering Documents, and thus no specific registration steps are required.
165+
</p>
166+
167+
<p><a href="#figure-process-flowchart"></a> shows an example of the process.</p>
168+
169+
<figure id="figure-process-flowchart">
170+
<figcaption>Example of the Process</figcaption>
171+
<img class="figure" src="sample.png">
172+
</figure>
173+
174+
</section>
175+
</section>
176+
177+
<section id="sec-using-a-smpte-json-schema-resource">
178+
<h3>Using a SMPTE JSON Schema Resource</h3>
179+
180+
<p>A SMPTE JSON Schema resource can be used informatively by an Engineering
181+
Document, either by inclusion or by reference.</p>
182+
183+
<p class="note">The current specification of JSON Schema, though well-supported, is not a
184+
normatively referenceable document per the Standards Operations Manual (section
185+
10 Normative References) and AG-03. Thus, provision of SMPTE JSON Schema
186+
resources, at this time, is strictly informative.</p>
187+
</section>
188+
189+
<section id="sec-version">
190+
<h3>Version</h3>
191+
192+
<p>
193+
Whenever a SMPTE JSON Schema resource is provided, the Engineering Document
194+
shall provide an informative reference to the JSON Schema language specification
195+
to which it conforms (e.g., JSON Schema, as shown in the Bibliography).
196+
</p>
197+
198+
<p>
199+
A SMPTE JSON Schema resource shall use the <code>$schema</code> keyword in the root schema
200+
object.
201+
</p>
202+
203+
<p class="note">
204+
the <code>$schema</code> keyword is both used as JSON Schema dialect identifier and
205+
as the identifier of a resource which is itself a JSON Schema resource to
206+
evaluate conformance to that dialect.
207+
</p>
208+
209+
<p class="note">
210+
JSON Schema resources can comprise subschemas, where portions of a root
211+
schema document are separately identifiable by a URI-reference that are not
212+
absolute and/or contain non-empty fragments. For example,
213+
<code>https://smpte-ra.org/schemas/2120-2/2021/smpte-tlx-items/definitions/rationalType</code>
214+
is a reference to a subschema within the SMPTE JSON Schema resource
215+
<code>https://smpte-ra.org/schemas/2120-2/2021/smpte-tlx-items</code>
216+
where the subschema represents the constraints for a JSON structure
217+
representing a rational value.
218+
</p>
219+
220+
</section>
221+
222+
<section id="sec-keyword-order">
223+
<h3>Keyword Order</h3>
224+
225+
<p>The following keywords should appear as the first keywords in any SMPTE JSON Schema resource in this order:</p>
226+
227+
<ul>
228+
<li><code>$schema,</code> as specified in <a href="#sec-version"></a></li>
229+
<li><code>$id,</code> as specified in <a href="#sec-id-keyword"></a>; and,</li>
230+
<li><code>$comment,</code> as specified in <a
231+
href="#sec-cc-license-schema-resources"></a>.</li>
232+
</ul>
233+
234+
</section>
235+
</section>
236+
237+
<section id="sec-copyright-and-license">
238+
<h2>Copyright and License</h2>
239+
240+
<section id="sec-license">
241+
<h3>License</h3>
242+
243+
<p>
244+
Any SMPTE JSON structure or SMPTE JSON Schema resource, whether provided within
245+
the prose or as an Additional Element of an Engineering Document, shall be
246+
licensed according to <a href="#sec-json-document-license"></a>.
247+
</p>
248+
249+
<p class="note">
250+
The license portion of Annex A is verbatim the BSD-3-Clause license
251+
available at <a>https://spdx.org/licenses/BSD-3-Clause.html</a>.
252+
</p>
253+
</section>
254+
255+
<section id="sec-cc-license-schema-resources">
256+
<h3>Copyright and License in SMPTE JSON Schema resources</h3>
257+
258+
Any SMPTE JSON Schema resource shall include the copyright and license
259+
provided in <a href="#sec-json-document-license"></a> in the form of the
260+
<code>$comment</code> element specified in <a href="#sec-license-element"></a>.
261+
</section>
262+
</section>
263+
264+
<section class="annex" id="sec-json-document-license">
265+
<h2>JSON Document License</h2>
266+
267+
<section id="sec-copyright-element">
268+
<h3>Copyright Element</h3>
269+
<pre>
270+
Copyright (c), Society of Motion Pictures and Television Engineers.
271+
272+
Redistribution and use in source and binary forms, with or without modification,
273+
are permitted provided that the following conditions are met:
274+
</pre>
275+
<p><a href="#table-copyright-forms"></a> lists copyright forms.</p>
276+
<table id="table-copyright-forms">
277+
<caption>Copyright Forms</caption>
278+
<thead>
279+
<tr>
280+
<th>Name</th>
281+
</tr>
282+
</thead>
283+
<tbody>
284+
<tr>
285+
<td>(c)</td>
286+
</tr>
287+
<tr>
288+
<td>©</td>
289+
</tr>
290+
</tbody>
291+
</table>
292+
</section>
293+
294+
<section id="sec-license-element">
295+
<h3>License Element</h3>
296+
297+
<p>The following example JSON Schema incorporates the above element in
298+
accordance with <a href="#sec-cc-license-schema-resources"></a>, with the initial
299+
keyword order recommended in <a href="#sec-keyword-order"></a>.</p>
300+
301+
<pre>
302+
{
303+
"$schema": "https://json-schema.org/draft/2020-12/meta/core",
304+
"$id": "https://smpte-ra.org/json-schema/2199-1/2022/foo",
305+
"$comment": "Copyright (c), Society of Motion Pictures and Television Engineers. Licensed under BSD-3-Clause (https://spdx.org/licenses/BSD-3-Clause.html).",
306+
"title": "foo",
307+
"type": "object",
308+
"description": "This is an example schema for a fictitious foo object.",
309+
"examples": [
310+
{
311+
"bar": "zyzx"
312+
}
313+
}
314+
</pre>
315+
316+
</section>
317+
</section>
318+
319+
<section id="sec-bibliographic-references">
320+
<ul>
321+
<li><cite id="bib-draft-bhutton-json-schema-00">IETF
322+
draft-bhutton-json-schema-00</cite>, Wright, A., H. Andrews; B. Hutton, G.
323+
Dennis, "JSON Schema: A Media Type for Describing JSON Documents", Work in
324+
Progress, December 8, 2020.
325+
<a>https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00</a>
326+
</li>
327+
</ul>
328+
</section>
329+
330+
</body>
331+
332+
</html>

‎tooling

Submodule tooling added at a3ac896

0 commit comments

Comments
 (0)