From 93901540e7efd22ce48692deb4298df30ea4c2a7 Mon Sep 17 00:00:00 2001 From: Sarven Capadisli Date: Tue, 28 May 2024 10:05:58 +0200 Subject: [PATCH] Use RFC 'header field' and 'field value' consistently --- ED/protocol.html | 62 ++++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/ED/protocol.html b/ED/protocol.html index bf46728d..a50aa3c8 100644 --- a/ED/protocol.html +++ b/ED/protocol.html @@ -720,7 +720,7 @@

Relationship to LDP

LDP does not specify URI patterns for resources when using the POST method, e.g., POST http://example.org/foo/ may result in creating a resource with URI http://example.org/foo/bar, http://example.org/baz/qux/quxx, http://example.org/{uuid} or something else. In Solid Protocol, the URI of a new resource resulting from, e.g., POST http://example.org/foo/, is in context of the request URI, and therefore http://example.org/foo/bar will be created, and it is not possible to construct the new URI besides under the direct hierarchy of http://example.org/foo/.

-

Solid Protocol's server behaviour in that regard is compatible with LDP even if only ldp:Container is advertised in the HTTP Link header of the request URI, i.e., http://example.org/foo/ as the target URI of POST. Thus, it is possible to have a Solid Protocol server as a particular specialisation of LDP with respect to behaviours around POST to containers. Clients that are interoperable with LDP servers would also be interoperable with Solid Protocol servers with respect to relative referencing. Although LDP servers cannot guarantee the URI pattern resulting from POST requests, the fact that Solid Protocol servers can does not impact interoperability between Solid Protocol servers and LDP clients.

+

Solid Protocol's server behaviour in that regard is compatible with LDP even if only ldp:Container is advertised in the HTTP Link header field of the request URI, i.e., http://example.org/foo/ as the target URI of POST. Thus, it is possible to have a Solid Protocol server as a particular specialisation of LDP with respect to behaviours around POST to containers. Clients that are interoperable with LDP servers would also be interoperable with Solid Protocol servers with respect to relative referencing. Although LDP servers cannot guarantee the URI pattern resulting from POST requests, the fact that Solid Protocol servers can does not impact interoperability between Solid Protocol servers and LDP clients.

Solid Protocol clients may not fully interoperate with LDP servers, e.g., it is possible for an LDP server implementation to assign URIs to new resources that are not compatible with Solid Protocol. An LDP server needs to also conform to Solid Protocol server requirements in order to participate in the Solid ecosystem.

@@ -740,13 +740,13 @@

HTTP Server

Servers MUST conform to HTTP Semantics [RFC9110]. Servers SHOULD conform to HTTP Caching [RFC9111]. Servers MUST conform to HTTP/1.1 [RFC9112]. Servers SHOULD conform to HTTP/2 [RFC9113].

-

Servers SHOULD use TLS connections through the https URI scheme in order to secure the communication with clients. When both http and https URI schemes are supported, the server MUST redirect all http URIs to their https counterparts using a response with a 301 status code and a Location header.

+

Servers SHOULD use TLS connections through the https URI scheme in order to secure the communication with clients. When both http and https URI schemes are supported, the server MUST redirect all http URIs to their https counterparts using a response with a 301 status code and a Location header field.

When a client does not provide valid credentials when requesting a resource that requires it (see WebID), servers MUST send a response with a 401 status code (unless 404 is preferred for security reasons).

Server MUST generate a Content-Type header field in a message that contains content.

-

Server MUST reject PUT, POST and PATCH requests without the Content-Type header with a status code of 400. [Source]

+

Server MUST reject PUT, POST and PATCH requests without the Content-Type header field with a status code of 400. [Source]

@@ -757,7 +757,7 @@

HTTP Client

When a client receives a response with a 403 or 404 status code, the client MAY repeat the request with different credentials.

-

Clients MUST use the Content-Type HTTP header in PUT, POST, and PATCH requests [RFC9110]. [Source]

+

Clients MUST use the Content-Type HTTP header field in PUT, POST, and PATCH requests [RFC9110]. [Source]

@@ -810,17 +810,17 @@

Storage Resource

When a server supports multiple storages, the URIs MUST be allocated to non-overlapping space.

- + - + -

Clients can determine the storage of a resource by moving up the URI path hierarchy until the response includes a Link header with rel="type" targeting http://www.w3.org/ns/pim/space#Storage.

+

Clients can determine the storage of a resource by moving up the URI path hierarchy until the response includes a Link header field with rel="type" targeting http://www.w3.org/ns/pim/space#Storage.

Clients can discover a storage by making an HTTP GET request on the target URL to retrieve an RDF representation [RDF11-CONCEPTS], whose encoded RDF graph contains a relation of type http://www.w3.org/ns/pim/space#storage. The object of the relation is the storage (pim:Storage).

