Skip to content

Commit 8d1ce31

Browse files
awwrightawwright
authored
Merge pull request #228 from handrews/hrefschema
Support URI input with "hrefSchema"
2 parents 60e5bae + e4f3667 commit 8d1ce31

File tree

3 files changed

+151
-12
lines changed

3 files changed

+151
-12
lines changed

‎hyper-schema.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@
2020
"description": "a URI template, as defined by RFC 6570, with the addition of the $, ( and ) characters for pre-processing",
2121
"type": "string"
2222
},
23+
"hrefSchema": {
24+
"description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
25+
"allOf": [ {"$ref": "#"} ]
26+
},
2327
"rel": {
2428
"description": "relation to the target resource of the link",
2529
"type": "string"

‎jsonschema-hyperschema.xml

Lines changed: 143 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -366,9 +366,33 @@
366366
The URI of the normative link description schema is: <eref target="http://json-schema.org/draft-04/links">http://json-schema.org/draft-04/links</eref> (draft-04 version).
367367
</t>
368368

369-
<t>
370-
"Form"-like functionality can be defined by use of the "method" and "schema" keywords, which supplies a schema describing the data to supply to the server.
371-
</t>
369+
<section title="Links and data">
370+
<t>
371+
"Form"-like functionality can be defined by use of the <xref target="method">"method"</xref> and <xref target="schema">"schema"</xref> keywords, which supplies a schema describing the data to supply to the server.
372+
Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>.
373+
</t>
374+
<t>
375+
The simplest kind of link has an "href" with no template variables, and no "schema". This does not
376+
allow for any variance in the link URI, nor does it allow for a request document.
377+
</t>
378+
<t>
379+
An "href" with at least one template variable, but no "hrefSchema" or "schema", allows resolving
380+
the template variable from the instance, but does not allow resolving it
381+
from external data, nor does it allow a request document.
382+
</t>
383+
<t>
384+
An "href" with at least one template variable and with an "hrefSchema" allows using external
385+
data to resolve the template, and falls back to resolving any remaining variables from the instance.
386+
</t>
387+
<t>
388+
A link with a "schema" allows submitting external data either as a request body (if "method" is "post"),
389+
or as a URI query string (if "method" is "get"). Such a query string replaces any query string
390+
present after the "href" template is resolved.
391+
</t>
392+
<t>
393+
See the individual keyword descriptions below for details related to each of these cases.
394+
</t>
395+
</section>
372396

373397
<!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure -->
374398

@@ -473,20 +497,32 @@
473497

474498
<section title="Values for substitution">
475499
<t>
476-
After pre-processing, the URI Template is filled out using data from the instance.
500+
After pre-processing, the URI Template is filled out using data from some combination of an externa source and the instance.
501+
Where either instance data or external data may be used, this section will refer simply to "data" or to a "value".
502+
When the source is important, it is specified explicitly.
503+
477504
To allow the use of any object property (including the empty string), array index, or the instance value itself, the following rules are defined:
478505
</t>
479506

480507
<t>
481508
For a given variable name in the URI Template, the value to use is determined as follows:
482509
<list>
483-
<t>If the variable name is "%73elf", then the instance value itself MUST be used.</t>
484-
<t>If the variable name is "%65mpty", then the instances's empty-string ("") property MUST be used (if it exists).</t>
485-
<t>If the instance 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).</t>
510+
<t>If the variable name is "%73elf", then the value itself MUST be used.</t>
511+
<t>If the variable name is "%65mpty", then the empty-string ("") property MUST be used (if it exists).</t>
512+
<t>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).</t>
486513
<t>Otherwise, the variable name should be percent-decoded, and the corresponding object property MUST be used (if it exists).</t>
487514
</list>
488515
</t>
489516

517+
<t>
518+
If <xref target="hrefSchema">"hrefSchema"</xref> is present and
519+
external input is provided, the input MUST be a valid instance according
520+
to the value of "hrefSchema".
521+
Template variables, after the process listed above, MUST first
522+
be resolved from the external data instance. Any variables left
523+
unresolved MUST be resolved from the resource instance data.
524+
</t>
525+
490526
<section title="Converting to strings">
491527
<t>
492528
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:
@@ -506,18 +542,109 @@
506542
<section title="Missing values">
507543
<t>
508544
Sometimes, the appropriate values will not be available.
509-
For example, the template might specify the use of object properties, but the instance is an array or a string.
545+
For example, the template might specify the use of object properties, but no such input was provide (or "hrefSchema" is not present), and the instance is an array or a string.
510546
</t>
511547

512548
<t>
513-
If any of the values required for the template are not present in the JSON instance, then substitute values MAY be provided from another source (such as default values).
549+
If any of the values required for the template are present in neither the user input (if relevant) or the JSON instance, then substitute values MAY be provided from another source (such as default values).
514550
Otherwise, the link definition SHOULD be considered not to apply to the instance.
515551
</t>
516552
</section>
517553
</section>
518554

519555
</section>
520556

