Skip to content

Commit e1116ab

Browse files
handrewshandrews
authored
Merge branch 'master' into media-in-validation
2 parents 0d205ae + 7f401b2 commit e1116ab

File tree

3 files changed

+107
-67
lines changed

3 files changed

+107
-67
lines changed

‎hyper-schema.json

Lines changed: 3 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -10,59 +10,6 @@
1010
"items": { "$ref": "#" }
1111
}
1212
]
13-
},
14-
"linkDescription": {
15-
"title": "Link Description Object",
16-
"type": "object",
17-
"required": [ "href" ],
18-
"properties": {
19-
"href": {
20-
"description": "a URI template, as defined by RFC 6570",
21-
"type": "string",
22-
"format": "uri-template"
23-
},
24-
"hrefSchema": {
25-
"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\"",
26-
"allOf": [ {"$ref": "#"} ]
27-
},
28-
"rel": {
29-
"description": "relation to the target resource of the link",
30-
"type": "string"
31-
},
32-
"anchor": {
33-
"description": "the URI of the context resource",
34-
"type": "string",
35-
"format": "uri-reference"
36-
},
37-
"title": {
38-
"description": "a title for the link",
39-
"type": "string"
40-
},
41-
"description": {
42-
"description": "additional information about the purpose or usage of the link",
43-
"type": "string"
44-
},
45-
"targetSchema": {
46-
"description": "JSON Schema describing the link target",
47-
"allOf": [ { "$ref": "#" } ]
48-
},
49-
"mediaType": {
50-
"description": "media type (as defined by RFC 2046) describing the link target",
51-
"type": "string"
52-
},
53-
"submissionEncType": {
54-
"description": "The media type in which to submit data along with the request",
55-
"type": "string",
56-
"default": "application/json"
57-
},
58-
"submissionSchema": {
59-
"description": "Schema describing the data to submit along with the request",
60-
"allOf": [ { "$ref": "#" } ]
61-
},
62-
"$comment": {
63-
"type": "string"
64-
}
65-
}
6613
}
6714
},
6815
"allOf": [ { "$ref": "http://json-schema.org/draft-06/schema#" } ],
@@ -103,12 +50,13 @@
10350
"propertyNames": { "$ref": "#" },
10451

10552
"base": {
106-
"description": "URI Template resolved as for the 'href' keyword in the Link Description Object. The resulting URI Reference is resolved against the current URI base and sets the new URI base for URI references within the instance.",
10753
"type": "string"
10854
},
10955
"links": {
11056
"type": "array",
111-
"items": { "$ref": "#/definitions/linkDescription" }
57+
"items": {
58+
"$ref": "http://json-schema.org/draft-06/links#"
59+
}
11260
}
11361
},
11462
"links": [

‎jsonschema-hyperschema.xml

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1010
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
1111
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
12+
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1213
]>
1314
<?rfc toc="yes"?>
1415
<?rfc symrefs="yes"?>
@@ -904,6 +905,84 @@ GET /foo/
904905
</section>
905906
</section>
906907

