Skip to content

Commit bd5729d

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 bd5729d

File tree

3 files changed

+110
-4
lines changed

3 files changed

+110
-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: 102 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -377,6 +377,7 @@
377377
The value of the "href" link description property is a template used to determine the target URI of the related resource.
378378
The value of the instance property MUST be resolved as a <xref target="RFC3986">URI-reference</xref> against the base URI of the instance.
379379
</t>
380+
380381
<t>
381382
This property is REQUIRED.
382383
</t>
@@ -473,7 +474,8 @@
473474

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

@@ -487,6 +489,14 @@
487489
</list>
488490
</t>
489491

492+
<t>
493+
If <xref target="hrefSchema">"hrefSchema"</xref> is present and
494+
user input is provided, the input MUST be valid according to the value of "hrefSchema".
495+
Template variables, after the process listed above, MUST first
496+
be resolved from the user input instance. Any variables left
497+
unresolved MUST be resolved from the resource instance.
498+
</t>
499+
490500
<section title="Converting to strings">
491501
<t>
492502
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 +516,103 @@
506516
<section title="Missing values">
507517
<t>
508518
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.
519+
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.
510520
</t>
511521

512522
<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).
523+
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).
514524
Otherwise, the link definition SHOULD be considered not to apply to the instance.
515525
</t>
516526
</section>
517527
</section>
518528

519529
</section>
520530

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

847942
<t>
848-
Note that this does not provide data for any URI templates.
943+
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.
944+
</t>
945+
946+
<t>
849947
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.
850948
</t>
851949
</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)