diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 2d6edfac..05b6484b 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -353,60 +353,6 @@
at runtime, for instance due to application state that controls the operation's
availability.
-
-
- URI Template variables in "href" resolve from
- server-supplied instance data by default. This data is drawn from the
- sub-instance that validated against the schema containing the LDO.
-
-
- "templatePointers" allows adjusting
- the location from which instance data is resolved on a per-variable
- basis.
-
-
- "hrefSchema" allows a link to specify
- a schema for resolving template variables from client-supplied data.
- Regular JSON Schema validation features can be used to require resolution
- from user agent data, forbid it, or allow user agent data while falling back
- to server-supplied instance data if no user agent data is provided.
-
-
- To implement the common pattern of resolving a templated path component
- with server-supplied instance data while accepting user agent data to build
- a query string:
-
-
- set the "hrefSchema" subschemas for the path template variables
- to false, to disallow user agent input
-
-
- give the query string template variables names that do not appear
- in the instance, to prevent resolving them from the instance
-
-
- See the "hrefSchema" section for an example of this approach.
-
-
- To implement the equivalent of an input form pre-populated with
- pre-existing instance data:
-
-
- ensure that each variable in the form resolves from the appropriate
- field in the instance, which provides the initial value that will
- continue to be used if the user agent takes no action to change it
-
- provide a validation schema for each of those fields in
- "hrefSchema", to describe what user agent input may be allowed
- to replace it
-
-
- This can be done with variables in any component of the URI template
- (path, query string, etc.) While the word "form" is used here,
- JSON Hyper-Schema does not constraint the nature of this interaction, which
- may or may not involve rendering an interactive form.
-
-
In JSON Hyper-Schema, "targetSchema"
@@ -451,112 +397,6 @@
This property is REQUIRED.
-
-
-
- The pre-processing rules present in earlier drafts have been removed due
- to their complexity and inability to address all limitations with URI
- templating.
- This section is subject to significant change in upcoming drafts to
- replace the old pre-processing with a comprehensive solution.
-
-
-
- The value of "href" is to be used as a URI Template, as defined in
- RFC 6570.
- However, some special considerations apply:
-
-
-
-
- The URI Template is filled out using data from some combination of an
- external source and the instance.
- Where either instance data or user agent data may be used, this section
- will refer simply to "data" or to a "value".
- When the source is important, it is specified explicitly.
-
- To allow the use of any object property (including the empty string) or
- array index, the following rules are defined:
-
-
-
- For a given variable name in the URI Template, the value to use is
- determined as follows:
-
-
- If the data is an array, and the variable name is a
- representation of a non-negative integer, then the value at the
- corresponding array index MUST be used (if it exists).
-
-
- Otherwise, the variable name should be percent-decoded, and the
- corresponding object property MUST be used (if it exists).
-
-
-
-
-
- If "hrefSchema" is present and
- user agent data is provided, the data MUST be a valid instance according
- to the value of "hrefSchema".
- Template variables, after the process listed above, MUST first
- be resolved from the user agent data instance. Any variables left
- unresolved MUST be resolved from the resource instance data.
-
-
-
-
- When any value referenced by the URI template is null, a boolean or
- a number, then it should first be converted into a string as
- follows:
-
-
- null values SHOULD be replaced by the text "null"
-
-
- boolean values SHOULD be replaced by their lower-case
- equivalents: "true" or "false"
-
-
- numbers SHOULD be replaced with their original JSON
- representation.
-
-
-
-
- In some software environments the original JSON representation of a
- number will not be available (there is no way to tell the difference
- between 1.0 and 1), so any reasonable representation should be used.
- Schema and API authors should bear this in mind, and use other types
- (such as string or boolean) if the exact representation is
- important.
-
-
-
-
-
-
- Sometimes, the appropriate values will not be available. In many
- cases, the URI Template behavior of simply removing variables that
- do not have a value will be appropriate. An example of this is
- optional query parameters, the presence or absence of which does
- not change the nature of the link relation type.
-
-
-
- However, some variables, such as an identifier used in a path component,
- cannot meaningfully be omitted. The resulting URI would be meaningless,
- or would require a different link relation type. While "hrefSchema" can
- express a requirement for those variables that can be supplied via input,
- some variables must be resolved from instance data. When that instance
- data is not required by the context schema, the
- "templateRequired keyword may
- be used to indicate that when the instance data is not available, the
- link does not apply.
-
-
-
-
@@ -676,11 +516,21 @@
any user agent data from being accepted.
- Implementations MUST NOT attempt to validate values resolved from
- resource instance data with "hrefSchema". This allows for different
+ Setting any subschema that applies to a particular variable to "false"
+ prevents any user agent data from being accepted for that single variable.
+
+
+ For template variables that can be resolved from the instance data,
+ if the instance data is valid against all applicable subschemas
+ in "hrefSchema", then it MUST be used to pre-populate the input
+ data set for that variable.
+
+
+ Note that even when data is pre-populated from the instance, the validation
+ schema for that variable in "hrefSchema" need not be identical to the validation
+ schema(s) that apply to the instance data's location. This allows for different
validation rules for user agent data, such as supporting spelled-out
- months for date-time input but using the standard date-time
- format for storage.
+ months for date-time input, but using the standard date-time format for storage.
@@ -711,7 +561,7 @@
- In this example, the schema for "extra" is given as a reference
+ In the following example, the schema for "extra" is given as a reference
to keep the user agent data validation constraints identical to the
instance validation constraints for the corresponding property,
while "id" is given a false schema to prevent user agent data for
@@ -957,7 +807,7 @@ GET /foo/
This property changes the point within the instance that is considered
to be the context resource of the link. The value of the property MUST be a
- valid JSON Pointer, or a valid
+ valid JSON Pointer, or a valid
Relative JSON Pointer
which is evaluated relative to the position in the instance from which
"href" template variable resolution would
@@ -1539,6 +1389,221 @@ GET /foo/
+
+
+ Three hyper-schema keywords are URI Templates:
+ "base", "anchor", and "href". Each are resolved separately to URI-references,
+ and then the anchor or href URI-reference is resolved against the base (which
+ is itself resolved against earlier bases as needed, each of which was first
+ resolved from a URI Template to a URI-reference).
+
+
+ All three keywords share the same algorithm for resolving variables from
+ instance data, which makes use of the "templatePointers" and "templateRequired"
+ keywords. When resolving "href", both it and any "base" templates
+ needed for resolution to an absolute URI, the algorithm is modified to
+ optionally accept user input based on the "hrefSchema" keyword.
+
+
+ For each URI Template (T), the following pseudocode describes an algorithm for
+ resolving T into a URI-reference (R). For the purpose of this algorithm:
+
+
+ "ldo.templatePointers" is an empty object if the keyword was not
+ present and "ldo.templateRequired" is likewise an empty array.
+
+
+ "attachmentPointer" is the absolute JSON Pointer for the attachment
+ location of the LDO.
+
+
+ "getApplicableSchemas()" returns an iterable set of all (sub)schemas
+ that apply to the attachment point in the instance.
+
+
+
+
+ This algorithm should be applied first to either "href" or "anchor",
+ and then as needed to each successive "base". The order is important,
+ as it is not always possible to tell whether a template will resolve
+ to a full URI or a URI-reference.
+
+
+ In English, the high-level algorithm is:
+
+ Populate template variable data from the instance
+ If input is desired, accept input
+ Check that all required variables have a value
+ Encode values into strings and fill out the template
+
+
+
+
+ This is the high-level algorithm as pseudocode. "T" comes from either
+ "href" or "anchor" within the LDO, or from "base" in a containing schema.
+ Pseudocode for each step follows. "initialTemplateKeyword" indicates
+ which of the two started the process (since "base" is always resolved
+ in order to finish resolving one or the other of those keywords).
+
+
+
+
+
+
+
+
+ This step looks at various locations in the instance for variable values.
+ For each variable:
+
+
+ Use "templatePointers" to find a value if the variable
+ appears in that keyword's value
+
+
+ Otherwise, look for a property name matching the variable in
+ the instance location to which the link is attached
+
+
+ In either case, if there is a value at the location, put it in
+ the template resolution data set
+
+
+
+
+
+
+
+
+
+
+
+
+ This step is relatively complex, as there are several cases to support.
+ Some variables will forbid input and some will allow it. Some will
+ have initial values that need to be presented in the input interface,
+ and some will not.
+
+
+
+ Figure out which variables can accept input
+
+ Pre-populate the input data set if the template resolution data
+ set has a value
+
+ Accept input (present a web form, make a callback, etc.)
+ Validate the input data set, (not the template resolution data set)
+
+ Put the input in the template resolution data set, overriding
+ any existing values
+
+
+
+
+
+ "InputForm" represents whatevers sort of input mechanism is appropriate.
+ This may be a literal web form, or may be a more programmatic construct
+ such as a callback function accepting specific fields and data types,
+ with the given initial values, if any.
+
+
+
+
+
+
+
+
+
+ This section is straightforward, converting literals to their names
+ as strings, and converting numbers to strings in the most obvious manner,
+ and percent-encoding as needed for use in the URI.
+
+
+
+
+
+
+ In some software environments the original JSON representation of a
+ number will not be available (there is no way to tell the difference
+ between 1.0 and 1), so any reasonable representation should be used.
+ Schema and API authors should bear this in mind, and use other types
+ (such as string or boolean) if the exact representation is
+ important. If the number was provide as input in the form of a
+ string, the string used as input SHOULD be used.
+
+
+
+