Skip to content

Commit

Permalink
Add Use Cases and Requirements
Browse files Browse the repository at this point in the history
  • Loading branch information
@awwright
awwright committed Mar 27, 2023
1 parent 29d65fa commit 4089b1e
Showing 1 changed file with 310 additions and 0 deletions.
310 changes: 310 additions & 0 deletions jsonschema-use-cases.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,310 @@
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc [
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC3987 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc strict="no"?>
<?rfc rfcedstyle="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes" ?>
<rfc category="info" docName="draft-wright-jsonschema-use-cases-00" ipr="none" submissionType="independent">
<front>
<title abbrev="JSON Schema">JSON Schema: Use Cases and Requirements</title>

<author fullname="Austin Wright" initials="A" surname="Wright" role="editor">
<address>
<email>[email protected]</email>
</address>
</author>

<date year="2023"/>
<workgroup>JSON Schema</workgroup>
<keyword>JSON</keyword>
<keyword>Schema</keyword>
<keyword>Hyper Schema</keyword>
<keyword>Hypermedia</keyword>

<abstract>
<t>
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.
</t>
</abstract>
<note title="Note to Readers">
<t>
The issues list for this document can be found at
<eref target="https://github.com/json-schema-org/json-schema-spec/issues"/>.
</t>
<t>
For additional information, see <eref target="https://json-schema.org/"/>.
</t>
<t>
To provide feedback, use this issue tracker, the communication methods listed on the
homepage, or email the document editors.
</t>
</note>
</front>

<middle>
<section title="Scope and Motivation">
<t>
JSON Schema is a JSON media type for defining the structure of JSON data. JSON Schema
is intended to define validation, documentation, hyperlink navigation, and interaction
control of JSON data.
</t>
<t>
This document elaborates in detail what this means, and the specific use cases that shall be supported.
</t>
</section>

<section title="Conventions and Terminology">
<t>
Objectives specify the class of problems that are in the scope of the specification.
</t>

<t>
Use Cases catalog a variety of personal objectives that users may have, due to various motivations and constraints, that the specification shall accommodate, but without prescribing a specific design or implementation.
</t>

<t>
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.
</t>
</section>

<section title="Objectives">
<t>
JSON Schema shall be built to support the following objectives, supporting expansion into uses not currently described by any use case, but which fall within the objectives.
</t>

<section title="Validation">
<t>
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.
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.
</t>
</section>

<section title="Annotation">
<t>
The second objective of JSON Schema is to map an input JSON document to an arbitrary output described by the user.
Annotations may be combined with validation (in the same schema) to specify the domain of inputs for which an output is defined.
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.
</t>
</section>

<section title="Internet">
<t>
JSON is a technology standardized as a part of a larger ecosystem of Internet technology, and likewise, JSON Schema may also specify its role in this ecosystem; for example, use in HTTP, or the meaning of media type parameters.
</t>
</section>

<section title="Out of scope">
<t>
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.
</t>
<t>
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, such as when the API is using JSON and needs a way to describe these JSON documents.
</t>
</section>

</section>

<section title="Use Cases">
<t>
JSON Schema shall be written to standardize these use cases, or shall accommodate implementations targeted at these uses.
</t>

<section title="Structural validation" anchor="uc-structural">
<t>
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).
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
The following features of JSON are structural validation:
</t>
<list>
<t>JSON primitive type (string, object, etc)</t>
<t>Minimum or maximum in a linear range of values</t>
<t>Minimum or maximum lengths (number of characters, digits, items, or properties)</t>
<t>Literal/constant values or alternate/enumerated values</t>
<t>Pattern matching strings by a regular expression (including object keys)</t>
<t>Logic operators (union, intersection, difference)</t>
<t>Descent into object properties and array items (recursively)</t>
</list>
<t>
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.
</t>
</section>

<section title="Semantic annotation" anchor="uc-annotations">
<t>
There is a need to annotate values within a JSON document: for machine readability, and for documentation purposes.
Given a document and directions for annotating it, you should should be able to:
</t>
<list>
<t>document the meaning of a property,</t>
<t>suggest a default value for new documents of a given type,</t>
<t>fill in missing values (in objects or arrays) with values of equivalent meaning,</t>
<t>generate a list of hyperlinks,</t>
<t>or declare relationships between data.</t>
</list>
<t>
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.
</t>
</section>

<section title="Domain-specific language">
<t>
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.
</t>
<t>
Application authors may use a schema to define custom hooks and processing for the JSON (without need for standardizing the customization).
</t>
<t>
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).
</t>
</section>

<section title="A common vocabulary">
<t>
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.
</t>
<t>
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.
</t>
</section>

<section title="Model-Driven UI constraints">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>

<section title="Fuzzing, enumeration, and generation">
<t>
Security applications need to generate examples of JSON documents within the valid set, and outside the valid set.
</t>
</section>

<section title="Embedded database constraints">
<t>
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.
</t>
</section>

<section title="Partial validation" anchor="partial-validation">
<t>
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:
</t>
<list style="symbols">
<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>
<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>
<t>Other validators may have a limited amount of memory and cannot support assertions more complicated than a deterministic context-free grammar.</t>
</list>
<t>
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.
</t>
<t>
<cref>
There's two directions this can work: an application should be able to determine if a third-party schema is making a distinction that it does not support; and an application may want to publish a schema indicating it works in a reduced value space.
</cref>
</t>
</section>

<section title="Machine-readable profiles of Web resources">
<t>
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.
</t>
</section>

<section title="Hypermedia">
<t>
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.
</t>
</section>

<section title="Results and Reporting">
<t>
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).
</t>
</section>

<section title="Extension points" anchor="extension-points">
<t>
Not every feature needs to be supported by every implementation.
To accommodate a wide variety of niche audiences, it should be possible to specify features that are optional to implement.
This includes standardized features that are optional to implement, bespoke or user-defined features that are not standardized, and new features added to future publications of the specification.
For forward compatibility, implementations that do not support optional extensions must degrade in a predictable fashion.
</t>
</section>

<section title="External validation">
<t>
Authors may embed resources of other media types, such as text documents, or base64 or hex-encoded binary documents; and may wish to pass off validation of these documents to another software tool.
</t>
</section>

<section title="Intra-document data consistency validation">
<t>
A JSON document may carry relational data that must be internally consistent. Example constraints include:
</t>
<ul>
<li>One-to-one calculations, like that children's birthdates come after their parent's birthdates;</li>
<li>One-to-many calculations, like a reference to an anchor points to an anchor defined somewhere in the same document.</li>
</ul>
</section>

<section title="Inter-database consistency validation">
<t>
A JSON document may carry relational data that must be verified against outside data sources. Example constraints include:
</t>
<ul>
<li>References to a user ID points to a user in a central users database.</li>
<li>A supplied email address has been verified by the user.</li>
</ul>
</section>

<section title="Linting">
<t>
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.
</t>
<t>
For example, for security reasons, an application may want to verify 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, it could not close the tag and be interpreted as HTML.
</t>
<t>
This is not a standard part of JSON Schema because it may violate the semantics of JSON, by adding an ability to distinguish between encodings which are supposed to be equivalent to receiving applications.
</t>
</section>
</section>

<section title="Security Considerations" anchor="security">
<t>
This document does not make any normative requirements.
</t>
</section>
</middle>

<back>
<!-- References Section -->
<references title="Informative References">
&RFC5234;
&RFC6906;
</references>

</back>
</rfc>

0 comments on commit 4089b1e

Please sign in to comment.