Skip to content

Commit 6a9c047

Browse files
awwrightawwright
committed
Add Use Cases and Requirements
1 parent d962a20 commit 6a9c047

File tree

1 file changed

+309
-0
lines changed

1 file changed

+309
-0
lines changed

‎jsonschema-use-cases.xml

+309
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
<?xml version="1.0" encoding="US-ASCII"?>
2+
<!DOCTYPE rfc [
3+
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
4+
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
5+
<!ENTITY RFC3987 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml">
6+
<!ENTITY RFC6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
7+
<!ENTITY RFC8259 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8259.xml">
8+
]>
9+
<?rfc toc="yes"?>
10+
<?rfc symrefs="yes"?>
11+
<?rfc compact="yes"?>
12+
<?rfc subcompact="no"?>
13+
<?rfc strict="no"?>
14+
<?rfc rfcedstyle="yes"?>
15+
<?rfc comments="yes"?>
16+
<?rfc inline="yes" ?>
17+
<rfc category="info" docName="draft-wright-jsonschema-use-cases-00" ipr="none" submissionType="independent">
18+
<front>
19+
<title abbrev="JSON Schema">JSON Schema: Use Cases and Requirements</title>
20+
21+
<author fullname="Austin Wright" initials="A" surname="Wright" role="editor">
22+
<address>
23+
<email>[email protected]</email>
24+
</address>
25+
</author>
26+
27+
<date year="2022"/>
28+
<workgroup>JSON Schema</workgroup>
29+
<keyword>JSON</keyword>
30+
<keyword>Schema</keyword>
31+
<keyword>Hyper Schema</keyword>
32+
<keyword>Hypermedia</keyword>
33+
34+
<abstract>
35+
<t>
36+
To foster development of JSON Schema, this document contains a list of use cases and requirements that may be used to inform its development and evolution. All examples should be realistic examples of how people may use JSON Schema.
37+
</t>
38+
</abstract>
39+
<note title="Note to Readers">
40+
<t>
41+
The issues list for this document can be found at
42+
<eref target="https://github.com/json-schema-org/json-schema-spec/issues"/>.
43+
</t>
44+
<t>
45+
For additional information, see <eref target="https://json-schema.org/"/>.
46+
</t>
47+
<t>
48+
To provide feedback, use this issue tracker, the communication methods listed on the
49+
homepage, or email the document editors.
50+
</t>
51+
</note>
52+
</front>
53+
54+
<middle>
55+
<section title="Scope and Motivation">
56+
<t>
57+
JSON Schema is a JSON media type for defining the structure of JSON data. JSON Schema
58+
is intended to define validation, documentation, hyperlink navigation, and interaction
59+
control of JSON data.
60+
</t>
61+
<t>
62+
This specification defines JSON Schema core terminology and mechanisms, including
63+
pointing to another JSON Schema by reference,
64+
dereferencing a JSON Schema reference,
65+
specifying the dialect being used,
66+
specifying a dialect's vocabulary requirements,
67+
and defining the expected output.
68+
</t>
69+
<t>
70+
Other specifications define the vocabularies that perform assertions about validation,
71+
linking, annotation, navigation, and interaction.
72+
</t>
73+
</section>
74+
75+
<section title="Conventions and Terminology">
76+
<t>
77+
The terms "JSON", "JSON text", "JSON value", "member", "element", "object", "array",
78+
"number", "string", "boolean", "true", "false", and "null" in this document are to
79+
be interpreted as defined in <xref target="RFC8259">RFC 8259</xref>.
80+
</t>
81+
82+
<t>
83+
Use Cases describe the system's behavior under various conditions, cataloging who does what with the system, for what purpose, but without concern for system design or implementation.
84+
</t>
85+
86+
<t>
87+
Requirements list functional and non-functional or quality requirements, and the use cases they may be derived from/related to.
88+
</t>
89+
</section>
90+
91+
<section title="Use Cases">
92+
<section title="Structural validation" anchor="uc-structural">
93+
<t>
94+
The most basic function of validating JSON is the ability to express any subset of JSON that can be described by a deterministic context-free grammar, except for distinguishing between different encodings of the same value. Schemas that limit themselves to this functionality may be compiled to a deterministic pushdown automata.
95+
</t>
96+
<t>
97+
The following features of JSON are easily expressible as a pushdown automata:
98+
</t>
99+
<list>
100+
<t>JSON primitive type (string, object, etc)</t>
101+
<t>Minimum or maximum in a linear range of values</t>
102+
<t>Minimum or maximum lengths (number of characters, digits, items, or properties)</t>
103+
<t>Literal/constant values or alternate/enumerated values</t>
104+
<t>Pattern matching strings by a regular expression (including object keys)</t>
105+
<t>Logic operators (union, intersection, difference)</t>
106+
<t>Descent into object properties and array items</t>
107+
</list>
108+
<t>
109+
Multiple forms that are value-equal according JSON need not be distinguished under this use-case. This includes the ordering of properties in an object, character escapes in strings, and whitespace.
110+
</t>
111+
</section>
112+
113+
<section title="Semantic annotation" anchor="uc-annotations">
114+
<t>
115+
There is a need to annotate values within a JSON document: for machine readability, and for documentation purposes.
116+
Given a document and directions for annotating it, you should should be able to:
117+
</t>
118+
<list>
119+
<t>document the meaning of a property,</t>
120+
<t>suggest a default value for new documents of a given type,</t>
121+
<t>fill in missing values (in objects or arrays) with values of equivalent meaning,</t>
122+
<t>generate a list of hyperlinks,</t>
123+
<t>or declare relationships between data.</t>
124+
</list>
125+
<t>
126+
A schema may be used to describe a machine-readable <xref target="RFC6906">profile</xref> of JSON document. Even when two schemas identify the same set of JSON documents; depending on the context, a given JSON document may be a profile of one but not the other.
127+
</t>
128+
</section>
129+
130+
<section title="Domain-specific language">
131+
<t>
132+
Application authors may use an entirely self-contained inside an application that consumes JSON. By using a declarative language, the application requirements can be better optimized by the application.
133+
</t>
134+
<t>
135+
Application authors may define custom hooks and processing for the JSON (without need for standardizing the customization).
136+
</t>
137+
<t>
138+
The only interoperability consideration here is that updates to the validator library must not change the set of valid JSON documents, unless the developer specifically opts into such a breaking change (e.g. by upgrading the library to a new major version number).
139+
</t>
140+
</section>
141+
142+
<section title="A common vocabulary">
143+
<t>
144+
A team of developers write two similar applications, for different platforms, in different languages. The application downloads and reads JSON documents. They want to make sure that both applications accept or reject JSON with identical behavior, so they write a single JSON Schema and deploy it to both applications.
145+
</t>
146+
<t>
147+
The only interoperability consideration here is that the two applications, given the same schema, must both be reasonably expected to support the same behavior and operate in the same manner.
148+
</t>
149+
</section>
150+
151+
<section title="Model-Driven UI constraints">
152+
<t>
153+
When a server declares constraints that a submission must meet, there is a need for the user interface to receive these constraints to provide model-driven validation of permissible values, making the form more accessible to the user.
154+
</t>
155+
<t>
156+
If the schema is ambiguous in any way, or is up to the discretion of the customer's user-agent, some customers may have a difficult time submitting a correct request.
157+
</t>
158+
</section>
159+
160+
<section title="Fuzzing, enumeration, and generation">
161+
<t>
162+
Security applications need to generate examples of JSON documents within the valid set, and outside the valid set.
163+
</t>
164+
</section>
165+
166+
<section title="Embedded database constraints">
167+
<t>
168+
A database that uses JSON may need a way to declare, enforce, or guarantee certain constraints on the JSON document being stored. The database may use JSON Schema as a way to annotate certain fields as having a special meaning for uniqueness or indexing purposes.
169+
</t>
170+
</section>
171+
172+
<section title="Partial validation" anchor="partial-validation">
173+
<t>
174+
Due to technical limitations, some JSON parsers may only be able to understand a subset of the JSON value space, and it makes sense to validate the value read by the application, instead of the JSON document provided to the JSON parser. For example:
175+
</t>
176+
<list style="symbols">
177+
<t>Many JSON parsers cast the arbitrary-precision decimal numbers to an IEEE floating point, validating the number after it has lost some precision, because this form is read by the application.</t>
178+
<t>Some programming languages cannot distinguish between an ordered array of values and a key-value map; or an empty array is identical to an empty object.</t>
179+
<t>Other validators may have a limited amount of memory and cannot support assertions more complicated than a deterministic context-free grammar in the Chomsky hierarchy (i.e. validation not describable by a deterministic pushdown automata).</t>
180+
</list>
181+
<t>
182+
Users of these validators need a way to determine if the missing functionality is essential to correct understanding, and if not, get a validation result that would be correct but-for the unimplemented functionality.
183+
</t>
184+
<t>
185+
<cref>
186+
This should work both ways; an application should be able to use a third-party schema and understand if the assertions go beyond what the environment supports; and an application should be able to publish a schema that is compatible with the subset of the value space that it supports. Consider if these are separate use cases.
187+
</cref>
188+
</t>
189+
</section>
190+
191+
<section title="Machine-readable profiles of Web resources">
192+
<t>
193+
A Web server that offers a JSON document should be able to link to a profile document that describes the meaning of the data in a machine-readable form.
194+
</t>
195+
</section>
196+
197+
<section title="Hypermedia">
198+
<t>
199+
Generic user-agents must be able to make use of the schema as it evolves, including Web browsers, spiders, and automated tooling. It should support loose coupling (like an HTML homepage); so a schema should be able to change, add, and remove features with minimal breakage for compatible clients.
200+
</t>
201+
</section>
202+
203+
<section title="Extension points" anchor="extension-points">
204+
<t>
205+
Application developers may wish to express a wide variety of constraints that would be impractical to require every validator to implement.
206+
</t>
207+
<t>
208+
Like in the <xref target="partial-validation">"Partial validation"</xref> use case, validators need to understand when the extension is not supported, and allow the application to determine if validation may continue without it. For example, if a Web API does not use XML, it would be unnecessary for its JSON validator to support keywords dealing with XML, so in this case, it's appropriate for its JSON validator to reject constraints dealing with XML altogether.
209+
</t>
210+
</section>
211+
</section>
212+
213+
<section title="Use cases for extensions">
214+
<t>
215+
This section lists use cases that not required for interoperability in media type handling, but which should be defined as as standard extensions to maximize support and feature interoperability.
216+
As specified in <xref target="extension-points">"Extension points,"</xref>
217+
validators should gracefully degrade in the presence of extensions that they do not support.
218+
</t>
219+
220+
<section title="External validation">
221+
<t>
222+
JSON may embed resources of other media types, like base64 or hex-encoded documents; and may wish to pass off validation of these documents to another software tool.
223+
</t>
224+
</section>
225+
226+
<section title="Intra-document data consistency validation">
227+
<t>
228+
A JSON document may carry relational data whose consistency must be verified. Example constraints include:
229+
</t>
230+
<ul>
231+
<li>One-to-one calculations, like that children's birthdates come after their parent's birthdates;</li>
232+
<li>One-to-many calculations, like a reference to an anchor points to an anchor defined somewhere in the same document.</li>
233+
</ul>
234+
</section>
235+
236+
<section title="Inter-database consistency validation">
237+
<t>
238+
A JSON document may carry relational data whose consistency must be verified. Example constraints include:
239+
</t>
240+
<ul>
241+
<li>References to a user ID points to a user in a central users database.</li>
242+
<li>A supplied email address has been verified by the user.</li>
243+
</ul>
244+
</section>
245+
246+
</section>
247+
248+
<section title="Requirements" anchor="requirements">
249+
<t>
250+
Requirement 1.
251+
</t>
252+
<section title="R1. " anchor="r1">
253+
<t>
254+
Requirement 1.
255+
</t>
256+
<t>
257+
Motivation: <xref target="extension-points">Extension points</xref>,
258+
</t>
259+
<t>
260+
Use Cases: <xref target="extension-points">Extension points</xref>,
261+
</t>
262+
<t>
263+
Implementation: type, enum, const, patternProperties, pattern,
264+
</t>
265+
</section>
266+
<section title="R4. Annotations" anchor="r4">
267+
<t>
268+
Constraints/shapes may incorporate extra information that does not affect validation.
269+
It shall be possible to search for constraints/shapes with particular extra information.
270+
</t>
271+
<t>
272+
Motivation: <xref target="uc-annotations">Annotations</xref>,
273+
</t>
274+
<t>
275+
Use Cases: <xref target="extension-points">Extension points</xref>,
276+
</t>
277+
<t>
278+
Implementation: title, description
279+
</t>
280+
</section>
281+
<section title="R7. Named Schemas" anchor="r7">
282+
<t>
283+
It should be possible to designate a schema as a named entity, so that it may be reused in multiple places, including across the Web.
284+
</t>
285+
<t>
286+
Use Cases: <xref target="extension-points">Extension points</xref>,
287+
</t>
288+
<t>
289+
Implementation: $id, $ref
290+
</t>
291+
</section>
292+
</section>
293+
294+
<section title="Security Considerations" anchor="security">
295+
<t>
296+
This document does not make any normative requirements.
297+
</t>
298+
</section>
299+
</middle>
300+
301+
<back>
302+
<!-- References Section -->
303+
<references title="Informative References">
304+
&RFC6906;
305+
&RFC8259;
306+
</references>
307+
308+
</back>
309+
</rfc>

0 commit comments

Comments
 (0)