[Source] [Source]

-

Servers MUST include the Link header with rel="http://www.w3.org/ns/solid/terms#storageDescription" targeting the URI of the storage description resource in the response of HTTP GET, HEAD and OPTIONS requests targeting a resource in a storage.

+

Servers MUST include the Link header field with rel="http://www.w3.org/ns/solid/terms#storageDescription" targeting the URI of the storage description resource in the response of HTTP GET, HEAD and OPTIONS requests targeting a resource in a storage.

Servers MUST include statements about the storage as part of the storage description resource.

@@ -835,7 +835,7 @@

Storage Resource

Servers MUST keep track of at least one owner of a storage in an implementation defined way.

- +

[Source][Source][Source][Source]

@@ -850,7 +850,7 @@

Resource Containment

The representation and behaviour of containers in Solid corresponds to LDP Basic Container and MUST be supported by server. [Source]

-

Servers can determine the value of the HTTP Last-Modified header field in response to HEAD and GET requests targeting a container based on changes to containment triples.

+

Servers can determine the field value of the HTTP Last-Modified header field in response to HEAD and GET requests targeting a container based on changes to containment triples.

Note: Container Last-Modified Comparison

@@ -879,7 +879,7 @@

Contained Resource Metadata

The Unix time when the resource was last modified.
-

The dcterms:modified value of a contained resource corresponds with the Last-Modified header value of the contained resource. If one were to perform HEAD or GET requests on the URI of the contained resource at the time of the HTTP message’s generation, then a response with the 200 status code including the Last-Modified header would indicate the same date and time.

+

The dcterms:modified value of a contained resource corresponds with the Last-Modified header field value of the contained resource. If one were to perform HEAD or GET requests on the URI of the contained resource at the time of the HTTP message’s generation, then a response with the 200 status code including the Last-Modified header field would indicate the same date and time.

Note: Contained Resource Metadata Considerations
@@ -927,9 +927,9 @@