557+
<section title="hrefSchema" anchor="hrefSchema">
558+
<t>
559+
The value of the "hrefSchema" link description property MUST be
560+
a valid JSON Schema. This schema is used to validate user input
561+
or other external data for filling out the URI Template in
562+
<xref target="href">"href"</xref>, as described in that section.
563+
</t>
564+
<t>
565+
Omitting "hrefSchema" or setting the entire schema to "false" prevents
566+
any external data from being accepted.
567+
</t>
568+
<t>
569+
Implementations MUST NOT attempt to validate values resolved from
570+
resource instance data with "hrefSchema". This allows for different
571+
validation rules for user input, such as supporting spelled-out
572+
months for date-time input but using the standard date-time
573+
format for storage.
574+
</t>
575+
<figure>
576+
<preamble>
577+
For example, this defines a schema for each of the query string
578+
parameters in the URI template:
579+
</preamble>
580+
<artwork>
581+
<![CDATA[{
582+
"href": "/foos{?condition,count,query}",
583+
"hrefSchema": {
584+
"properties": {
585+
"condition": {
586+
"type": "boolean",
587+
"default": true
588+
},
589+
"count": {
590+
"type": "integer",
591+
"minimum": 0,
592+
"default": 0
593+
},
594+
"query": {
595+
"type": "string"
596+
}
597+
}
598+
}
599+
}]]>
600+
</artwork>
601+
</figure>
602+
<figure>
603+
<preamble>
604+
In this example, the schema for "extra" is given as a reference
605+
to keep the external data validation constraints identical to the
606+
instance validation constraints for the corresponding property,
607+
while "id" is given a false schema to prevent external data for
608+
that variable.
609+
</preamble>
610+
<artwork>
611+
<![CDATA[{
612+
"definitions": {
613+
"extra": {
614+
"type": "string",
615+
"maxLength": 32
616+
}
617+
},
618+
"type": "object",
619+
"properties": {
620+
"id": {
621+
"type": "integer",
622+
"minimum": 1,
623+
"readOnly": true
624+
},
625+
"extra": {"$ref": "#/definitions/extra"}
626+
},
627+
"links": [{
628+
"rel": "self",
629+
"href": "/things/{id}{?extra}",
630+
"hrefSchema": {
631+
"properties": {
632+
"id": false,
633+
"extra": {"$ref": "#/definitions/extra"}
634+
}
635+
}
636+
}]
637+
}]]>
638+
</artwork>
639+
</figure>
640+
<t>
641+
<cref>
642+
The above example simulates the behavior found in earlier drafts using only "hrefSchema",
643+
which would allow the concurrent use of "schema" on a "post" link.
644+
</cref>
645+
</t>
646+
</section>
647+
521648
<section title="rel">
522649
<t>
523650
The value of the "rel" property indicates the name of the relation to the target resource. The value MUST be a registered link relation from the <xref target="RFC5988">IANA Link Relation Type Registry established in RFC 5988</xref>, or a normalized URI following the <xref target="RFC3986">URI production of RFC 3986</xref>.
@@ -784,7 +911,7 @@ GET /foo/
784911
The following properties also apply to Link Description Objects, and provide functionality analogous to <xref target="W3C.CR-html5-20140731">HTML forms</xref>, by providing a means for making a request with client- or user-selected information.
785912
</t>
786913

787-
<section title="method">
914+
<section title="method" anchor="method">
788915
<t>
789916
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
790917
</t>
@@ -839,13 +966,16 @@ GET /foo/
839966
</t>
840967
</section>
841968

842-
<section title="schema">
969+
<section title="schema" anchor="schema">
843970
<t>
844971
This property contains a schema which defines the acceptable structure of the document being encoded according to the "encType" property.
845972
</t>
846973

847974
<t>
848-
Note that this does not provide data for any URI templates.
975+
Note that this does not provide data for any URI templates. That is handed by <xref target="hrefSchema">"hrefSchema"</xref>. If the method is "get" and the resolved URI Template has a query string, the query string produced by input validated agaisnt "schema" replaces the existing query string.
976+
</t>
977+
978+
<t>
849979
This is a separate concept from the "targetSchema" property, which is describing the target information resource (including for replacing the contents of the resource in a PUT request), unlike "schema" which describes the user-submitted request data to be evaluated by the resource.
850980
</t>
851981
</section>
@@ -916,6 +1046,7 @@ GET /foo/
9161046
<t hangText="draft-wright-json-schema-hyperschema-01">
9171047
<list style="symbols">
9181048
<t>Fixed examples</t>
1049+
<t>Added "hrefSchema" for user input to "href" URI Templates</t>
9191050
</list>
9201051
</t>
9211052
<t hangText="draft-wright-json-schema-hyperschema-00">

‎links.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@
99
"description": "a URI template, as defined by RFC 6570, with the addition of the $, ( and ) characters for pre-processing",
1010
"type": "string"
1111
},
12+
"hrefSchema": {
13+
"description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
14+
"allOf": [ {"$ref": "#"} ]
15+
},
1216
"rel": {
1317
"description": "relation to the target resource of the link",
1418
"type": "string"

0 commit comments

Comments
 (0)