From 75c073c8bc3249b9cbf0284d1d401c42cd5ce553 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 9 Nov 2023 15:57:00 +0100 Subject: [PATCH] Consistent formatting of references to headers and preferences (#213) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consistently reference headers and preferences --------- Co-authored-by: Heiko Theißen --- docs/odata-json-format/odata-json-format.html | 4 +- docs/odata-json-format/odata-json-format.md | 4 +- docs/odata-protocol/odata-protocol.html | 68 +++++------ docs/odata-protocol/odata-protocol.md | 111 +++++++++--------- .../odata-url-conventions.html | 6 +- .../odata-url-conventions.md | 6 +- odata-json-format/10 Media Entity.md | 2 +- odata-json-format/4 Common Characteristics.md | 2 +- odata-protocol/11 Data Service Requests.md | 14 +-- odata-protocol/11.4 Data Modification.md | 44 +++---- odata-protocol/11.5 Operations.md | 22 ++-- odata-protocol/8 Header Fields.md | 30 ++--- odata-url-conventions/4 Resource Path.md | 2 +- odata-url-conventions/5 Query Options.md | 4 +- 14 files changed, 154 insertions(+), 165 deletions(-) diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 39cd77bac..bc33d3f42 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -467,7 +467,7 @@

Content-Type: application/json;metadata=minimal

cannot be assumed to support streaming.

-

JSON producers are encouraged to follow the payload ordering constraints whenever possible (and include the streaming=true content-type parameter) to support the maximum set of client scenarios.

+

JSON producers are encouraged to follow the payload ordering constraints whenever possible (and include the streaming=true media type parameter) to support the maximum set of client scenarios.

To support streaming scenarios the following payload ordering constraints have to be met:

  • If present, the context control information MUST be the first property in the JSON object.
    • @@ -1062,7 +1062,7 @@

    13 Collection of Entities

    A collection of entities is represented as a JSON object containing a name/value pair named value. It MAY contain context, type, count, nextLink, or deltaLink control information.

    If present, the context control information MUST be the first name/value pair in the response.

    -

    The count name/value pair represents the number of entities in the collection. If present and the streaming=true content-type parameter is set, it MUST come before the value name/value pair. If the response represents a partial result, the count name/value pair MUST appear in the first partial response, and it MAY appear in subsequent partial responses (in which case it may vary from response to response).

    +

    The count name/value pair represents the number of entities in the collection. If present and the streaming=true media type parameter is set, it MUST come before the value name/value pair. If the response represents a partial result, the count name/value pair MUST appear in the first partial response, and it MAY appear in subsequent partial responses (in which case it may vary from response to response).

    The value of the value name/value pair is a JSON array where each element is representation of an entity or a representation of an entity reference. An empty collection is represented as an empty JSON array.

    Functions or actions that are bound to this collection of entities are advertised in the “wrapper object” in the same way as functions or actions are advertised in the object representing a single entity.

    The nextLink control information MUST be included in a response that represents a partial result.

    diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 4a71f489f..d19c44307 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -688,7 +688,7 @@ cannot be assumed to support streaming. JSON producers are encouraged to follow the payload ordering constraints whenever possible (and include the `streaming=true` -content-type parameter) to support the maximum set of client scenarios. +media type parameter) to support the maximum set of client scenarios. To support streaming scenarios the following payload ordering constraints have to be met: @@ -1995,7 +1995,7 @@ first name/value pair in the response. The `count` name/value pair represents the number of entities in the collection. If present and the [`streaming=true`](#PayloadOrderingConstraints) -content-type parameter is set, it MUST come before the +media type parameter is set, it MUST come before the `value` name/value pair. If the response represents a partial result, the `count` name/value pair MUST appear in the first partial response, and it MAY appear in subsequent partial responses (in diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 89e711567..6802647c6 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -660,7 +660,7 @@

    OData-JSON for format-specific details about format parameters within the Content-Type header.

    8.1.2 Header Content-Encoding

    -

    As defined in RFC7231, the Content-Encoding header field is used as a modifier to the media-type (as indicated in the Content-Type). When present, its value indicates what additional content codings have been applied to the entity-body. A service MAY specify a list of acceptable content codings using an annotation with term Capabilities.AcceptableEncodings, see OData-VocCap.

    +

    As defined in RFC7231, the Content-Encoding header field is used as a modifier to the media-type (as indicated in the Content-Type header). When present, its value indicates what additional content codings have been applied to the entity-body. A service MAY specify a list of acceptable content codings using an annotation with term Capabilities.AcceptableEncodings, see OData-VocCap.

    If the Content-Encoding header is specified on an individual request or response within a batch, then it specifies the encoding for that individual request or response. Individual requests or responses that don’t include the Content-Encoding header inherit the encoding of the overall batch request or response.

    8.1.3 Header Content-Language

    As defined in RFC7231, a request or response can include a Content-Language header to indicate the natural language of the intended audience for the enclosed message body. OData does not add any additional requirements over HTTP for including Content-Language. OData services can annotate model elements whose content depends on the content language with the term Core.IsLanguageDependent, see OData-VocCore.

    @@ -682,7 +682,7 @@

    8.2.1 Hea

    Services MUST reject formats that specify unknown or unsupported format parameters.

    If a media type specified in the Accept header includes a charset format parameter and the request also contains an Accept-Charset header, then the Accept-Charset header MUST be used.

    If the media type specified in the Accept header does not include a charset format parameter, then the Content-Type header of the response MUST NOT contain a charset format parameter.

    -

    The service SHOULD NOT add any format parameters to the Content-Type parameter not specified in the Accept header.

    +

    The service SHOULD NOT add any format parameters to the Content-Type header not specified in the Accept header.

    If the Accept header is specified on an individual request within a batch, then it specifies the acceptable formats for that individual request. Requests within a batch that don’t include the Accept header inherit the acceptable formats of the overall batch request.

    8.2.2 Header Accept-Charset

    As defined in RFC7231, the client MAY specify the set of accepted character sets with the Accept-Charset header.

    @@ -693,7 +693,7 @@

    8.2.4 Header If-Match

    As defined in RFC7232, a client MAY include an If-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-Match request header MUST be an ETag value previously retrieved for the resource, or * to match any value.

    If an operation on an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.

    -

    If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending ETag headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from RFC7232.

    +

    If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending ETag headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from RFC7232.

    If the value does not match the current ETag value of the resource for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request. In the case of an upsert, if the addressed entity does not exist the provided ETag value is considered not to match.

    An If-Match header with a value of * in a PUT or PATCH request results in an upsert request being processed as an update and not an insert.

    The If-Match header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.

    @@ -739,8 +739,8 @@

    Capabilities.CallbackSupported annotation term defined in OData-VocCap.

    If the service applies the callback preference it MUST include the callback preference in the Preference-Applied response header.

    -

    When the callback preference is applied to asynchronous requests, the OData service invokes the callback endpoint once it has finished processing the request. The status monitor resource, returned in the Location header of the previously returned 202 Accepted response, can then be used to retrieve the results of the asynchronously executed request.

    -

    When the callback preference is specified on a GET request to a delta link and there are no changes available, the OData service returns a 202 Accepted response with a Location header specifying the delta link to be used to check for future updates. The OData service then invokes the specified callback endpoint once new changes become available.

    +

    When the callback preference is applied to asynchronous requests, the OData service invokes the callback endpoint once it has finished processing the request. The status monitor resource, returned in the Location header of the previously returned 202 Accepted response, can then be used to retrieve the results of the asynchronously executed request.

    +

    When the callback preference is specified on a GET request to a delta link and there are no changes available, the OData service returns a 202 Accepted response with a Location header specifying the delta link to be used to check for future updates. The OData service then invokes the specified callback endpoint once new changes become available.

    Combining respond-async, callback and track-changes preferences on a GET request to a delta-link might influence the response in a couple of ways.

    • If the service processes the request synchronously, and no updates are available, then the response is the same as if the respond-async hadn’t been specified and results in a response as described above.
      • @@ -867,7 +867,7 @@

      8.3.7 Header Retry-After

      A service MAY include a Retry-After header, as defined in RFC7231, in 202 Accepted and in 3xx Redirect responses

      -

      The Retry-After header specifies the duration of time, in seconds, that the client is asked to wait before retrying the request or issuing a request to the resource returned as the value of the Location header.

      +

      The Retry-After header specifies the duration of time, in seconds, that the client is asked to wait before retrying the request or issuing a request to the resource returned as the value of the Location header.

      8.3.8 Header Vary

      If a response varies depending on the OData-Version of the response, the service MUST include a Vary header listing the OData-MaxVersion request header field to allow correct caching of the response.

      If a response varies depending on the applied preferences (allow-entityreferences, include-annotations, omit-values, return), the service MUST include a Vary header listing the Prefer request header field to allow correct caching of the response.

      @@ -885,10 +885,10 @@

      9.1.3 Response Code 202 Accepted

      202 Accepted indicates that the Data Service Request has been accepted and has not yet completed executing asynchronously. The asynchronous handling of requests is defined in the sections on Asynchronous Requests and Asynchronous Batch Requests.

      9.1.4 Response Code 204 No Content

      -

      A request returns 204 No Content if the requested resource has the null value, or if the service applies a return=minimal preference. In this case, the response body MUST be empty.

      +

      A request returns 204 No Content if the requested resource has the null value, or if the service applies a return=minimal preference. In this case, the response body MUST be empty.

      As defined in RFC7231, a Data Modification Request that responds with 204 No Content MAY include an ETag header with a value reflecting the result of the data modification if and only if the client can reasonably “know” the new representation of the resource without actually receiving it. For a PUT request this means that the response body of a corresponding 200 OK or 201 Created response would have been identical to the request body, i.e. no server-side modification of values sent in the request body, no server-calculated values etc. For a PATCH request this means that the response body of a corresponding 200 OK or 201 Created response would have consisted of all values sent in the request body, plus (for values not sent in the request body) server-side values corresponding to the ETag value sent in the If-Match header of the PATCH request, i.e. the previous values “known” to the client.

      9.1.5 Response Code 3xx Redirection

      -

      As per RFC7231, a 3xx Redirection indicates that further action needs to be taken by the client in order to fulfill the request. In this case, the response SHOULD include a Location header, as appropriate, with the URL from which the result can be obtained; it MAY include a Retry-After header.

      +

      As per RFC7231, a 3xx Redirection indicates that further action needs to be taken by the client in order to fulfill the request. In this case, the response SHOULD include a Location header, as appropriate, with the URL from which the result can be obtained; it MAY include a Retry-After header.

      9.1.6 Response Code 304 Not Modified

      As per RFC7232, a 304 Not Modified is returned when the client performs a GET request containing an If-None-Match header and the content has not changed. In this case the response SHOULD NOT include other headers in order to prevent inconsistencies between cached entity-bodies and updated headers.

      The service MUST ensure that no observable change has occurred to the state of the service as a result of any request that returns a 304 Not Modified.

      @@ -923,7 +923,7 @@

      9.5 In-Stream Errors

      -

      In the case that the service encounters an error after sending a success status to the client, the service MUST leave the response malformed according to its content-type. Clients MUST treat the entire response as being in error.

      +

      In the case that the service encounters an error after sending a success status to the client, the service MUST leave the response malformed according to its Content-Type. Clients MUST treat the entire response as being in error.

      Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).

      10 Context URL

      @@ -1223,13 +1223,13 @@

      OData-CSDLJSON describes a JSON representation for OData metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is application/json.

      OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

      OData services can expose a metadata document that describes the data model exposed by the service. The metadata document URL MUST be the root URL of the service with $metadata appended. To retrieve this document the client issues a GET request to the metadata document URL.

      -

      If a request for metadata does not specify a format preference (via Accept header or $format) then the XML representation MUST be returned.

      +

      If a request for metadata does not specify a format preference (via Accept header or $format) then the XML representation MUST be returned.

      11.2 Requesting Data

      OData services support requests for data via HTTP GET requests.

      The path of the URL specifies the target of the request (for example; the collection of entities, entity, navigation property, structural property, or operation). Additional query operators, such as filter, sort, page, and projection operations are specified through query options.

      This section describes the types of data requests defined by OData. For complete details on the syntax for building requests, see OData-URL.

      OData services are hypermedia driven services that return URLs to the client. If a client subsequently requests the advertised resource and the URL has expired, then the service SHOULD respond with 410 Gone. If this is not feasible, the service MUST respond with 404 Not Found.

      -

      The format of the returned data is dependent upon the request and the format specified by the client, either in the Accept header or using the $format query option. If the client specifies neither an Accept header nor the $format query option, the service is allowed to return the response in any format.

      +

      The format of the returned data is dependent upon the request and the format specified by the client, either in the Accept header or using the $format query option. If the client specifies neither an Accept header nor the $format query option, the service is allowed to return the response in any format.

      11.2.1 System Query Options

      OData defines a number of system query options that allow refining the request. System query options are prefixed with the dollar ($) character, which is optional in OData 4.01. 4.01 services MUST support case-insensitive system query option names specified with or without the $ prefix. Clients that want to work with 4.0 services MUST use lower case names and specify the $ prefix.

      The result of the request MUST be as if the system query options were evaluated in the following order.

      @@ -1501,7 +1501,7 @@

      Null values come before non-null values when sorting in ascending order and after non-null values when sorting in descending order.

      Items are sorted by the result values of the first expression, and then items with the same value for the first expression are sorted by the result value of the second expression, and so on.

      The Boolean value false comes before the value true in ascending order.

      -

      Services SHOULD order language-dependent strings according to the content-language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.

      +

      Services SHOULD order language-dependent strings according to the Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.

      Values of type Edm.Stream or any of the Geo types cannot be sorted.

      Example 50: return all Products ordered by release date in ascending order, then by rating in descending order

      @@ -1609,8 +1609,8 @@

      To request entity references in place of the actual entities, the client issues a GET request with /$ref appended to the resource path.

      If the resource path does not identify an entity or a collection of entities, the service returns 404 Not Found.

      -

      If the resource path identifies a collection, the response MUST be the format-specific representation of a collection of entity references pointing to the related entities. If no entities are related, the response is the format-specific representation of an empty collection. The response MAY contain an ETag header for the collection whose value changes if the collection of references changes, i.e. a reference is added or removed.

      -

      If the resource path identifies a single existing entity, the response MUST be the format-specific representation of an entity reference. The response MAY contain an ETag header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.

      +

      If the resource path identifies a collection, the response MUST be the format-specific representation of a collection of entity references pointing to the related entities. If no entities are related, the response is the format-specific representation of an empty collection. The response MAY contain an ETag header for the collection whose value changes if the collection of references changes, i.e. a reference is added or removed.

      +

      If the resource path identifies a single existing entity, the response MUST be the format-specific representation of an entity reference. The response MAY contain an ETag header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.

      If the resource path terminates on a single entity and no such entity exists, the service returns either 204 No Content or 404 Not Found.

      Example 66: collection with an entity reference for each Order related to the Product with ID=0

      @@ -1711,15 +1711,15 @@

      11.3.

      11.4 Data Modification

      Updatable OData services support Create, Update, and Delete operations for some or all exposed entities. Additionally, Actions supported by a service can affect the state of the system.

      A successfully completed Data Modification Request must not violate the integrity of the data.

      -

      The client may request whether content be returned from a Create, Update, or Delete request, or the invocation of an Action, by specifying the return Prefer header.

      +

      The client may request whether content be returned from a Create, Update, or Delete request, or the invocation of an Action, by specifying the return preference.

      11.4.1 Common Data Modification Semantics

      Data Modification Requests share the following semantics.

      11.4.1.1 Use of ETags for Avoiding Update Conflicts

      Each entity has its own ETag value that MUST change when structural properties or links from that entity have changed. In addition, modifying, adding, or deleting a contained entity MAY change the ETag of the parent entity.

      Collections of entities (including collections of related entities) MAY have their own ETag value whose semantics is service-specific. It typically changes if entities are added to or removed from the collection, or if an entity in the collection is changed. The ETag of a collection of related entities reached via a navigation property MAY differ from the ETag of the entity containing the navigation property.

      A Data Modification Request on an existing resource or an Action Request invoking an action bound to an existing resource MAY require optimistic concurrency control. Services SHOULD announce this via annotations with the terms Core.OptimisticConcurrency in OData-VocCore and Capabilities.NavigationRestrictions (nested property OptimisticConcurrencyControl) in OData-VocCap.

      -

      If optimistic concurrency control is required for a resource, the service MUST include an ETag header in a response to a GET request to the resource, and MAY include the ETag in a format-specific manner in responses containing that resource.

      -

      The presence of an ETag header in a response does not imply in itself that the resource requires optimistic concurrency control; the ETag may just be used for caching and/or conditional GET requests.

      +

      If optimistic concurrency control is required for a resource, the service MUST include an ETag header in a response to a GET request to the resource, and MAY include the ETag in a format-specific manner in responses containing that resource.

      +

      The presence of an ETag header in a response does not imply in itself that the resource requires optimistic concurrency control; the ETag may just be used for caching and/or conditional GET requests.

      If an ETag value is specified in an If-Match or If-None-Match header of a Data Modification Request or Action Request, the operation MUST only be invoked if the If-Match or If-None-Match condition is satisfied.

      If the client does not specify an If-Match request header in a Data Modification Request or Action Request on a resource that requires optimistic concurrency control, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request. Clients can attempt to disable optimistic concurrency control by specifying If-Match with a value of *. Services MAY reject such requests.

      For requests including an OData-Version header value of 4.01, any ETag values specified in the request body of an update request MUST be * or match the current value for the record being updated.

      @@ -1747,8 +1747,8 @@

      1

      If the entity being created is not an open entity, additional property values beyond those specified in the metadata SHOULD NOT be sent in the request body. The service MUST fail if unable to persist all property values specified in the request.

      Properties computed by the service (annotated with the term Core.Computed, see OData-VocCore) and properties that are tied to properties of the principal entity by a referential constraint, can be omitted and MUST be ignored if included in the request.

      Properties with a defined default value, nullable properties, and collection-valued properties omitted from the request are set to the default value, null, or an empty collection, respectively.

      -

      Upon successful completion, the response MUST contain a Location header that contains the edit URL or read URL of the created entity.

      -

      Upon successful completion the service MUST respond with either 201 Created and a representation of the created entity, or 204 No Content if the request included a Prefer header with a value of return=minimal and did not include the system query options $select and $expand.

      +

      Upon successful completion, the response MUST contain a Location header that contains the edit URL or read URL of the created entity.

      +

      Upon successful completion the service MUST respond with either 201 Created and a representation of the created entity, or 204 No Content if the request included a return=minimal preference and did not include the system query options $select and $expand.

      To create a new entity with links to existing entities in a single request, the client includes references to the related entities in the request body.

      The representation for referencing related entities is format-specific.

      @@ -1805,7 +1805,7 @@

      1

      If an update specifies both a binding to a single-valued navigation property and a dependent property that is tied to a key property of the principal entity according to the same navigation property, then the dependent property is ignored, and the relationship is updated according to the value specified in the binding.

      If the entity being updated is open, then additional values for properties beyond those specified in the metadata or returned in a previous request MAY be sent in the request body. The service MUST treat these as dynamic properties.

      If the entity being updated is not open, then additional values for properties beyond those specified in the metadata or returned in a previous request SHOULD NOT be sent in the request body. The service MUST fail if it is unable to persist all updatable property values specified in the request.

      -

      Upon successful completion the service responds with either 200 OK and a representation of the updated entity, or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation, or by specifying the system query options $select or $expand. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.

      +

      Upon successful completion the service responds with either 200 OK and a representation of the updated entity, or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference, or by specifying the system query options $select or $expand. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags.

      Update requests with an OData-Version header with a value of 4.0 MUST NOT contain related entities as inline content. Such requests MAY contain binding information for navigation properties. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this adds to the relationship.

      Payloads with an OData-Version header with a value of 4.01 or greater MAY include nested entities and entity references that specify the full set of to be related entities, or a nested delta payload representing the related entities that have been added, removed, or changed. Such a request is referred to as a “deep update”. If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.

      @@ -1878,8 +1878,8 @@

      1

      Upserts are not supported against media entities, single-valued non-containment navigation properties, or entities whose keys values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.

      Singleton entities can be upserted if they are nullable. Services supporting this SHOULD advertise it by annotating the singleton with the term Capabilities.UpdateRestrictions (nested property Upsertable with value true) defined in OData-VocCap.

      Key and other non-updatable properties, as well as dependent properties that are not tied to key properties of the principal entity, MUST be ignored by the service in processing the Upsert request.

      -

      To ensure that an update request is not treated as an insert, the client MAY specify an If-Match header in the update request. The service MUST NOT treat an update request containing an If-Match header as an insert.

      -

      A PUT or PATCH request MUST NOT be treated as an update if an If-None-Match header is specified with a value of *.

      +

      To ensure that an update request is not treated as an insert, the client MAY specify an If-Match header in the update request. The service MUST NOT treat an update request containing an If-Match header as an insert.

      +

      A PUT or PATCH request MUST NOT be treated as an update if an If-None-Match header is specified with a value of *.

      11.4.5 Delete an Entity

      To delete an individual entity, the client makes a DELETE request to a URL that identifies the entity. Services MAY restrict deletes only to requests addressing the edit URL of the entity.

      The request body SHOULD be empty. Top-level singleton entities can be deleted if they are nullable. Services supporting this MAY advertise it by annotating the singleton with the term Capabilities.DeleteRestrictions (nested property Deletable with value true) defined in OData-VocCap.

      @@ -1912,8 +1912,8 @@

      11.4.7.1 Create a Media Entity

      A POST request to a media entity’s entity set creates a new media entity. The request body MUST contain the media value (for example, the photograph) whose media type MUST be specified in a Content-Type header. The request body is always interpreted as the media value, even if it has the media type of an OData format supported by the service. It is not possible to set the structural properties of the media entity when creating the media entity.

      -

      Upon successful completion, the response MUST contain Location header that contains the edit URL of the created media entity.

      -

      Upon successful completion the service responds with either 201 Created, or 204 No Content if the request included a Prefer header with a value of return=minimal.

      +

      Upon successful completion, the response MUST contain Location header that contains the edit URL of the created media entity.

      +

      Upon successful completion the service responds with either 201 Created, or 204 No Content if the request included a return=minimal preference.

      11.4.7.2 Update a Media Entity Stream

      A successful PUT request to the media edit URL of a media entity changes the media stream of the entity.

      If the entity includes an ETag value for the media stream, the client MUST include an If-Match header with the ETag value.

      @@ -1966,7 +1966,7 @@

      A successful PUT request to the edit URL for a primitive property updates the value of the property. The message body MUST contain the new value, formatted as a single property according to the specified format.

      A successful PUT request to the edit URL for the raw value of a primitive property updates the property with the raw value specified in the payload. The payload MUST be formatted as an appropriate content type for the raw value of the property.

      The same rules apply whether this is a regular property or a dynamic property.

      -

      Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

      +

      Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

      Services MUST return an error if the property is not updatable.

      11.4.9.2 Set a Value to Null

      A successful DELETE request to the edit URL for a structural property, or to the edit URL of the raw value of a primitive property, sets the property to null. The request body is ignored and should be empty.

      @@ -1980,7 +1980,7 @@

      200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

      +

      Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

      Services MUST return an error if the property is not updatable.

      11.4.9.4 Update a Collection Property

      A successful PUT request to the edit URL of a collection property updates that collection. The message body MUST contain the desired new value, formatted as a collection property according to the specified format.

      @@ -1988,7 +1988,7 @@

      A successful POST request to the edit URL of a collection property adds an item to the collection. The body of the request MUST be a single item to be added to the collection. If the collection is ordered, the item is added to the end of the collection, and if the collection supports positional insert $index MAY be used to specify the insert position.

      A successful DELETE request to the edit URL of a collection property deletes all items in that collection.

      Since collection members have no individual identity, PATCH is not supported for collection properties.

      -

      Upon successful completion the service responds with either 200 OK and a representation of the updated collection, or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

      +

      Upon successful completion the service responds with either 200 OK and a representation of the updated collection, or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference.

      Services MUST return an error if the property is not updatable.

      11.4.10 Managing Members of an Ordered Collection

      Collections annotated with the Core.Ordered term (see OData-VocCore) have a stable order. Members of an ordered collection of primitive and complex types can be individually updated or deleted by invoking an update operation against the URL of the collection appended by a segment containing the zero-based ordinal of the item within the collection. A negative ordinal number indexes from the end of the collection, with -1 representing the last item in the collection.

      @@ -2179,11 +2179,11 @@

      Core.OptionalParameter defined in OData-VocCore MAY be omitted from the request body. If an omitted parameter is not annotated (and thus nullable), it MUST be interpreted as having the null value. If it is annotated and the annotation specifies a DefaultValue, the omitted parameter is interpreted as having that default value. If omitted and the annotation does not specify a default value, the service is free on how to interpret the omitted parameter. Note: a nullable non-binding parameter is equivalent to being annotated as optional with a default value of null.

      4.01 services MUST support invoking actions with no non-binding parameters and parameterless action imports both without a request body and with a request body representing no parameters, according to the particular format. Interoperable clients SHOULD always include a request body, even when invoking actions with no non-binding parameters and parameterless action imports.

      If the action returns results, the client SHOULD use content type negotiation to request the results in the desired format, otherwise the default content type will be used.

      -

      The client can request whether any results from the action be returned using the return Prefer header.

      -

      Actions that create and return a single entity follow the rules for entity creation and return a Location header that contains the edit URL or read URL of the created entity.

      +

      The client can request whether any results from the action be returned using the return preference.

      +

      Actions that create and return a single entity follow the rules for entity creation and return a Location header that contains the edit URL or read URL of the created entity.

      If the action returns a value of type Edm.Stream, the response to the POST request follows the rules for requesting stream properties.

      Actions without a return type respond with 204 No Content on success.

      -

      To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.

      +

      To request processing of the action only if the binding parameter value, an entity or collection of entities, is unmodified, the client includes the If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.

      Example 98: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.

      POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
