Skip to content

Commit bfc5fda

Browse files
handrewshandrews
authored
Merge pull request #493 from handrews/client-vocab
Normalize "client" terminology
2 parents 3fc5d1b + dfe513d commit bfc5fda

File tree

1 file changed

+40
-36
lines changed

1 file changed

+40
-36
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 40 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -611,8 +611,8 @@
611611
serialization formats. User agents MAY use this information to inform
612612
the interface they present to the user before the link is followed,
613613
but MUST NOT use this information in the interpretation of the resulting
614-
data. Instead, a client MUST use the media type given by the response for
615-
run-time interpretation. See the section on
614+
data. Instead, a user agent MUST use the media type given by the response
615+
for run-time interpretation. See the section on
616616
<xref target="security">"Security Concerns"</xref> for a detailed
617617
examination of mis-use of "targetMediaType".
618618
</t>
@@ -681,12 +681,12 @@
681681
</t>
682682
<t>
683683
Implementations MUST NOT assume that all discoverable information is
684-
accounted for in this object. Clients MUST properly handle run-time
685-
responses that contradict this property's values.
684+
accounted for in this object. Client applications MUST properly handle
685+
run-time responses that contradict this property's values.
686686
</t>
687687
<t>
688-
Clients MUST NOT assume that an implementation will automatically take any
689-
action based on the value of this property.
688+
Client applications MUST NOT assume that an implementation will
689+
automatically take any action based on the value of this property.
690690
</t>
691691
<t>
692692
See <xref target="HTTP">"JSON Hyper-Schema and HTTP"</xref> for
@@ -696,9 +696,9 @@
696696
</section>
697697
<section title="Link Input" anchor="input">
698698
<t>
699-
There are four ways to use client-supplied data with a link, and each
699+
There are four ways to use client input with a link, and each
700700
is addressed by a separate link description object keyword. When performing
701-
operations, clients SHOULD ignore schemas that are not relevant to their
701+
operations, user agents SHOULD ignore schemas that are not relevant to their
702702
semantics.
703703
</t>
704704
<section title="hrefSchema" anchor="hrefSchema">
@@ -759,12 +759,13 @@
759759
</t>
760760
<t>
761761
The purpose of this keyword is to advertise target resource interaction
762-
features, and indicate to clients what headers and header values are
763-
likely to be useful. Clients MAY use the schema to validate relevant
762+
features, and indicate to user agents and client applications what headers
763+
and header values are likely to be useful.
764+
User agents and client applications MAY use the schema to validate relevant
764765
headers, but MUST NOT assume that missing headers or values are forbidden
765766
from use. While schema authors MAY set "additionalProperties" to
766-
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
767-
from supplying additional headers when requests are made.
767+
false, this is NOT RECOMMENDED and MUST NOT prevent client applications
768+
or user agents from supplying additional headers when requests are made.
768769
</t>
769770
<t>
770771
The exact mapping of the JSON data model into the headers is
@@ -777,23 +778,24 @@
777778
</t>
778779
<t>
779780
"headerSchema" is applicable to any request method or command that the
780-
protocol supports. When generating a request, clients SHOULD ignore
781-
schemas for headers that are not relevant to that request.
781+
protocol supports. When generating a request, user agents and client
782+
applications SHOULD ignore schemas for headers that are not relevant
783+
to that request.
782784
</t>
783785
</section>
784786