Note: URI Origin

  • Description Resource
    • - + - + @@ -969,7 +969,7 @@

    Description Resource

    When an HTTP request targets a description resource, the server MUST apply the authorization rule that is used for the subject resource with which the description resource is associated.

    - + @@ -1009,7 +1009,7 @@

    Reading Resources

    Servers MUST indicate the HTTP methods supported by the target resource by generating an Allow header field in successful responses.

    -

    When responding to authorized requests, servers MUST indicate supported media types in the HTTP Accept-Patch [RFC5789], Accept-Post [LDP] and Accept-Put [The Accept-Put Response Header] response headers that correspond to acceptable HTTP methods listed in Allow header value in response to HTTP GET, HEAD and OPTIONS requests.

    +

    When responding to authorized requests, servers MUST indicate supported media types in the HTTP Accept-Patch [RFC5789], Accept-Post [LDP] and Accept-Put [The Accept-Put Response Header] response header fields that correspond to acceptable HTTP methods listed in Allow header field value in response to HTTP GET, HEAD and OPTIONS requests.

    [Source] [Source] [Source]

    @@ -1035,17 +1035,17 @@

    Writing Resources

    Note: Conditional Update

    -

    Clients are encouraged to use the HTTP If-None-Match header with a value of "*" to prevent an unsafe request method, e.g., PUT, PATCH, from inadvertently modifying an existing representation of the target resource when the client believes that the resource does not have a current representation. [Source] [Source] [Source]

    +

    Clients are encouraged to use the HTTP If-None-Match header field with a value of "*" to prevent an unsafe request method, e.g., PUT, PATCH, from inadvertently modifying an existing representation of the target resource when the client believes that the resource does not have a current representation. [Source] [Source] [Source]

    -

    Servers MAY use the HTTP ETag header with a strong validator for RDF bearing representations in order to encourage clients to opt-in to using the If-Match header in their requests.

    +

    Servers MAY use the HTTP ETag header field with a strong validator for RDF bearing representations in order to encourage clients to opt-in to using the If-Match header field in their requests.

    Modifying Resources Using N3 Patches

    -

    Servers MUST accept a PATCH request with an N3 Patch body when the target of the request is an RDF document [RDF11-CONCEPTS]. Servers MUST indicate support of N3 Patch by listing text/n3 as a value of the Accept-Patch header [RFC5789] of relevant responses. [Source]

    +

    Servers MUST accept a PATCH request with an N3 Patch body when the target of the request is an RDF document [RDF11-CONCEPTS]. Servers MUST indicate support of N3 Patch by listing text/n3 as a field value of the Accept-Patch header field [RFC5789] of relevant responses. [Source]

    An N3 Patch is a document in the Notation3 (N3) format [N3], identified by the media type text/n3, conforming to the following constraints:

    @@ -1105,7 +1105,7 @@

    Deleting Resources

    Servers MUST support the HTTP DELETE method [RFC9110]. [Source] [Source]

    -

    When a DELETE request targets storage’s root container or its associated ACL resource, the server MUST respond with the 405 status code. Server MUST exclude the DELETE method in the HTTP response header Allow in response to requests to these resources [RFC9110]. [Source]

    +

    When a DELETE request targets storage’s root container or its associated ACL resource, the server MUST respond with the 405 status code. Server MUST exclude the DELETE method in the field value of the Allow header field, in response to requests to these resources [RFC9110]. [Source]

    When a contained resource is deleted, the server MUST also remove the corresponding containment triple. [Source]

    @@ -1124,9 +1124,9 @@

    Deleting Resources

    Resource Representations

    -

    When a server creates an RDF source [RDF11-CONCEPTS] on HTTP PUT, POST, or PATCH requests, the server MUST satisfy GET requests on this resource when the value of the Accept header requests a representation in text/turtle or application/ld+json [Turtle] [JSON-LD11]. [Source] [Source] [Source] [Source]

    +

    When a server creates an RDF source [RDF11-CONCEPTS] on HTTP PUT, POST, or PATCH requests, the server MUST satisfy GET requests on this resource when the field value of the Accept header field requests a representation in text/turtle or application/ld+json [Turtle] [JSON-LD11]. [Source] [Source] [Source] [Source]

    -

    When a PUT, POST, PATCH or DELETE method request targets a representation URL that is different than the resource URL, the server MUST respond with a 307 or 308 status code and Location header specifying the preferred URI reference. [Source]

    +

    When a PUT, POST, PATCH or DELETE method request targets a representation URL that is different than the resource URL, the server MUST respond with a 307 or 308 status code and Location header field specifying the preferred URI reference. [Source]

    @@ -1135,7 +1135,7 @@

    Constraints and Problem Details

    This section is non-normative.

    -

    Servers are encouraged to publish any constraints on clients’ ability to create or update resources by adding a Link header with an appropriate context URI, a link relation of http://www.w3.org/ns/ldp#constrainedBy, and a target URI identifying a set of constraints [RFC8288], to responses to requests that fail due to violation of those constraints. The same Link header can be provided in other responses.

    +

    Servers are encouraged to publish any constraints on clients’ ability to create or update resources by adding a Link header field with an appropriate context URI, a link relation of http://www.w3.org/ns/ldp#constrainedBy, and a target URI identifying a set of constraints [RFC8288], to responses to requests that fail due to violation of those constraints. The same Link header field can be provided in other responses.

    Servers are encouraged to use the URIs of the constraints that are defined by specifications or other constraint URIs within its authority depending on the request's semantics on a target resource.

    @@ -1189,7 +1189,7 @@

    Cross-Origin Resource Sharing

    For cases where the other origins have their own access protection mechanism — like within Solid — the browser’s built-in cross-origin protection is actually an obstacle rather than a feature. After all, storages already ensure through access control that certain documents can only be accessed by specific people or applications. Preventively blocking apps from different origins thus introduces an unnecessary barrier.

    -

    Fortunately, Web servers can indicate to the browser that certain documents do not require cross-origin protection. This mechanism to selectively disable that protection is called Cross-Origin Resource Sharing or CORS [FETCH]. By responding to browser requests with a specific combination of HTTP headers, servers can indicate which actions are allowed for a given resource. For Solid, the goal is to allow all actions on the CORS level, such that the deeper Authorization layer can exert full control over the app’s allowed permissions. The next section describes how to achieve this through the right HTTP header configuration.

    +

    Fortunately, Web servers can indicate to the browser that certain documents do not require cross-origin protection. This mechanism to selectively disable that protection is called Cross-Origin Resource Sharing or CORS [FETCH]. By responding to browser requests with a specific combination of HTTP header fields, servers can indicate which actions are allowed for a given resource. For Solid, the goal is to allow all actions on the CORS level, such that the deeper Authorization layer can exert full control over the app’s allowed permissions. The next section describes how to achieve this through the right HTTP header field configuration.

    CORS Server

    @@ -1203,9 +1203,9 @@

    Note: CORS Protocol Blocking

    -

    Concretely, whenever a server receives an HTTP request containing a valid Origin header [RFC6454], the server MUST respond with the appropriate Access-Control-* headers as specified in the CORS protocol [FETCH]. In particular, the server MUST set the Access-Control-Allow-Origin header to the valid Origin value from the request and list Origin in the Vary header value. The server MUST make all used response headers readable for the Solid app through Access-Control-Expose-Headers (with the possible exception of the Access-Control-* headers themselves). A server MUST also support the HTTP OPTIONS method [RFC9110] such that it can respond appropriately to CORS preflight requests.

    +

    Concretely, whenever a server receives an HTTP request containing a valid Origin header [RFC6454], the server MUST respond with the appropriate Access-Control-* header fields as specified in the CORS protocol [FETCH]. In particular, the server MUST set the Access-Control-Allow-Origin header field value to the valid Origin header field value from the request and list Origin in the Vary header field value. The server MUST make all used response headers readable for the Solid app through Access-Control-Expose-Headers (with the possible exception of the Access-Control-* header fields themselves). A server MUST also support the HTTP OPTIONS method [RFC9110] such that it can respond appropriately to CORS preflight requests.

    -

    Careful attention is warranted, especially because of the many edge cases. For instance, servers SHOULD explicitly enumerate all used response headers under Access-Control-Expose-Headers rather than resorting to *, which does not cover all cases (such as credentials mode set to include). Servers SHOULD also explicitly list Accept under Access-Control-Allow-Headers, because values longer than 128 characters (not uncommon for RDF-based Solid apps) would otherwise be blocked, despite shorter Accept headers being allowed without explicit mention.

    +

    Careful attention is warranted, especially because of the many edge cases. For instance, servers SHOULD explicitly enumerate all used response header fields under Access-Control-Expose-Headers rather than resorting to *, which does not cover all cases (such as credentials mode set to include). Servers SHOULD also explicitly list Accept under Access-Control-Allow-Headers, because header field values longer than 128 characters (not uncommon for RDF-based Solid apps) would otherwise be blocked, despite shorter Accept header field values being allowed without explicit mention.

    @@ -1283,19 +1283,19 @@

    HTTP Headers

    The Accept-Put Response Header

    -

    This specification introduces a new HTTP response header Accept-Put used to specify the document formats accepted by the server on HTTP PUT requests. It is modelled after the Accept-Patch header defined in [RFC5789] and the Accept-Post header defined in [LDP].

    +

    This specification introduces the Accept-Put header field used to specify the document formats accepted by the server on HTTP PUT requests. It is modelled after the Accept-Patch header defined in [RFC5789] and the Accept-Post header defined in [LDP].

    The syntax for Accept-Put, using the ABNF syntax defined in Section 2.1 of [RFC9110], is:

    Accept-Put = "Accept-Put" ":" #media-range
    -

    The Accept-Put header specifies a comma-separated list of media ranges (with optional parameters) as defined by [RFC9110], Section 12.5.1. The Accept-Put header, in effect, uses the same syntax as the HTTP Accept header.

    +

    The Accept-Put header field specifies a comma-separated list of media ranges (with optional parameters) as defined by [RFC9110], Section 12.5.1. The Accept-Put header field, in effect, uses the same syntax as the HTTP Accept header.

    -

    The presence of the Accept-Put header in response to any method is an implicit indication that PUT is allowed on the resource identified by the target URI. The presence of a specific document format in this header indicates that that specific format is allowed on PUT requests to the resource identified by the target URI.

    +

    The presence of the Accept-Put header field in response to any method is an implicit indication that PUT is allowed on the resource identified by the target URI. The presence of a specific document format in this header field indicates that that specific format is allowed on PUT requests to the resource identified by the target URI.

    IANA Registration Template:

    -

    The Accept-Put response header must be added to the permanent registry (see [RFC9110]).

    +

    The Accept-Put response header field must be added to the permanent registry (see [RFC9110]).

    Header field name
    @@ -1331,7 +1331,7 @@

    Security Considerations

    Implementations are encouraged to adhere to the same security considerations that are found in HTTP Semantics [RFC9110] and HTTP/1.1 [RFC9112].

    - Servers are strongly discouraged from assuming that HTTP request headers’ field-values are valid or non-malicious. + Servers are strongly discouraged from assuming that HTTP request headers’ field values are valid or non-malicious. Servers are strongly encouraged to sanitize requests before processing them or incorporating them in messages sent to others. @@ -1346,7 +1346,7 @@

    Security Considerations

    Servers are strongly discouraged from exposing information beyond the minimum amount necessary to enable a feature.

    -

    Servers are strongly discouraged from assuming that the user agent is a regular Web browser, even when requests contain familiar values in headers such as User-Agent or Origin. Such an assumption could lead to incorrect conclusions about the security model of the application making the request, since the request might actually come from a non-browser actor unaffected by browser security constraints.

    +

    Servers are strongly discouraged from assuming that the user agent is a regular Web browser, even when requests contain familiar field values in header fields such as User-Agent or Origin. Such an assumption could lead to incorrect conclusions about the security model of the application making the request, since the request might actually come from a non-browser actor unaffected by browser security constraints.

    Servers disable all cross-origin protections in browsers because resource access is governed explicitly by the Authorization component. As such, servers cannot rely on browser-based cross-origin protection mechanisms for determining the authentication status or representation of a resource.