@@ -2202,12 +2202,12 @@ 
      The same action name may be used multiple times within a schema provided there is at most one unbound overload, and each bound overload specifies a different binding parameter type.
      
 
      If the action is bound and the binding parameter type is part of an inheritance hierarchy, the action overload is selected based on the type of the URL segment preceding the action name. A type-cast segment can be used to select an action defined on a particular type in the hierarchy, see OData-URL.
      
 
      11.6 Asynchronous Requests
      
-
      A Prefer header with a respond-async preference allows clients to request that the service process a Data Service Request asynchronously.
      
+
      A Prefer header with a respond-async preference allows clients to request that the service process a Data Service Request asynchronously.
      
 
      If the client has specified respond-async in the request, the service MAY process the request asynchronously and return a 202 Accepted response. A service MUST NOT reply to a Data Service Request with 202 Accepted if the request has not included the respond-async preference.
      
-
      Responses that return 202 Accepted MUST include a Location header pointing to a status monitor resource that represents the current state of the asynchronous processing in addition to an optional Retry-After header indicating the time, in seconds, the client should wait before querying the service for status. Services MAY include a response body, for example, to provide additional status information.
      
-
      A GET request to the status monitor resource again returns 202 Accepted response if the asynchronous processing has not finished. This response MUST again include a Location header and MAY include a Retry-After header to be used for a subsequent request. The Location header and optional Retry-After header may or may not contain the same values as returned by the previous request.
      
