From dfe513df01fce9fa5a0dfc68bcf42dce3f818c84 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 26 Oct 2017 10:07:37 -0700 Subject: [PATCH] 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. --- jsonschema-hyperschema.xml | 76 ++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 36 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 086e7bae..274cee78 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -612,8 +612,8 @@ serialization formats. User agents MAY use this information to inform the interface they present to the user before the link is followed, but MUST NOT use this information in the interpretation of the resulting - data. Instead, a client MUST use the media type given by the response for - run-time interpretation. See the section on + data. Instead, a user agent MUST use the media type given by the response + for run-time interpretation. See the section on "Security Concerns" for a detailed examination of mis-use of "targetMediaType". @@ -682,12 +682,12 @@ Implementations MUST NOT assume that all discoverable information is - accounted for in this object. Clients MUST properly handle run-time - responses that contradict this property's values. + accounted for in this object. Client applications MUST properly handle + run-time responses that contradict this property's values. - Clients MUST NOT assume that an implementation will automatically take any - action based on the value of this property. + Client applications MUST NOT assume that an implementation will + automatically take any action based on the value of this property. See "JSON Hyper-Schema and HTTP" for @@ -697,9 +697,9 @@
- There are four ways to use client-supplied data with a link, and each + There are four ways to use client input with a link, and each is addressed by a separate link description object keyword. When performing - operations, clients SHOULD ignore schemas that are not relevant to their + operations, user agents SHOULD ignore schemas that are not relevant to their semantics.
@@ -760,12 +760,13 @@ The purpose of this keyword is to advertise target resource interaction - features, and indicate to clients what headers and header values are - likely to be useful. Clients MAY use the schema to validate relevant + features, and indicate to user agents and client applications what headers + and header values are likely to be useful. + User agents and client applications MAY use the schema to validate relevant headers, but MUST NOT assume that missing headers or values are forbidden from use. While schema authors MAY set "additionalProperties" to - false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents - from supplying additional headers when requests are made. + false, this is NOT RECOMMENDED and MUST NOT prevent client applications + or user agents from supplying additional headers when requests are made. The exact mapping of the JSON data model into the headers is @@ -778,8 +779,9 @@ "headerSchema" is applicable to any request method or command that the - protocol supports. When generating a request, clients SHOULD ignore - schemas for headers that are not relevant to that request. + protocol supports. When generating a request, user agents and client + applications SHOULD ignore schemas for headers that are not relevant + to that request.
@@ -787,14 +789,14 @@ In JSON Hyper-Schema, "targetSchema" supplies a non-authoritative description of the target resource's - representation. A client can use "targetSchema" to structure input for - replacing or modifying the representation, or as the base representation - for building a patch document based on a patch media type. + representation. A client application can use "targetSchema" to structure + input for replacing or modifying the representation, or as the base + representation for building a patch document based on a patch media type. - Alternatively, if "targetSchema" is absent or if the client prefers to - only use authoritative information, it can interact with the target - resource to confirm or discover its representation structure. + Alternatively, if "targetSchema" is absent or if the client application + prefers to only use authoritative information, it can interact with the + target resource to confirm or discover its representation structure. "targetSchema" is not intended to describe link operation responses, @@ -818,7 +820,8 @@
If present, this property indicates the media type format the - client should use for the request payload described by + client application and user agent should use for the request + payload described by "submissionSchema". @@ -911,7 +914,7 @@ The JSON Pointer for the location within the instance to which the - link is attached. By default, "contextUri" and "attachementUri" are + link is attached. By default, "contextUri" and "attachmentUri" are the same, but "contextUri" can be changed by LDO keywords, while "attachmentUri" cannot. @@ -1346,11 +1349,11 @@ for varname in templateData: Since the semantics of many HTTP methods are defined in terms of the target resource, "targetSchema" is used for requests and/or responses for several - HTTP methods. - In particular, "targetSchema" suggests what a client can expect for the - response to an HTTP GET or any response for which the "Content-Location" - header is equal to the request URI, and what a client should send if it - replaces the resource in an HTTP PUT request. + HTTP methods. In particular, "targetSchema" suggests what a client + application can expect for the response to an HTTP GET or any response + for which the "Content-Location" header is equal to the request URI, + and what a client application should send if it replaces the resource + in an HTTP PUT request. These correlations are defined by RFC 7231, section 4.3.1 - "GET", section 4.3.4 "PUT", and section 3.1.4.2, "Content-Location". @@ -1484,8 +1487,8 @@ for varname in templateData: include the URI(s) of the schema(s) to which the negotiated representation is expected to conform. One possible use for schema parameters in content negotiation is if the resource has conformed to several different - schema versions over time. The client can indicate what version(s) it - understands in the "Accept" header in this way. + schema versions over time. The client application can indicate what version(s) + it understands in the "Accept" header in this way.
@@ -1773,10 +1776,10 @@ Link: rel=describedBy The instance field matching this variable is required, and it is also allowed in the input data. So its instance value is used to - pre-populate the input data set before accepting the client's input. - The client can opt to leave the instance value in place. Since - this field is required in "hrefSchema", the client cannot delete it - (although it could set it to an empty string). + pre-populate the input data set before accepting client input. The + client application can opt to leave the instance value in place. Since + this field is required in "hrefSchema", the client application cannot + delete it (although it could set it to an empty string). The "false" schema set for this in the main schema prevents this field @@ -1800,7 +1803,7 @@ Link: rel=describedBy We can partially resolve the link as follows, before asking the client - for input. + application for input.
@@ -2408,8 +2411,9 @@ Link: rev=up - Clients MUST NOT use the value of "targetSchema" to aid in the interpretation - of the data received in response to following the link, as this leaves + User agents or client applications MUST NOT use the value of "targetSchema" + to aid in the interpretation of the data received in response to following + the link, as this leaves "safe" data open to re-interpretation.