908+
<section title="targetHints" anchor="targetHints">
909+
<t>
910+
<cref>
911+
This section attempts to strike a balance between comprehensiveness
912+
and flexibility by deferring most of its structure to the protocol
913+
indicated by the URI scheme. Note that a resource can be identified
914+
by a URI with a dereferenceable scheme, yet not be accessible over
915+
that protocol. While currently very loose, this section is expected
916+
to become more well-defined based on draft feedback, and may change
917+
significantly in future drafts.
918+
</cref>
919+
</t>
920+
<t>
921+
The value of this property is advisory only. It represents information that
922+
is expected to be discoverable through interacting with the target resource,
923+
typically in the form of protocol-specific control information or meta-data
924+
such as headers returned in response to an HTTP HEAD or OPTIONS request.
925+
The protocol is determined by the "href" URI scheme, although note that
926+
resources are not guaranteed to be accessible over such a protocol.
927+
</t>
928+
<t>
929+
The value of this property SHOULD be an object. The keys to this object
930+
SHOULD be lower-cased forms of the control data field names. Each value
931+
SHOULD be an array, in order to uniformly handle multi-valued fields.
932+
Multiple values MUST be presented as an array, and not as a single string.
933+
</t>
934+
<t>
935+
Protocols with control information not suitable for representation as
936+
a JSON object MAY be represented by another data type, such as an array.
937+
</t>
938+
<t>
939+
Values that cannot be understood as part of the indicated protocol MUST
940+
be ignored by a JSON Hyper-Schema implementation. Applications MAY make
941+
use of such values, but MUST NOT assume interoperability with other
942+
implementations.
943+
</t>
944+
<t>
945+
Implementations MUST NOT assume that all discoverable information is
946+
accounted for in this object. Clients MUST properly handle run-time responses
947+
that contradict this property's values.
948+
</t>
949+
<t>
950+
Clients MUST NOT assume that an implementation will automatically take any
951+
action based on the value of this property.
952+
</t>
953+
<section title='"targetHints" for HTTP'>
954+
<t>
955+
<cref>It would be good to also include a section with CoAP examples.</cref>
956+
</t>
957+
<t>
958+
JSON serializations of HTTP response header information SHOULD follow the
959+
guidelines established by the work in progress
960+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>.
961+
Approaches shown in that document's examples SHOULD be applied to other
962+
similarly structured headers wherever possible.
963+
</t>
964+
<t>
965+
No distinction is made between headers that may appear in responses to
966+
different methods, such as HEAD vs OPTIONS.
967+
</t>
968+
<figure>
969+
<preamble>
970+
This examples shows several hints that are useful for clients
971+
when determining what requests to make and how to make them.
972+
</preamble>
973+
<artwork>
974+
<![CDATA[{
975+
"targetHints": {
976+
"allow": ["GET", "PUT"],
977+
"accept-patch": ["application/merge-patch+json"],
978+
"accept-ranges": ["none"]
979+
}
980+
}]]>
981+
</artwork>
982+
</figure>
983+
</section>
984+
</section>
985+
907986
<section title="mediaType">
908987
<t>
909988
The value of this property is advisory only, and represents the media type
@@ -935,7 +1014,8 @@ GET /foo/
9351014

9361015
<t>
9371016
If this property's value is not specified, then the value should be taken to be
938-
"application/json".
1017+
"application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific
1018+
value in <xref target="targetHints">"targetHints"</xref> for this purpose.
9391019
</t>
9401020

9411021
<figure>
@@ -1110,6 +1190,7 @@ GET /foo/
11101190
&rfc3986;
11111191
<!--&rfc4287;-->
11121192
&rfc6570;
1193+
&I-D.reschke-http-jfv;
11131194
<reference anchor="json-schema">
11141195
<front>
11151196
<title>JSON Schema: A Media Type for Describing JSON Documents</title>

‎links.json

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,49 @@
66
"required": [ "href" ],
77
"properties": {
88
"href": {
9-
"description": "a URI template, as defined by RFC 6570",
109
"type": "string",
1110
"format": "uri-template"
1211
},
1312
"hrefSchema": {
14-
"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\"",
15-
"allOf": [ {"$ref": "#"} ]
13+
"allOf": [
14+
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
15+
]
1616
},
1717
"rel": {
18-
"description": "relation to the target resource of the link",
1918
"type": "string"
2019
},
20+
"anchor": {
21+
"type": "string",
22+
"format": "uri-reference"
23+
},
2124
"title": {
22-
"description": "a title for the link",
25+
"type": "string"
26+
},
27+
"description": {
2328
"type": "string"
2429
},
2530
"targetSchema": {
26-
"description": "JSON Schema describing the link target",
27-
"allOf": [ { "$ref": "hyper-schema#" } ]
31+
"allOf": [
32+
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
33+
]
34+
},
35+
"targetHints": {
36+
"description": "JSON representation of likely metadata such as response headers, with a protocol-dependent format"
2837
},
2938
"mediaType": {
30-
"description": "media type (as defined by RFC 2046) describing the link target",
3139
"type": "string"
3240
},
3341
"submissionEncType": {
34-
"description": "The media type in which to submit data along with the request",
3542
"type": "string",
3643
"default": "application/json"
3744
},
3845
"submissionSchema": {
39-
"description": "Schema describing the data to submit along with the request",
40-
"allOf": [ { "$ref": "hyper-schema#" } ]
46+
"allOf": [
47+
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
48+
]
49+
},
50+
"$comment": {
51+
"type": "string"
4152
}
4253
}
4354
}

0 commit comments

Comments
 (0)