+
      Responses that return 202 Accepted MUST include a Location header pointing to a status monitor resource that represents the current state of the asynchronous processing in addition to an optional Retry-After header indicating the time, in seconds, the client should wait before querying the service for status. Services MAY include a response body, for example, to provide additional status information.
      
+
      A GET request to the status monitor resource again returns 202 Accepted response if the asynchronous processing has not finished. This response MUST again include a Location header and MAY include a Retry-After header to be used for a subsequent request. The Location header and optional Retry-After header may or may not contain the same values as returned by the previous request.
      
 
      A GET request to the status monitor resource returns 200 OK once the asynchronous processing has completed. For OData 4.01 and greater responses, or OData 4.0 requests that include an Accept header that does not specify application/http, the response MUST include the AsyncResult response header. Any other headers, along with the response body, represent the result of the completed asynchronous operation. If the GET request to the status monitor includes an OData-MaxVersion header with a value of 4.0 and no Accept header, or an Accept header that includes application/http, then the body of the final 200 OK response MUST be represented as an HTTP message, as described in RFC7230, which is the full HTTP response to the completed asynchronous operation.
      
-
      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.
      
+
      A DELETE request sent to the status monitor resource requests that the asynchronous processing be canceled. A 200 OK or a 204 No Content response indicates that the asynchronous processing has been successfully canceled. A client can request that the DELETE should be executed asynchronously. A 202 Accepted response indicates that the cancellation is being processed asynchronously; the client can use the returned Location header (which MUST be different from the status monitor resource of the initial request) to query for the status of the cancellation. If a delete request is not supported by the service, the service returns 405 Method Not Allowed.
      
 
      After a successful DELETE request against the status monitor resource, any subsequent GET requests for the same status monitor resource returns 404 Not Found.
      
 
      If an asynchronous request is cancelled for reasons other than the consumers issuing a DELETE request against the status monitor resource, a GET request to the status monitor resource returns 200 OK with a response body containing a single HTTP response with a status code in the 5xx Server Error range indicating that the operation was cancelled.
      
 
      The service MUST ensure that no observable change has occurred as a result of a canceled request.
      
diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
index 2525bba86..8e43e236c 100644
--- a/docs/odata-protocol/odata-protocol.md
+++ b/docs/odata-protocol/odata-protocol.md
@@ -912,7 +912,7 @@ parameters within the `Content-Type` header.
 
 As defined in [RFC7231](#rfc7231), the `Content-Encoding` header
 field is used as a modifier to the media-type (as indicated in the
-`Content-Type`). When present, its value indicates what additional
+`Content-Type` header). When present, its value indicates what additional
 content codings have been applied to the entity-body.
 A service MAY specify a list of acceptable content codings using an
 annotation with term
@@ -1008,7 +1008,7 @@ If the media type specified in the `Accept` header does not include a
 contain a `charset` format parameter.
 
 The service SHOULD NOT add any format parameters to the `Content-Type`
-parameter not specified in the `Accept` header.
+header not specified in the `Accept` header.
 
 If the `Accept` header is specified on an individual request within a
 batch, then it specifies the acceptable formats for that individual
@@ -1058,7 +1058,7 @@ occurs as a result of the request.
 
 If present, the request MUST only be processed if the specified ETag
 value matches the current ETag value of the target resource. Services
-sending [`ETag` headers](#HeaderETag) with weak ETags that only depend
+sending [`ETag`](#HeaderETag) headers with weak ETags that only depend
 on the representation-independent entity state MUST use the weak
 comparison function because it is sufficient to prevent accidental
 overwrites. This is a deviation from [RFC7232](#rfc7232).
@@ -1255,14 +1255,14 @@ If the service applies the `callback` preference it MUST include the
 When the `callback` preference is applied to asynchronous requests, the
 OData service invokes the callback endpoint once it has finished
 processing the request. The status monitor resource, returned in the
-[`Location` header](#HeaderLocation) of the previously returned
+[`Location`](#HeaderLocation) header of the previously returned
 [`202 Accepted`](#ResponseCode202Accepted) response, can then be used to
 retrieve the results of the asynchronously executed request.
 
 When the `callback` preference is specified on a `GET` request to a
 delta link and there are no changes available, the OData service returns
-a [`202 Accepted`](#ResponseCode202Accepted) response with a [`Location`
-header](#HeaderLocation) specifying the delta link to be used to check
+a [`202 Accepted`](#ResponseCode202Accepted) response with a
+[`Location`](#HeaderLocation) header specifying the delta link to be used to check
 for future updates. The OData service then invokes the specified
 callback endpoint once new changes become available.
 
@@ -1736,8 +1736,8 @@ and in [`3xx Redirect`](#ResponseCode3xxRedirection) responses
 
 The `Retry-After` header specifies the duration of time, in seconds,
 that the client is asked to wait before retrying the request or issuing
-a request to the resource returned as the value of the [`Location`
-header](#HeaderLocation).
+a request to the resource returned as the value of the
+[`Location`](#HeaderLocation) header.
 
 ### 8.3.8 Header `Vary`
 
@@ -1801,8 +1801,9 @@ Requests](#AsynchronousBatchRequests).
 ### 9.1.4 Response Code `204 No Content`
 
 A request returns `204 No Content` if the requested resource has the
-`null` value, or if the service applies a [`return=minimal`
-preference](#Preferencereturnrepresentationandreturnminimal). In this case, the response body MUST be empty.
+`null` value, or if the service applies a
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference.
+In this case, the response body MUST be empty.
 
 As defined in [RFC7231](#rfc7231), a [Data Modification
 Request](#DataModification) that responds with
@@ -1824,10 +1825,10 @@ server-side values corresponding to the `ETag` value sent in the
 
 As per [RFC7231](#rfc7231), a `3xx Redirection` indicates that
 further action needs to be taken by the client in order to fulfill the
-request. In this case, the response SHOULD include a [`Location`
-header](#HeaderLocation), as appropriate, with the URL from which the
-result can be obtained; it MAY include a [`Retry-After`
-header](#HeaderRetryAfter).
+request. In this case, the response SHOULD include a
+[`Location`](#HeaderLocation) header, as appropriate, with the URL from which the
+result can be obtained; it MAY include a
+[`Retry-After`](#HeaderRetryAfter) header.
 
 ### 9.1.6 Response Code `304 Not Modified`
 
@@ -1941,7 +1942,7 @@ concerns around information disclosure.
 
 In the case that the service encounters an error after sending a success
 status to the client, the service MUST leave the response malformed
-according to its [content-type](#HeaderContentType). Clients MUST treat
+according to its [`Content-Type`](#HeaderContentType). Clients MUST treat
 the entire response as being in error.
 
 Services MAY include the header [`OData-Error`](#HeaderODataError) as a
@@ -2607,7 +2608,7 @@ root URL of the service with `$metadata` appended. To retrieve this
 document the client issues a `GET` request to the metadata document URL.
 
 If a request for metadata does not specify a format preference (via
-[`Accept` header](#HeaderAccept) or
+[`Accept`](#HeaderAccept) header or
 [`$format`](#SystemQueryOptionformat)) then the XML representation MUST
 be returned.
 
@@ -2632,10 +2633,10 @@ the URL has expired, then the service SHOULD respond with
 MUST respond with [`404 Not Found`](#ResponseCode404NotFound).
 
 The format of the returned data is dependent upon the request and the
-format specified by the client, either in the [`Accept`
-header](#HeaderAccept) or using the
+format specified by the client, either in the
+[`Accept`](#HeaderAccept) header or using the
 [`$format`](#SystemQueryOptionformat) query option. If
-the client specifies neither an [`Accept` header](#HeaderAccept) nor the
+the client specifies neither an [`Accept`](#HeaderAccept) header nor the
 [`$format`](#SystemQueryOptionformat) query option, the
 service is allowed to return the response in any format.
 
@@ -3291,7 +3292,7 @@ result value of the second expression, and so on.
 The Boolean value false comes before the value true in ascending order.
 
 Services SHOULD order language-dependent strings according to the
-[content-language](#HeaderContentLanguage) of the response, and SHOULD
+[`Content-Language`](#HeaderContentLanguage) of the response, and SHOULD
 annotate string properties with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).
@@ -3583,13 +3584,13 @@ If the resource path identifies a collection, the response MUST be the
 format-specific representation of a collection of entity references
 pointing to the related entities. If no entities are related, the
 response is the format-specific representation of an empty collection.
-The response MAY contain an [ETag header](#HeaderETag) for the
+The response MAY contain an [`ETag`](#HeaderETag) header for the
 collection whose value changes if the collection of references changes,
 i.e. a reference is added or removed.
 
 If the resource path identifies a single existing entity, the response
 MUST be the format-specific representation of an entity reference. The
-response MAY contain an [ETag header](#HeaderETag) which represents the
+response MAY contain an [`ETag`](#HeaderETag) header which represents the
 identity of the referenced entity. If the resource path terminates in a
 single-valued navigation path, the ETag value changes if the
 relationship is changed and points to a different OData entity. If the
@@ -3958,7 +3959,7 @@ must not violate the integrity of the data.
 
 The client may request whether content be returned from a Create,
 Update, or Delete request, or the invocation of an Action, by specifying
-the [`return` Prefer header](#Preferencereturnrepresentationandreturnminimal).
+the [`return`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 ### 11.4.1 Common Data Modification Semantics
 
@@ -3990,11 +3991,11 @@ announce this via annotations with the terms
 [OData-VocCap](#ODataVocCap).
 
 If optimistic concurrency control is required for a resource, the
-service MUST include an [ETag header](#HeaderETag) in a response to a
+service MUST include an [`ETag`](#HeaderETag) header in a response to a
 `GET` request to the resource, and MAY include the ETag in a
 format-specific manner in responses containing that resource.
 
-The presence of an [ETag header](#HeaderETag) in a response does not
+The presence of an [`ETag`](#HeaderETag) header in a response does not
 imply in itself that the resource requires optimistic concurrency
 control; the ETag may just be used for caching and/or conditional `GET`
 requests.
@@ -4134,16 +4135,15 @@ Properties with a defined default value, nullable properties, and
 collection-valued properties omitted from the request are set to the
 default value, null, or an empty collection, respectively.
 
-Upon successful completion, the response MUST contain a [`Location`
-header](#HeaderLocation) that contains the edit URL or read URL of the
+Upon successful completion, the response MUST contain a
+[`Location`](#HeaderLocation) header that contains the edit URL or read URL of the
 created entity.
 
 Upon successful completion the service MUST respond with either
 [`201 Created`](#ResponseCode201Created) and a representation of the
 created entity, or [`204 No Content`](#ResponseCode204NoContent) if the
-request included a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) and did not
+request included a
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference and did not
 include the system query options [`$select`](#SystemQueryOptionselect)
 and [`$expand`](#SystemQueryOptionexpand).
 
@@ -4343,8 +4343,7 @@ Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) and a representation of the updated
 entity, or [`204 No Content`](#ResponseCode204NoContent). The client may
 request that the response SHOULD include a body by specifying a
-[`Prefer` header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal), or by
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference, or by
 specifying the system query options
 [`$select`](#SystemQueryOptionselect) or
 [`$expand`](#SystemQueryOptionexpand). If the service uses ETags for
@@ -4508,12 +4507,12 @@ that are not tied to key properties of the principal entity, MUST be
 ignored by the service in processing the Upsert request.
 
 To ensure that an update request is not treated as an insert, the client
-MAY specify an [`If-Match` header](#HeaderIfMatch) in the update
+MAY specify an [`If-Match`](#HeaderIfMatch) header in the update
 request. The service MUST NOT treat an update request containing an
 `If-Match` header as an insert.
 
 A `PUT` or `PATCH` request MUST NOT be treated as an update if an
-[`If-None-Match` header](#HeaderIfNoneMatch) is specified with a value
+[`If-None-Match`](#HeaderIfNoneMatch) header is specified with a value
 of `*`.
 
 ### 11.4.5 Delete an Entity
@@ -4638,15 +4637,14 @@ OData format supported by the service. It is not possible to set the
 structural properties of the media entity when creating the media
 entity.
 
-Upon successful completion, the response MUST contain [`Location`
-header](#HeaderLocation) that contains the edit URL of the created media
+Upon successful completion, the response MUST contain
+[`Location`](#HeaderLocation) header that contains the edit URL of the created media
 entity.
 
 Upon successful completion the service responds with either
 [`201 Created`](#ResponseCode201Created), or
 [`204 No Content`](#ResponseCode204NoContent) if the request included a
-[`Prefer` header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=minimal`](#Preferencereturnrepresentationandreturnminimal).
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 #### 11.4.7.2 Update a Media Entity Stream
 
@@ -4793,9 +4791,8 @@ property.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
@@ -4845,9 +4842,8 @@ request body and set all unspecified properties to their default value.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
@@ -4877,9 +4873,8 @@ supported for collection properties.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) and a representation of the updated collection, or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
@@ -5511,11 +5506,11 @@ negotiation to request the results in the desired format, otherwise the
 default content type will be used.
 
 The client can request whether any results from the action be returned
-using the [`return Prefer` header](#Preferencereturnrepresentationandreturnminimal).
+using the [`return`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Actions that create and return a single entity follow the rules for
-[entity creation](#CreateanEntity) and return a [`Location`
-header](#HeaderLocation) that contains the edit URL or read URL of the
+[entity creation](#CreateanEntity) and return a
+[`Location`](#HeaderLocation) header that contains the edit URL or read URL of the
 created entity.
 
 If the action returns a value of type `Edm.Stream`, the response to the `POST` request
@@ -5528,7 +5523,7 @@ To request processing of the action only if the binding parameter value,
 an entity or collection of entities, is unmodified, the client includes
 the [`If-Match`](#HeaderIfMatch) header with the latest known ETag value
 for the entity or collection of entities. The ETag value for a
-collection as a whole is transported in the `ETag` header of a
+collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
 collection response.
 
 ::: example
@@ -5566,7 +5561,7 @@ see [OData-URL](#ODataURL).
 
 ## 11.6 Asynchronous Requests
 
-A [Prefer](#HeaderPrefer) header with a
+A [`Prefer`](#HeaderPrefer) header with a
 [`respond-async`](#Preferencerespondasync) preference allows clients
 to request that the service process a [Data Service
 Request](#DataServiceRequests) asynchronously.
@@ -5578,18 +5573,18 @@ NOT reply to a [Data Service Request](#DataServiceRequests) with
 `202 Accepted` if the request has not included the `respond-async`
 preference.
 
-Responses that return `202 Accepted` MUST include a [`Location`
-header](#HeaderLocation) pointing to a *status monitor resource* that
+Responses that return `202 Accepted` MUST include a
+[`Location`](#HeaderLocation) header pointing to a *status monitor resource* that
 represents the current state of the asynchronous processing in addition
-to an optional [`Retry-After` header](#HeaderRetryAfter) indicating the
+to an optional [`Retry-After`](#HeaderRetryAfter) header indicating the
 time, in seconds, the client should wait before querying the service for
 status. Services MAY include a response body, for example, to provide
 additional status information.
 
 A `GET` request to the status monitor resource again returns
 `202 Accepted` response if the asynchronous processing has not finished.
-This response MUST again include a [`Location` header](#HeaderLocation)
-and MAY include a [`Retry-After` header](#HeaderRetryAfter) to be used for a subsequent request. The
+This response MUST again include a [`Location`](#HeaderLocation) header
+and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a subsequent request. The
 `Location` header and optional `Retry-After` header may or may not
 contain the same values as returned by the previous request.
 
@@ -5612,7 +5607,7 @@ asynchronous processing be canceled. A `200 OK` or a
 been successfully canceled. A client can request that the `DELETE`
 should be executed asynchronously. A `202 Accepted` response indicates
 that the cancellation is being processed asynchronously; the client can
-use the returned [`Location` header](#HeaderLocation) (which MUST be
+use the returned [`Location`](#HeaderLocation) header (which MUST be
 different from the status monitor resource of the initial request) to
 query for the status of the cancellation. If a delete request is not
 supported by the service, the service returns
diff --git a/docs/odata-url-conventions/odata-url-conventions.html b/docs/odata-url-conventions/odata-url-conventions.html
index a939a6207..1e6b5a6fc 100644
--- a/docs/odata-url-conventions/odata-url-conventions.html
+++ b/docs/odata-url-conventions/odata-url-conventions.html
@@ -840,7 +840,7 @@ 
      
 
      Example 49: passing a filter condition in the request body
      
 
      POST http://host/service/People/$query
@@ -898,7 +898,7 @@ 
      5.1.1.1.3
 
      The gt operator returns true if the left operand is greater than the right operand, otherwise it returns false.
      
 
      The special value INF is greater than any number, and any number is greater than -INF.
      
 
      The Boolean value true is greater than false.
      
-
      Services SHOULD order language-dependent strings according to the content-language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
      
+
      Services SHOULD order language-dependent strings according to the Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
      
 
      If any operand is null, the operator returns false.
      
 
      5.1.1.1.4 Greater Than or Equal
      
 
      The ge operator returns true if the left operand is greater than or equal to the right operand, otherwise it returns false.
      
@@ -907,7 +907,7 @@ 
      5.1.1.1.5 Less Than
 
      The lt operator returns true if the left operand is less than the right operand, otherwise it returns false.
      
 
      The special value -INF is less than any number, and any number is less than INF.
      
 
      The Boolean value false is less than true.
      
-
      Services SHOULD order language-dependent strings according to the content-language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
      
+
      Services SHOULD order language-dependent strings according to the Content-Language of the response, and SHOULD annotate string properties with language-dependent order with the term Core.IsLanguageDependent, see OData-VocCore.
      
 
      If any operand is null, the operator returns false.
      
 
      5.1.1.1.6 Less Than or Equal
      
 
      The le operator returns true if the left operand is less than or equal to the right operand, otherwise it returns false.
      
diff --git a/docs/odata-url-conventions/odata-url-conventions.md b/docs/odata-url-conventions/odata-url-conventions.md
index bc585dfda..ff5a8cb5f 100644
--- a/docs/odata-url-conventions/odata-url-conventions.md
+++ b/docs/odata-url-conventions/odata-url-conventions.md
@@ -1380,7 +1380,7 @@ Requests to paths ending in `/$query` MUST use the `POST` verb. Query
 options specified in the request body and query options specified in the
 request URL are processed together.
 
-The request body MUST use the content-type `text/plain`. It contains the
+The request body MUST use `Content-Type: text/plain`. It contains the
 query portion of the URL and MUST use the same percent-encoding as in
 URLs (especially: no spaces, tabs, or line breaks allowed) and MUST
 follow the syntax rules described in chapter Query Options.
@@ -1559,7 +1559,7 @@ greater than `-INF`.
 The Boolean value `true` is greater than `false`.
 
 Services SHOULD order language-dependent strings according to the
-content-language of the response, and SHOULD annotate string properties
+`Content-Language` of the response, and SHOULD annotate string properties
 with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).
@@ -1584,7 +1584,7 @@ than `INF`.
 The Boolean value `false` is less than `true`.
 
 Services SHOULD order language-dependent strings according to the
-content-language of the response, and SHOULD annotate string properties
+`Content-Language` of the response, and SHOULD annotate string properties
 with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).
diff --git a/odata-json-format/10 Media Entity.md b/odata-json-format/10 Media Entity.md
index 1b8322cc3..ac05f3e0e 100644
--- a/odata-json-format/10 Media Entity.md	
+++ b/odata-json-format/10 Media Entity.md	
@@ -153,7 +153,7 @@ first name/value pair in the response.
 
 The `count` name/value pair represents the number of entities
 in the collection. If present and the [`streaming=true`](#PayloadOrderingConstraints)
-content-type parameter is set, it MUST come before the
+media type parameter is set, it MUST come before the
 `value` name/value pair. If the response represents a partial
 result, the `count` name/value pair MUST appear in the first
 partial response, and it MAY appear in subsequent partial responses (in
diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md
index 22f0494ff..03e2e2c22 100644
--- a/odata-json-format/4 Common Characteristics.md	
+++ b/odata-json-format/4 Common Characteristics.md	
@@ -153,7 +153,7 @@ cannot be assumed to support streaming.
 
 JSON producers are encouraged to follow the payload ordering constraints
 whenever possible (and include the `streaming=true`
-content-type parameter) to support the maximum set of client scenarios.
+media type parameter) to support the maximum set of client scenarios.
 
 To support streaming scenarios the following payload ordering
 constraints have to be met:
diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md
index 933597829..956e733d9 100644
--- a/odata-protocol/11 Data Service Requests.md	
+++ b/odata-protocol/11 Data Service Requests.md	
@@ -78,7 +78,7 @@ root URL of the service with `$metadata` appended. To retrieve this
 document the client issues a `GET` request to the metadata document URL.
 
 If a request for metadata does not specify a format preference (via
-[`Accept` header](#HeaderAccept) or
+[`Accept`](#HeaderAccept) header or
 [`$format`](#SystemQueryOptionformat)) then the XML representation MUST
 be returned.
 
@@ -103,10 +103,10 @@ the URL has expired, then the service SHOULD respond with
 MUST respond with [`404 Not Found`](#ResponseCode404NotFound).
 
 The format of the returned data is dependent upon the request and the
-format specified by the client, either in the [`Accept`
-header](#HeaderAccept) or using the
+format specified by the client, either in the
+[`Accept`](#HeaderAccept) header or using the
 [`$format`](#SystemQueryOptionformat) query option. If
-the client specifies neither an [`Accept` header](#HeaderAccept) nor the
+the client specifies neither an [`Accept`](#HeaderAccept) header nor the
 [`$format`](#SystemQueryOptionformat) query option, the
 service is allowed to return the response in any format.
 
@@ -763,7 +763,7 @@ result value of the second expression, and so on.
 The Boolean value false comes before the value true in ascending order.
 
 Services SHOULD order language-dependent strings according to the
-[content-language](#HeaderContentLanguage) of the response, and SHOULD
+[`Content-Language`](#HeaderContentLanguage) of the response, and SHOULD
 annotate string properties with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).
@@ -1055,13 +1055,13 @@ If the resource path identifies a collection, the response MUST be the
 format-specific representation of a collection of entity references
 pointing to the related entities. If no entities are related, the
 response is the format-specific representation of an empty collection.
-The response MAY contain an [ETag header](#HeaderETag) for the
+The response MAY contain an [`ETag`](#HeaderETag) header for the
 collection whose value changes if the collection of references changes,
 i.e. a reference is added or removed.
 
 If the resource path identifies a single existing entity, the response
 MUST be the format-specific representation of an entity reference. The
-response MAY contain an [ETag header](#HeaderETag) which represents the
+response MAY contain an [`ETag`](#HeaderETag) header which represents the
 identity of the referenced entity. If the resource path terminates in a
 single-valued navigation path, the ETag value changes if the
 relationship is changed and points to a different OData entity. If the
diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md
index c5908be0a..4e55d3564 100644
--- a/odata-protocol/11.4 Data Modification.md	
+++ b/odata-protocol/11.4 Data Modification.md	
@@ -9,7 +9,7 @@ must not violate the integrity of the data.
 
 The client may request whether content be returned from a Create,
 Update, or Delete request, or the invocation of an Action, by specifying
-the [`return` Prefer header](#Preferencereturnrepresentationandreturnminimal).
+the [`return`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 ### ##subsubsec Common Data Modification Semantics
 
@@ -41,11 +41,11 @@ announce this via annotations with the terms
 [OData-VocCap](#ODataVocCap).
 
 If optimistic concurrency control is required for a resource, the
-service MUST include an [ETag header](#HeaderETag) in a response to a
+service MUST include an [`ETag`](#HeaderETag) header in a response to a
 `GET` request to the resource, and MAY include the ETag in a
 format-specific manner in responses containing that resource.
 
-The presence of an [ETag header](#HeaderETag) in a response does not
+The presence of an [`ETag`](#HeaderETag) header in a response does not
 imply in itself that the resource requires optimistic concurrency
 control; the ETag may just be used for caching and/or conditional `GET`
 requests.
@@ -185,16 +185,15 @@ Properties with a defined default value, nullable properties, and
 collection-valued properties omitted from the request are set to the
 default value, null, or an empty collection, respectively.
 
-Upon successful completion, the response MUST contain a [`Location`
-header](#HeaderLocation) that contains the edit URL or read URL of the
+Upon successful completion, the response MUST contain a
+[`Location`](#HeaderLocation) header that contains the edit URL or read URL of the
 created entity.
 
 Upon successful completion the service MUST respond with either
 [`201 Created`](#ResponseCode201Created) and a representation of the
 created entity, or [`204 No Content`](#ResponseCode204NoContent) if the
-request included a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) and did not
+request included a
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference and did not
 include the system query options [`$select`](#SystemQueryOptionselect)
 and [`$expand`](#SystemQueryOptionexpand).
 
@@ -394,8 +393,7 @@ Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) and a representation of the updated
 entity, or [`204 No Content`](#ResponseCode204NoContent). The client may
 request that the response SHOULD include a body by specifying a
-[`Prefer` header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal), or by
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference, or by
 specifying the system query options
 [`$select`](#SystemQueryOptionselect) or
 [`$expand`](#SystemQueryOptionexpand). If the service uses ETags for
@@ -559,12 +557,12 @@ that are not tied to key properties of the principal entity, MUST be
 ignored by the service in processing the Upsert request.
 
 To ensure that an update request is not treated as an insert, the client
-MAY specify an [`If-Match` header](#HeaderIfMatch) in the update
+MAY specify an [`If-Match`](#HeaderIfMatch) header in the update
 request. The service MUST NOT treat an update request containing an
 `If-Match` header as an insert.
 
 A `PUT` or `PATCH` request MUST NOT be treated as an update if an
-[`If-None-Match` header](#HeaderIfNoneMatch) is specified with a value
+[`If-None-Match`](#HeaderIfNoneMatch) header is specified with a value
 of `*`.
 
 ### ##subsubsec Delete an Entity
@@ -689,15 +687,14 @@ OData format supported by the service. It is not possible to set the
 structural properties of the media entity when creating the media
 entity.
 
-Upon successful completion, the response MUST contain [`Location`
-header](#HeaderLocation) that contains the edit URL of the created media
+Upon successful completion, the response MUST contain
+[`Location`](#HeaderLocation) header that contains the edit URL of the created media
 entity.
 
 Upon successful completion the service responds with either
 [`201 Created`](#ResponseCode201Created), or
 [`204 No Content`](#ResponseCode204NoContent) if the request included a
-[`Prefer` header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=minimal`](#Preferencereturnrepresentationandreturnminimal).
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 #### ##subsubsubsec Update a Media Entity Stream
 
@@ -844,9 +841,8 @@ property.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
@@ -897,9 +893,8 @@ request body and set all unspecified properties to their default value.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
@@ -929,9 +924,8 @@ supported for collection properties.
 Upon successful completion the service responds with either
 [`200 OK`](#ResponseCode200OK) and a representation of the updated collection, or
 [`204 No Content`](#ResponseCode204NoContent). The client may request
-that the response SHOULD include a body by specifying a [Prefer
-header](#Preferencereturnrepresentationandreturnminimal) with a value of
-[`return=representation`](#Preferencereturnrepresentationandreturnminimal).
+that the response SHOULD include a body by specifying a
+[`return=representation`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Services MUST return an error if the property is not updatable.
 
diff --git a/odata-protocol/11.5 Operations.md b/odata-protocol/11.5 Operations.md
index 9be53635c..37e7c2e4a 100644
--- a/odata-protocol/11.5 Operations.md	
+++ b/odata-protocol/11.5 Operations.md	
@@ -402,11 +402,11 @@ negotiation to request the results in the desired format, otherwise the
 default content type will be used.
 
 The client can request whether any results from the action be returned
-using the [`return Prefer` header](#Preferencereturnrepresentationandreturnminimal).
+using the [`return`](#Preferencereturnrepresentationandreturnminimal) preference.
 
 Actions that create and return a single entity follow the rules for
-[entity creation](#CreateanEntity) and return a [`Location`
-header](#HeaderLocation) that contains the edit URL or read URL of the
+[entity creation](#CreateanEntity) and return a
+[`Location`](#HeaderLocation) header that contains the edit URL or read URL of the
 created entity.
 
 If the action returns a value of type `Edm.Stream`, the response to the `POST` request
@@ -419,7 +419,7 @@ To request processing of the action only if the binding parameter value,
 an entity or collection of entities, is unmodified, the client includes
 the [`If-Match`](#HeaderIfMatch) header with the latest known ETag value
 for the entity or collection of entities. The ETag value for a
-collection as a whole is transported in the `ETag` header of a
+collection as a whole is transported in the [`ETag`](#HeaderETag) header of a
 collection response.
 
 ::: example
@@ -457,7 +457,7 @@ see [OData-URL](#ODataURL).
 
 ## ##subsec Asynchronous Requests
 
-A [Prefer](#HeaderPrefer) header with a
+A [`Prefer`](#HeaderPrefer) header with a
 [`respond-async`](#Preferencerespondasync) preference allows clients
 to request that the service process a [Data Service
 Request](#DataServiceRequests) asynchronously.
@@ -469,18 +469,18 @@ NOT reply to a [Data Service Request](#DataServiceRequests) with
 `202 Accepted` if the request has not included the `respond-async`
 preference.
 
-Responses that return `202 Accepted` MUST include a [`Location`
-header](#HeaderLocation) pointing to a *status monitor resource* that
+Responses that return `202 Accepted` MUST include a
+[`Location`](#HeaderLocation) header pointing to a *status monitor resource* that
 represents the current state of the asynchronous processing in addition
-to an optional [`Retry-After` header](#HeaderRetryAfter) indicating the
+to an optional [`Retry-After`](#HeaderRetryAfter) header indicating the
 time, in seconds, the client should wait before querying the service for
 status. Services MAY include a response body, for example, to provide
 additional status information.
 
 A `GET` request to the status monitor resource again returns
 `202 Accepted` response if the asynchronous processing has not finished.
-This response MUST again include a [`Location` header](#HeaderLocation)
-and MAY include a [`Retry-After` header](#HeaderRetryAfter) to be used for a subsequent request. The
+This response MUST again include a [`Location`](#HeaderLocation) header
+and MAY include a [`Retry-After`](#HeaderRetryAfter) header to be used for a subsequent request. The
 `Location` header and optional `Retry-After` header may or may not
 contain the same values as returned by the previous request.
 
@@ -503,7 +503,7 @@ asynchronous processing be canceled. A `200 OK` or a
 been successfully canceled. A client can request that the `DELETE`
 should be executed asynchronously. A `202 Accepted` response indicates
 that the cancellation is being processed asynchronously; the client can
-use the returned [`Location` header](#HeaderLocation) (which MUST be
+use the returned [`Location`](#HeaderLocation) header (which MUST be
 different from the status monitor resource of the initial request) to
 query for the status of the cancellation. If a delete request is not
 supported by the service, the service returns
diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md
index 58d4a050f..c7c174615 100644
--- a/odata-protocol/8 Header Fields.md	
+++ b/odata-protocol/8 Header Fields.md	
@@ -34,7 +34,7 @@ parameters within the `Content-Type` header.
 
 As defined in [RFC7231](#rfc7231), the `Content-Encoding` header
 field is used as a modifier to the media-type (as indicated in the
-`Content-Type`). When present, its value indicates what additional
+`Content-Type` header). When present, its value indicates what additional
 content codings have been applied to the entity-body.
 A service MAY specify a list of acceptable content codings using an
 annotation with term
@@ -130,7 +130,7 @@ If the media type specified in the `Accept` header does not include a
 contain a `charset` format parameter.
 
 The service SHOULD NOT add any format parameters to the `Content-Type`
-parameter not specified in the `Accept` header.
+header not specified in the `Accept` header.
 
 If the `Accept` header is specified on an individual request within a
 batch, then it specifies the acceptable formats for that individual
@@ -180,7 +180,7 @@ occurs as a result of the request.
 
 If present, the request MUST only be processed if the specified ETag
 value matches the current ETag value of the target resource. Services
-sending [`ETag` headers](#HeaderETag) with weak ETags that only depend
+sending [`ETag`](#HeaderETag) headers with weak ETags that only depend
 on the representation-independent entity state MUST use the weak
 comparison function because it is sufficient to prevent accidental
 overwrites. This is a deviation from [RFC7232](#rfc7232).
@@ -377,14 +377,14 @@ If the service applies the `callback` preference it MUST include the
 When the `callback` preference is applied to asynchronous requests, the
 OData service invokes the callback endpoint once it has finished
 processing the request. The status monitor resource, returned in the
-[`Location` header](#HeaderLocation) of the previously returned
+[`Location`](#HeaderLocation) header of the previously returned
 [`202 Accepted`](#ResponseCode202Accepted) response, can then be used to
 retrieve the results of the asynchronously executed request.
 
 When the `callback` preference is specified on a `GET` request to a
 delta link and there are no changes available, the OData service returns
-a [`202 Accepted`](#ResponseCode202Accepted) response with a [`Location`
-header](#HeaderLocation) specifying the delta link to be used to check
+a [`202 Accepted`](#ResponseCode202Accepted) response with a
+[`Location`](#HeaderLocation) header specifying the delta link to be used to check
 for future updates. The OData service then invokes the specified
 callback endpoint once new changes become available.
 
@@ -861,8 +861,8 @@ and in [`3xx Redirect`](#ResponseCode3xxRedirection) responses
 
 The `Retry-After` header specifies the duration of time, in seconds,
 that the client is asked to wait before retrying the request or issuing
-a request to the resource returned as the value of the [`Location`
-header](#HeaderLocation).
+a request to the resource returned as the value of the
+[`Location`](#HeaderLocation) header.
 
 ### ##subsubsec Header `Vary`
 
@@ -926,8 +926,8 @@ Requests](#AsynchronousBatchRequests).
 ### ##subsubsec Response Code `204 No Content`
 
 A request returns `204 No Content` if the requested resource has the
-`null` value, or if the service applies a [`return=minimal`
-preference](#Preferencereturnrepresentationandreturnminimal). 
+`null` value, or if the service applies a
+[`return=minimal`](#Preferencereturnrepresentationandreturnminimal) preference.
 In this case, the response body MUST be empty.
 
 As defined in [RFC7231](#rfc7231), a [Data Modification
@@ -950,10 +950,10 @@ server-side values corresponding to the `ETag` value sent in the
 
 As per [RFC7231](#rfc7231), a `3xx Redirection` indicates that
 further action needs to be taken by the client in order to fulfill the
-request. In this case, the response SHOULD include a [`Location`
-header](#HeaderLocation), as appropriate, with the URL from which the
-result can be obtained; it MAY include a [`Retry-After`
-header](#HeaderRetryAfter).
+request. In this case, the response SHOULD include a
+[`Location`](#HeaderLocation) header, as appropriate, with the URL from which the
+result can be obtained; it MAY include a
+[`Retry-After`](#HeaderRetryAfter) header.
 
 ### ##subsubsec Response Code `304 Not Modified`
 
@@ -1067,7 +1067,7 @@ concerns around information disclosure.
 
 In the case that the service encounters an error after sending a success
 status to the client, the service MUST leave the response malformed
-according to its [content-type](#HeaderContentType). Clients MUST treat
+according to its [`Content-Type`](#HeaderContentType). Clients MUST treat
 the entire response as being in error.
 
 Services MAY include the header [`OData-Error`](#HeaderODataError) as a
diff --git a/odata-url-conventions/4 Resource Path.md b/odata-url-conventions/4 Resource Path.md
index 5138d0866..977ff2f3f 100644
--- a/odata-url-conventions/4 Resource Path.md	
+++ b/odata-url-conventions/4 Resource Path.md	
@@ -946,7 +946,7 @@ Requests to paths ending in `/$query` MUST use the `POST` verb. Query
 options specified in the request body and query options specified in the
 request URL are processed together.
 
-The request body MUST use the content-type `text/plain`. It contains the
+The request body MUST use `Content-Type: text/plain`. It contains the
 query portion of the URL and MUST use the same percent-encoding as in
 URLs (especially: no spaces, tabs, or line breaks allowed) and MUST
 follow the syntax rules described in chapter Query Options.
diff --git a/odata-url-conventions/5 Query Options.md b/odata-url-conventions/5 Query Options.md
index a71a06031..4420143ae 100644
--- a/odata-url-conventions/5 Query Options.md	
+++ b/odata-url-conventions/5 Query Options.md	
@@ -162,7 +162,7 @@ greater than `-INF`.
 The Boolean value `true` is greater than `false`.
 
 Services SHOULD order language-dependent strings according to the
-content-language of the response, and SHOULD annotate string properties
+`Content-Language` of the response, and SHOULD annotate string properties
 with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).
@@ -187,7 +187,7 @@ than `INF`.
 The Boolean value `false` is less than `true`.
 
 Services SHOULD order language-dependent strings according to the
-content-language of the response, and SHOULD annotate string properties
+`Content-Language` of the response, and SHOULD annotate string properties
 with language-dependent order with the term
 [`Core.IsLanguageDependent`](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#IsLanguageDependent),
 see [OData-VocCore](#ODataVocCore).