Skip to content

Commit 2e4f18c

Browse files
committed
Prefix "schema" and "encType" with "submission"
These "schema" keyword is too generic of a name given that there are now three schemas involved in an LDO. Change it to indicate that it is used for submitting data for processing, as is done with HTML form submissions. Rename "encType" to match.
1 parent 436b1b4 commit 2e4f18c

File tree

1 file changed

+20
-15
lines changed

1 file changed

+20
-15
lines changed

jsonschema-hyperschema.xml

+20-15
Original file line numberDiff line numberDiff line change
@@ -390,15 +390,15 @@
390390

391391
<section title="Links and data">
392392
<t>
393-
"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.
393+
"Form"-like functionality can be defined by use of the <xref target="method">"method"</xref> and <xref target="submissionSchema">"submissionSchema"</xref> keywords, which supplies a schema describing the data to supply to the server.
394394
Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>.
395395
</t>
396396
<t>
397-
The simplest kind of link has an "href" with no template variables, and no "schema". This does not
397+
The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not
398398
allow for any variance in the link URI, nor does it allow for a request document.
399399
</t>
400400
<t>
401-
An "href" with at least one template variable, but no "hrefSchema" or "schema", allows resolving
401+
An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving
402402
the template variable from the instance, but does not allow resolving it
403403
from external data, nor does it allow a request document.
404404
</t>
@@ -407,7 +407,7 @@
407407
data to resolve the template, and falls back to resolving any remaining variables from the instance.
408408
</t>
409409
<t>
410-
A link with a "schema" allows submitting external data either as a request body (if "method" is "post"),
410+
A link with a "submissionSchema" allows submitting external data either as a request body (if "method" is "post"),
411411
or as a URI query string (if "method" is "get"). Such a query string replaces any query string
412412
present after the "href" template is resolved.
413413
</t>
@@ -580,7 +580,7 @@
580580
<t>
581581
<cref>
582582
The above example simulates the behavior found in earlier drafts using only "hrefSchema",
583-
which would allow the concurrent use of "schema" on a "post" link.
583+
which would allow the concurrent use of "submissionSchema" on a "post" link.
584584
</cref>
585585
</t>
586586
</section>
@@ -702,7 +702,7 @@ GET /foo/
702702
</t>
703703
</section>
704704

705-
<section title="targetSchema">
705+
<section title="targetSchema" anchor="targetSchema">
706706
<t>
707707
This property provides a schema that is expected to describe
708708
the link target's representation. Depending on the protocol,
@@ -883,7 +883,7 @@ GET /foo/
883883
</t>
884884
</section>
885885

886-
<section title="encType">
886+
<section title="submissionEncType" anchor="submissionEncType">
887887
<t>
888888
If present, this property indicates the media type format the client should use to encode a query parameter or send to the server.
889889
If the method is "get", this will indicate how to encode the query-string that is appended to the "href" link target.
@@ -894,10 +894,10 @@ GET /foo/
894894
<artwork>
895895
<![CDATA[{
896896
"links": [{
897-
"encType": "application/x-www-form-urlencoded",
897+
"submissionEncType": "application/x-www-form-urlencoded",
898898
"method": "get",
899899
"href": "/Product/",
900-
"schema": {
900+
"submissionSchema": {
901901
"properties": {
902902
"name": {
903903
"description": "name of the product"
@@ -936,7 +936,7 @@ GET /foo/
936936
<artwork>
937937
<![CDATA[{
938938
"links": [{
939-
"encType": "multipart/alternative; boundary=abc123",
939+
"submissionEncType": "multipart/alternative; boundary=ab12",
940940
"method": "post",
941941
"rel": "author",
942942
"href": "mailto:[email protected]{?subject}",
@@ -947,7 +947,7 @@ GET /foo/
947947
},
948948
"required": ["subject"]
949949
},
950-
"schema": {
950+
"submissionSchema": {
951951
"type": "array",
952952
"items": [
953953
{
@@ -968,17 +968,19 @@ GET /foo/
968968
</t>
969969
</section>
970970

971-
<section title="schema" anchor="schema">
971+
<section title="submissionSchema" anchor="submissionSchema">
972972
<t>
973-
This property contains a schema which defines the acceptable structure of the document being encoded according to the "encType" property.
973+
This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" property.
974974
</t>
975975

976976
<t>
977-
Note that this does not define the structure for URI template variables. 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 against "schema" replaces the existing query string.
977+
Note that this does not define the structure for URI template variables. 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 against "submissionSchema" replaces the existing query string.
978978
</t>
979979

980980
<t>
981-
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.
981+
This is a separate concept from the <xref target="targetSchema">"targetSchema"</xref> property, which is describing the target information resource (including for replacing the contents of the resource in a PUT request), unlike "submissionSchema" which describes the user-submitted request data to be evaluated by the resource.
982+
"submissionSchema" is intended for use with requests that have payloads that are not
983+
defined in terms of the target representation.
982984
</t>
983985
</section>
984986
</section>
@@ -1056,6 +1058,9 @@ GET /foo/
10561058
<t>Removed URI Template pre-processing</t>
10571059
<t>Clarified how links and data submission work</t>
10581060
<t>Clarified how validation keywords apply hyper-schema keywords and links</t>
1061+
<t>Clarified HTTP use with "targetSchema"</t>
1062+
<t>Renamed "schema" to "submissionSchema"</t>
1063+
<t>Renamed "encType" to "submissionEncType"</t>
10591064
</list>
10601065
</t>
10611066
<t hangText="draft-wright-json-schema-hyperschema-00">

0 commit comments

Comments
 (0)