785787
<section title="Manipulating the Target Resource Representation">
786788
<t>
787789
In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
788790
supplies a non-authoritative description of the target resource's
789-
representation. A client can use "targetSchema" to structure input for
790-
replacing or modifying the representation, or as the base representation
791-
for building a patch document based on a patch media type.
791+
representation. A client application can use "targetSchema" to structure
792+
input for replacing or modifying the representation, or as the base
793+
representation for building a patch document based on a patch media type.
792794
</t>
793795
<t>
794-
Alternatively, if "targetSchema" is absent or if the client prefers to
795-
only use authoritative information, it can interact with the target
796-
resource to confirm or discover its representation structure.
796+
Alternatively, if "targetSchema" is absent or if the client application
797+
prefers to only use authoritative information, it can interact with the
798+
target resource to confirm or discover its representation structure.
797799
</t>
798800
<t>
799801
"targetSchema" is not intended to describe link operation responses,
@@ -817,7 +819,8 @@
817819
<section title="submissionMediaType" anchor="submissionMediaType">
818820
<t>
819821
If present, this property indicates the media type format the
820-
client should use for the request payload described by
822+
client application and user agent should use for the request
823+
payload described by
821824
<xref target="submissionSchema">"submissionSchema"</xref>.
822825
</t>
823826
<t>
@@ -910,7 +913,7 @@
910913
</t>
911914
<t hangText="attachmentPointer">
912915
The JSON Pointer for the location within the instance to which the
913-
link is attached. By default, "contextUri" and "attachementUri" are
916+
link is attached. By default, "contextUri" and "attachmentUri" are
914917
the same, but "contextUri" can be changed by LDO keywords, while
915918
"attachmentUri" cannot.
916919
</t>
@@ -1345,11 +1348,11 @@ for varname in templateData:
13451348
<t>
13461349
Since the semantics of many HTTP methods are defined in terms of the target
13471350
resource, "targetSchema" is used for requests and/or responses for several
1348-
HTTP methods.
1349-
In particular, "targetSchema" suggests what a client can expect for the
1350-
response to an HTTP GET or any response for which the "Content-Location"
1351-
header is equal to the request URI, and what a client should send if it
1352-
replaces the resource in an HTTP PUT request.
1351+
HTTP methods. In particular, "targetSchema" suggests what a client
1352+
application can expect for the response to an HTTP GET or any response
1353+
for which the "Content-Location" header is equal to the request URI,
1354+
and what a client application should send if it replaces the resource
1355+
in an HTTP PUT request.
13531356
These correlations are defined by <xref target="RFC7231">RFC 7231,
13541357
section 4.3.1 - "GET", section 4.3.4 "PUT", and section 3.1.4.2,
13551358
"Content-Location"</xref>.
@@ -1483,8 +1486,8 @@ for varname in templateData:
14831486
include the URI(s) of the schema(s) to which the negotiated representation
14841487
is expected to conform. One possible use for schema parameters in
14851488
content negotiation is if the resource has conformed to several different
1486-
schema versions over time. The client can indicate what version(s) it
1487-
understands in the "Accept" header in this way.
1489+
schema versions over time. The client application can indicate what version(s)
1490+
it understands in the "Accept" header in this way.
14881491
</t>
14891492
</section>
14901493
</section>
@@ -1772,10 +1775,10 @@ Link: <https://schema.example.com/entry> rel=describedBy
17721775
<t hangText="title:">
17731776
The instance field matching this variable is required, and it is also
17741777
allowed in the input data. So its instance value is used to
1775-
pre-populate the input data set before accepting the client's input.
1776-
The client can opt to leave the instance value in place. Since
1777-
this field is required in "hrefSchema", the client cannot delete it
1778-
(although it could set it to an empty string).
1778+
pre-populate the input data set before accepting client input. The
1779+
client application can opt to leave the instance value in place. Since
1780+
this field is required in "hrefSchema", the client application cannot
1781+
delete it (although it could set it to an empty string).
17791782
</t>
17801783
<t hangText="cc:">
17811784
The "false" schema set for this in the main schema prevents this field
@@ -1799,7 +1802,7 @@ Link: <https://schema.example.com/entry> rel=describedBy
17991802
</figure>
18001803
<t>
18011804
We can partially resolve the link as follows, before asking the client
1802-
for input.
1805+
application for input.
18031806
</t>
18041807
<figure>
18051808
<artwork>
@@ -2407,8 +2410,9 @@ Link: <https://api.example.com/trees/1/nodes/456> rev=up
24072410
</cref>
24082411
</t>
24092412
<t>
2410-
Clients MUST NOT use the value of "targetSchema" to aid in the interpretation
2411-
of the data received in response to following the link, as this leaves
2413+
User agents or client applications MUST NOT use the value of "targetSchema"
2414+
to aid in the interpretation of the data received in response to following
2415+
the link, as this leaves
24122416
"safe" data open to re-interpretation.
24132417
</t>
24142418
<t>

0 commit comments

Comments
 (0)