Use cases: add "objectives" section

Author: awwright

jsonschema-use-cases.xml

@@ -32,7 +32,7 @@
 
         <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. All examples should be realistic examples of how people may use JSON Schema.
+                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">
@@ -64,24 +64,76 @@
 
         <section title="Conventions and Terminology">
             <t>
-                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.
+                Objectives specify the class of problems that are in the scope of the specification.
             </t>
 
             <t>
-                Requirements list functional and non-functional or quality requirements, and the use cases they may be derived from/related to.
+                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.
+            </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.
+            </t>
+
+            <t>
+                Not all implementations are required to implement all requirements. Only requirements that that are required for interoperability are part of the core semantics. Other requirements, where applications can gracefully degrade in the absence of support by an implementation, may be written as extensions.
             </t>
         </section>
-expressed as a context-free grammar that follows JSON
+
+        <section title="Objectives">
+            <t>
+                JSON Schema shall be built to support two objectives, including unstandardized uses, not described by any use case, but that fall within an objective.
+            </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 how it is used 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, in the cases where describing JSON documents is necessary.
+                </t>
+            </section>
+
+        </section>
+
         <section title="Use Cases">
+            <t>
+                JSON Schema shall standardize these use cases.
+            </t>
+
             <section title="Structural validation" anchor="uc-structural">
                 <t>
-                    Structural validation refers to define the "structure" or pattern 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. More specifically, structural validation is any validation that can be expressed as a context-free grammar that follows JSON semantics, so that different forms which are equal according to JSON will be guaranteed to have the same validation result.
+                    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. comparing two values for equality), though constraints may be added depending on "where" the value is found (e.g. a specific property or array item must have a number as its value).
                 </t>
                 <t>
-                    Validators that support structural validation can entirely replace generic grammar languages such as <xref target="RFC5234">ABNF</xref> and in addition, guarantee compliance with JSON semantics. Schemas whose validation is limited to structural validation can be implemented as a deterministic pushdown automata, and guarantee a result in proportional time without error.
+                    More specifically, structural validation is any validation that can be expressed as a context-free grammar that follows JSON semantics, so that different forms which are equal according to JSON will be guaranteed to have the same validation result.
                 </t>
                 <t>
-                    The following features of JSON are part of structural validation:
+                    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>
@@ -90,7 +142,7 @@ expressed as a context-free grammar that follows JSON
                     <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</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.
@@ -116,19 +168,19 @@ expressed as a context-free grammar that follows JSON
 
             <section title="Domain-specific language">
                 <t>
-                    Application authors may use an entirely self-contained schema inside an application that consumes JSON. By using a declarative language, the application requirements can be better optimized by the application.
+                    Application authors may use an entirely self-contained schema inside an application that consumes JSON. By using a declarative language, the application requirements can be optimized better than a human could do.
                 </t>
                 <t>
-                    Application authors may define custom hooks and processing for the JSON (without need for standardizing the customization).
+                    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 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).
+                    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 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.
+                    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.
@@ -140,7 +192,10 @@ expressed as a context-free grammar that follows JSON
                     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>
-                    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.
+                    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>
 
@@ -152,7 +207,7 @@ expressed as a context-free grammar that follows JSON
 
             <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 use JSON Schema as a way to annotate certain fields as having a special meaning for uniqueness or indexing purposes.
+                    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>
 
@@ -163,7 +218,7 @@ expressed as a context-free grammar that follows JSON
                 <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, because this form is read by the application.</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 in the Chomsky hierarchy (i.e. validation not describable by a deterministic pushdown automata).</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 correct understanding, and if not, get a validation result that would be correct but-for the unimplemented functionality.
@@ -187,6 +242,12 @@ expressed as a context-free grammar that follows JSON
                 </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>
                     Application developers may wish to express a wide variety of constraints that would be impractical to require every validator to implement.
@@ -199,7 +260,7 @@ expressed as a context-free grammar that follows JSON
 
         <section title="Use cases for extensions">
             <t>
-                This section lists use cases that are not required for interoperability in media type handling, but which should be defined as standard extensions to maximize support and feature interoperability.
+                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.
                 As specified in <xref target="extension-points">"Extension points,"</xref>
                 validators should gracefully degrade in the presence of extensions that they do not support.
             </t>
@@ -235,10 +296,10 @@ expressed as a context-free grammar that follows JSON
                     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, a linter may need to ensure that a JSON document does not contain the string "&lt;/script" but instead contains a character escape such as "&lt;\/script". This would ensure that, if the JSON were to be embedded in a &lt;script&gt; tag, that it would not have any part that could be interpreted as HTML.
+                    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.
                 </t>
                 <t>
-                    This is not a core part of JSON because it may violate the semantics of JSON, adding an ability to distinguish two document that JSON requires be equal to the receiving application.
+                    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.
                 </t>
             </section>