Skip to content

Commit ab1da70

Browse files
handrewshandrews
committed
Support URI input with "hrefSchema"
This adds a more flexible and powerful mechansim for allowing user input into the template resolution process. It offers a superset of the functionality available by using the "schema" field with "method"="get".
1 parent a43ed2c commit ab1da70

File tree

3 files changed

+109
-4
lines changed

3 files changed

+109
-4
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: 101 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -473,7 +473,8 @@
473473

474474
<section title="Values for substitution">
475475
<t>
476-
After pre-processing, the URI Template is filled out using data from the instance.
476+
After pre-processing, the URI Template is filled out using data from some combination of user input and the instance.
477+
477478
To allow the use of any object property (including the empty string), array index, or the instance value itself, the following rules are defined:
478479
</t>
479480

@@ -487,6 +488,14 @@
487488
</list>
488489
</t>
489490

491+
<t>
492+
If <xref target="hrefSchema">"hrefSchema"</xref> is present and
493+
user input is provided, the input MUST be valid according to the value of "hrefSchema".
494+
Template variables, after the process listed above, MUST first
495+
be resolved from the user input instance. Any variables left
496+
unresolved MUST be resolved from the resource instance.
497+
</t>
498+
490499
<section title="Converting to strings">
491500
<t>
492501
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 +515,103 @@
506515
<section title="Missing values">
507516
<t>
508517
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.
518+
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.
510519
</t>
511520

512521
<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).
522+
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).
514523
Otherwise, the link definition SHOULD be considered not to apply to the instance.
515524
</t>
516525
</section>
517526
</section>
518527

519528
</section>
520529

530+
<section title="hrefSchema" anchor="hrefSchema">
531+
<t>
532+
The value of the "hrefSchema" link description property MUST be
533+
a valid JSON Schema. This schema is used to validate user input
534+
for filling out the URI Template in
535+
<xref target="href">"href"</xref>, as described in that section.
536+
</t>
537+
<t>
538+
Omitting "hrefSchema" or setting the entire schema to "false" prevents
539+
any user input from being accepted.
540+
</t>
541+
<t>
542+
Implementations MUST NOT attempt to validate values resolved from
543+
instance data with "hrefSchema". This allows for different
544+
validation rules for user input, such as supporting spelled-out
545+
months for date-time input but using the standard date-time
546+
format for storage.
547+
</t>
548+
<figure>
549+
<preamble>
550+
For example, this defines a schema for each of the query string
551+
parameters in the URI template:
552+
</preamble>
553+
<artwork>
554+
<![CDATA[{
555+
"href": "/foos{?condition,count,query}",
556+
"hrefSchema": {
557+
"properties": {
558+
"condition": {
559+
"type": "boolean",
560+
"default": true
561+
},
562+
"count": {
563+
"type": "integer",
564+
"minimum": 0,
565+
"default": 0
566+
},
567+
"query": {
568+
"type": "string"
569+
}
570+
}
571+
}
572+
}]]>
573+
</artwork>
574+
</figure>
575+
<figure>
576+
<preamble>
577+
In this example, the schema for "extra" is given as a reference
578+
to keep the user input validation constraints identical to the
579+
instance validation constraints for the corresponding property,
580+
while "id" is given a false schema to prevent user input for
581+
that variable.
582+
</preamble>
583+
<artwork>
584+
<![CDATA[{
585+
"definitions": {
586+
"extra": {
587+
"type": "string",
588+
"maxLength": 32
589+
}
590+
},
591+
"type": "object",
592+
"properties": {
593+
"id": {
594+
"type": "integer",
595+
"minimum": 1,
596+
"readOnly": true
597+
},
598+
"extra": {"$ref": "#/definitions/extra"}
599+
},
600+
"links": [{
601+
"rel": "self",
602+
"href": "/things/{id}{?extra}",
603+
"hrefSchema": {
604+
"properties": {
605+
"id": false,
606+
"extra": {"$ref": "#/definitions/extra"}
607+
}
608+
}
609+
}]
610+
}]]>
611+
</artwork>
612+
</figure>
613+
</section>
614+
521615
<section title="rel">
522616
<t>
523617
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>.
@@ -845,7 +939,10 @@ GET /foo/
845939
</t>
846940

847941
<t>
848-
Note that this does not provide data for any URI templates.
942+
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.
943+
</t>
944+
945+
<t>
849946
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.
850947
</t>
851948
</section>

‎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)