Skip to content

Commit dfe513d

Browse files
handrewshandrews
committed
Normalize "client" terminology
Avoid "client" on its own where possible. Use "client application", "user agent", and "client input" as defined in the Terminology section to clarify roles and responsibilities.
1 parent 92fc8cb commit dfe513d

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
@@ -612,8 +612,8 @@
612612
serialization formats. User agents MAY use this information to inform
613613
the interface they present to the user before the link is followed,
614614
but MUST NOT use this information in the interpretation of the resulting
615-
data. Instead, a client MUST use the media type given by the response for
616-
run-time interpretation. See the section on
615+
data. Instead, a user agent MUST use the media type given by the response
616+
for run-time interpretation. See the section on
617617
<xref target="security">"Security Concerns"</xref> for a detailed
618618
examination of mis-use of "targetMediaType".
619619
</t>
@@ -682,12 +682,12 @@
682682
</t>
683683
<t>
684684
Implementations MUST NOT assume that all discoverable information is
685-
accounted for in this object. Clients MUST properly handle run-time
686-
responses that contradict this property's values.
685+
accounted for in this object. Client applications MUST properly handle
686+
run-time responses that contradict this property's values.
687687
</t>
688688
<t>
689-
Clients MUST NOT assume that an implementation will automatically take any
690-
action based on the value of this property.
689+
Client applications MUST NOT assume that an implementation will
690+
automatically take any action based on the value of this property.
691691
</t>
692692
<t>
693693
See <xref target="HTTP">"JSON Hyper-Schema and HTTP"</xref> for
@@ -697,9 +697,9 @@
697697
</section>
698698
<section title="Link Input" anchor="input">
699699
<t>
700-
There are four ways to use client-supplied data with a link, and each
700+
There are four ways to use client input with a link, and each
701701
is addressed by a separate link description object keyword. When performing
702-
operations, clients SHOULD ignore schemas that are not relevant to their
702+
operations, user agents SHOULD ignore schemas that are not relevant to their
703703
semantics.
704704
</t>
705705
<section title="hrefSchema" anchor="hrefSchema">
@@ -760,12 +760,13 @@
760760
</t>
761761
<t>
762762
The purpose of this keyword is to advertise target resource interaction
763-
features, and indicate to clients what headers and header values are
764-
likely to be useful. Clients MAY use the schema to validate relevant
763+
features, and indicate to user agents and client applications what headers
764+
and header values are likely to be useful.
765+
User agents and client applications MAY use the schema to validate relevant
765766
headers, but MUST NOT assume that missing headers or values are forbidden
766767
from use. While schema authors MAY set "additionalProperties" to
767-
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
768-
from supplying additional headers when requests are made.
768+
false, this is NOT RECOMMENDED and MUST NOT prevent client applications
769+
or user agents from supplying additional headers when requests are made.
769770
</t>
770771
<t>
771772
The exact mapping of the JSON data model into the headers is
@@ -778,23 +779,24 @@
778779
</t>
779780
<t>
780781
"headerSchema" is applicable to any request method or command that the
781-
protocol supports. When generating a request, clients SHOULD ignore
782-
schemas for headers that are not relevant to that request.
782+
protocol supports. When generating a request, user agents and client
783+
applications SHOULD ignore schemas for headers that are not relevant
784+
to that request.
783785
</t>
784786
</section>
785787

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

0 commit comments

Comments
 (0)