Skip to content

Commit fe5efce

Browse files
awwrightawwright
committed
Add Use Cases and Requirements
1 parent ab0453e commit fe5efce

File tree

1 file changed

+318
-0
lines changed

1 file changed

+318
-0
lines changed

Diff for: ‎jsonschema-use-cases.xml

+318
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
<?xml version="1.0" encoding="US-ASCII"?>
2+
<!DOCTYPE rfc [
3+
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
4+
<!ENTITY RFC3987 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml">
5+
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
6+
<!ENTITY RFC6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
7+
]>
8+
<?rfc toc="yes"?>
9+
<?rfc symrefs="yes"?>
10+
<?rfc compact="yes"?>
11+
<?rfc subcompact="no"?>
12+
<?rfc strict="no"?>
13+
<?rfc rfcedstyle="yes"?>
14+
<?rfc comments="yes"?>
15+
<?rfc inline="yes" ?>
16+
<rfc category="info" docName="draft-wright-jsonschema-use-cases-00" ipr="none" submissionType="independent">
17+
<front>
18+
<title abbrev="JSON Schema">JSON Schema: Use Cases and Requirements</title>
19+
20+
<author fullname="Austin Wright" initials="A" surname="Wright" role="editor">
21+
<address>
22+
<email>[email protected]</email>
23+
</address>
24+
</author>
25+
26+
<date year="2023"/>
27+
<workgroup>JSON Schema</workgroup>
28+
<keyword>JSON</keyword>
29+
<keyword>Schema</keyword>
30+
<keyword>Hyper Schema</keyword>
31+
<keyword>Hypermedia</keyword>
32+
33+
<abstract>
34+
<t>
35+
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.
36+
</t>
37+
</abstract>
38+
<note title="Note to Readers">
39+
<t>
40+
The issues list for this document can be found at
41+
<eref target="https://github.com/json-schema-org/json-schema-spec/issues"/>.
42+
</t>
43+
<t>
44+
For additional information, see <eref target="https://json-schema.org/"/>.
45+
</t>
46+
<t>
47+
To provide feedback, use this issue tracker, the communication methods listed on the
48+
homepage, or email the document editors.
49+
</t>
50+
</note>
51+
</front>
52+
53+
<middle>
54+
<section title="Scope and Motivation">
55+
<t>
56+
JSON Schema is a JSON media type for defining the structure of JSON data. JSON Schema
57+
is intended to define validation, documentation, hyperlink navigation, and interaction
58+
control of JSON data.
59+
</t>
60+
<t>
61+
This document elaborates in detail what this means, and the specific use cases that shall be supported.
62+
</t>
63+
</section>
64+
65+
<section title="Conventions and Terminology">
66+
<t>
67+
Objectives specify the class of problems that are in the scope of the specification.
68+
</t>
69+
70+
<t>
71+
Use Cases catalog a variety of personal objectives that users may have, due to various objectives and constraints, that the specification shall address, but without concern for a specific design or implementation. Use cases guide the minimum functionality that the specification must be capable of.
72+
</t>
73+
74+
<t>
75+
Requirements list functional, non-functional, and quality requirements, the use cases they may be derived from/related to, and reference how each use case is implemented. Requirements are not detailed at this time but may be specified in the future.
76+
</t>
77+
</section>
78+
79+
<section title="Objectives">
80+
<t>
81+
JSON Schema shall be built to support two objectives, including expansion into uses not currently described by any use case, but fall within the objectives.
82+
</t>
83+
84+
<section title="Validation">
85+
<t>
86+
The first objective of JSON Schema is to describe sets of JSON documents; specifically, to notate a language of JSON documents using a machine-readable, set-builder notation.
87+
This covers the key use case of validating input using a validator, as well as numerous other tools that depend on describing to each other which kinds of JSON documents are and are not acceptable.
88+
</t>
89+
</section>
90+
91+
<section title="Annotation">
92+
<t>
93+
The second objective of JSON Schema is to map an input JSON document to an arbitrary output described by the user.
94+
Annotations may be combined with validation (in the same schema) to specify the domain of inputs for which an output is defined.
95+
This covers the key use case of documenting the meaning of properties and values in JSON documents, and other uses where the input document is being interpreted in some fashion.
96+
</t>
97+
</section>
98+
99+
<section title="Internet">
100+
<t>
101+
JSON is a technology standardized as a part of a larger ecosystem of Internet technology, and likewise, JSON Schema may also specify how it is used in this ecosystem, for example, use in HTTP, or the meaning of media type parameters.
102+
</t>
103+
</section>
104+
105+
<section title="Out of scope">
106+
<t>
107+
Use cases or requirements that do not advance these objectives are likely out of scope, and better suited in separate work that references JSON Schema.
108+
</t>
109+
<t>
110+
For example, a method of describing an API interface would exceed the scope of JSON Schema, although JSON Schema may be used as a part of such a description, in the cases where describing JSON documents is necessary.
111+
</t>
112+
</section>
113+
114+
</section>
115+
116+
<section title="Use Cases">
117+
<t>
118+
JSON Schema shall standardize these use cases.
119+
</t>
120+
121+
<section title="Structural validation" anchor="uc-structural">
122+
<t>
123+
Structural validation refers to the "structure" that a JSON document is supposed to follow, such as which properties must exist, what types of values are expected where, and what they must look like. Constraints cannot read values elsewhere in the document (e.g. to compare two values for equality), though constraints may depend on "where" the value is found (e.g. specific properties or array items must be a number).
124+
</t>
125+
<t>
126+
More specifically, structural validation is any validation that can be performed with a context-free grammar that follows JSON semantics, such that any forms that are equal according to JSON will produce the same result.
127+
</t>
128+
<t>
129+
Validators that support structural validation can entirely replace generic grammar languages such as <xref target="RFC5234">ABNF</xref>, and will guarantee compliance with JSON semantics. Likewise, schemas whose validation rules are limited to structural validation can be executed using a deterministic pushdown automata, guaranteeing a result in proportional time without error.
130+
</t>
131+
<t>
132+
The following features of JSON are structural validation:
133+
</t>
134+
<list>
135+
<t>JSON primitive type (string, object, etc)</t>
136+
<t>Minimum or maximum in a linear range of values</t>
137+
<t>Minimum or maximum lengths (number of characters, digits, items, or properties)</t>
138+
<t>Literal/constant values or alternate/enumerated values</t>
139+
<t>Pattern matching strings by a regular expression (including object keys)</t>
140+
<t>Logic operators (union, intersection, difference)</t>
141+
<t>Descent into object properties and array items (recursively)</t>
142+
</list>
143+
<t>
144+
Multiple forms that are value-equal according to JSON are not distinguishable under this use-case. This includes the ordering of properties in an object, character escapes in strings, and whitespace.
145+
</t>
146+
</section>
147+
148+
<section title="Semantic annotation" anchor="uc-annotations">
149+
<t>
150+
There is a need to annotate values within a JSON document: for machine readability, and for documentation purposes.
151+
Given a document and directions for annotating it, you should should be able to:
152+
</t>
153+
<list>
154+
<t>document the meaning of a property,</t>
155+
<t>suggest a default value for new documents of a given type,</t>
156+
<t>fill in missing values (in objects or arrays) with values of equivalent meaning,</t>
157+
<t>generate a list of hyperlinks,</t>
158+
<t>or declare relationships between data.</t>
159+
</list>
160+
<t>
161+
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.
162+
</t>
163+
</section>
164+
165+
<section title="Domain-specific language">
166+
<t>
167+
Developers may write an application that uses a JSON Schema internally as a domain-specific language, so that the schema is only used inside a single application by a single party. By using a declarative language, the application requirements can be optimized better than a human could do.
168+
</t>
169+
<t>
170+
Application authors may use a schema to define custom hooks and processing for the JSON (without need for standardizing the customization).
171+
</t>
172+
<t>
173+
The only interoperability consideration here is that updates to the validator library must not change the validation result of any JSON documents, unless the developer specifically opts into such a breaking change (e.g. by upgrading the library to a new major version number).
174+
</t>
175+
</section>
176+
177+
<section title="A common vocabulary">
178+
<t>
179+
A development team maintains two similar applications, but for different platforms, in different languages. The application downloads and reads from a common repository of 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.
180+
</t>
181+
<t>
182+
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.
183+
</t>
184+
</section>
185+
186+
<section title="Model-Driven UI constraints">
187+
<t>
188+
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.
189+
</t>
190+
<t>
191+
For example, if a value is specified to be a date, the form field where the value is specified can provide immediate feedback if an invalid date is entered, and even offer a date picker to help the user input a correct value.
192+
</t>
193+
<t>
194+
Weak interoperability requirements can hamper the user experience within this use case. 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.
195+
</t>
196+
</section>
197+
198+
<section title="Fuzzing, enumeration, and generation">
199+
<t>
200+
Security applications need to generate examples of JSON documents within the valid set, and outside the valid set.
201+
</t>
202+
</section>
203+
204+
<section title="Embedded database constraints">
205+
<t>
206+
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 also use JSON Schema as a way to annotate certain fields as having a special meaning for uniqueness or indexing purposes.
207+
</t>
208+
</section>
209+
210+
<section title="Partial validation" anchor="partial-validation">
211+
<t>
212+
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:
213+
</t>
214+
<list style="symbols">
215+
<t>Many JSON parsers cast the arbitrary-precision decimal numbers to an IEEE floating point, validating the number after it has lost some precision.</t>
216+
<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>
217+
<t>Other validators may have a limited amount of memory and cannot support assertions more complicated than a deterministic context-free grammar.</t>
218+
</list>
219+
<t>
220+
Users of these validators need a way to determine if the missing functionality is essential to correctly validating input, and if not, get a validation result that would be correct but-for the unimplemented functionality.
221+
</t>
222+
<t>
223+
<cref>
224+
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.
225+
</cref>
226+
</t>
227+
</section>
228+
229+
<section title="Machine-readable profiles of Web resources">
230+
<t>
231+
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.
232+
</t>
233+
</section>
234+
235+
<section title="Hypermedia">
236+
<t>
237+
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.
238+
</t>
239+
</section>
240+
241+
<section title="Results and Reporting">
242+
<t>
243+
The party that is providing the schema and input may not be the same party that is performing the validation; in this case, there should be a standard way to abstract away the validator interface, and report the results of a validation operation (validation result, annotations, and errors).
244+
</t>
245+
</section>
246+
247+
<section title="Extension points" anchor="extension-points">
248+
<t>
249+
Application developers may wish to express a wide variety of constraints that would be impractical to require every validator to implement.
250+
</t>
251+
<t>
252+
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.
253+
</t>
254+
</section>
255+
</section>
256+
257+
<section title="Use cases for extensions">
258+
<t>
259+
This section lists use cases that are not required for interoperability and are not standardized, but fall within the objectives and could be standardized in the future.
260+
As specified in <xref target="extension-points">"Extension points,"</xref>
261+
validators should gracefully degrade in the presence of extensions that they do not support.
262+
</t>
263+
264+
<section title="External validation">
265+
<t>
266+
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.
267+
</t>
268+
</section>
269+
270+
<section title="Intra-document data consistency validation">
271+
<t>
272+
A JSON document may carry relational data whose consistency must be verified. Example constraints include:
273+
</t>
274+
<ul>
275+
<li>One-to-one calculations, like that children's birthdates come after their parent's birthdates;</li>
276+
<li>One-to-many calculations, like a reference to an anchor points to an anchor defined somewhere in the same document.</li>
277+
</ul>
278+
</section>
279+
280+
<section title="Inter-database consistency validation">
281+
<t>
282+
A JSON document may carry relational data whose consistency must be verified. Example constraints include:
283+
</t>
284+
<ul>
285+
<li>References to a user ID points to a user in a central users database.</li>
286+
<li>A supplied email address has been verified by the user.</li>
287+
</ul>
288+
</section>
289+
290+
<section title="Linting">
291+
<t>
292+
Sometimes it's desirable to require formatting that does not impact the application-level meaning of the document, but instead specifies requirements purely for aesthetic or compatibility reasons.
293+
</t>
294+
<t>
295+
For example, for security reasons, a linter may need to ensure that a JSON document does not contain the string "<tt>&lt;/script</tt>" but is written instead with a character escape such as "<tt>&lt;\/script</tt>". This would ensure that, if the JSON were to be embedded in a <tt>&lt;script&gt;</tt> tag, that it would not have any part that could close the tag and start being interpreted as HTML.
296+
</t>
297+
<t>
298+
This is not a core part of JSON because it may violate the semantics of JSON, adding an ability to distinguish two documents that are supposed to be equal to the receiving application.
299+
</t>
300+
</section>
301+
</section>
302+
303+
<section title="Security Considerations" anchor="security">
304+
<t>
305+
This document does not make any normative requirements.
306+
</t>
307+
</section>
308+
</middle>
309+
310+
<back>
311+
<!-- References Section -->
312+
<references title="Informative References">
313+
&RFC5234;
314+
&RFC6906;
315+
</references>
316+
317+
</back>
318+
</rfc>

0 commit comments

Comments
 (0)