[Ietf-message-headers] Update to NEW PREFERENCE - allow-entityreferences, callback, continue-on-error, include-annotations, maxpagesize, omit-values, and track-changes

[Chet Ensign <[e-mail]>]

This message contains an update to the registration request submitted on 29
August 2018 in
https://lists.w3.org/Archives/Public/ietf-http-wg/2018JulSep/0277.html

In response to the feedback received (summed up nicely in
https://lists.w3.org/Archives/Public/ietf-http-wg/2018OctDec/0279.html),
the OData Technical Committee updated the registration documents to include
the OData prefix in the Header and Preference names as suggested.

Below, please find the revised request. I have included the prior values in
[ ]s so that all the changes are visible.

---

Open Data (OData) Protocol IANA Prefer Header Preference registration
request
22-Jul-2019
------------------------------------------------------------------------------

This documentation contains the information needed for Registration of the
OData specific Prefer Header Preferences with IANA as called out in RFC
7240 - Prefer Header for HTTP.


The OData Prefer Header Preferences to be registered are

[odata.]allow-entityreferences [was allow-entityreferences and etc.]
[odata.]callback
[odata.]continue-on-error
[odata.]include-annotations
[odata.]maxpagesize
omit-values
[odata.]track-changes

The details as required by RFC 7240 for registering these preferences are
listed below

####
Preference:
[odata.]allow-entityreferences  [was allow-entityreferences]

Value:
<none>

Optional Parameters:
<none>

Description:
Indicates that the service is allowed to return references in place of
resources that have previously been returned, with at least the properties
requested, in the same response.

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferenceallowentityreferencesodata

Notes: [optional]
<None>
[was "The allow-entityreferences preference was named
odata.allow-entityreferences in OData version 4.0."]

####
Preference:
[odata.]callback  [was callback]

Value:
<none>

Optional Parameters:
url - The URL of a callback endpoint to be invoked by the service when data
is available.  The URL parameter is required

Description:
Requests that the service invoke the specified URL to signal some service
state, such as the completion of an asynchronous result or availability of
new or modified information. The service state that triggers the change is
dependent upon the request

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferencecallbackodatacallback

Notes: [optional]
<None>
[was The callback preference was named odata.callback in OData version 4.0.]

####
Preference:
[odata.]continue-on-error  [was continue-on-error]

Value:
<none>

Optional Parameters:
<none>

Description:
Requests that the service attempt to continue processing a request that
encounters non-fatal errors, for example in a multi-part request. The
response SHOULD indicate what portions of the request were and were not
able to be successfully handled.

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferencecontinueonerrorodatacontin

Notes: [optional]
<None>
[was The continue-on-error preference was named odata.continue-on-error in
OData version 4.0.]

####
Preference:
[odata.]include-annotations [was include-annotations]

Value:
Comma-separated list of terms to include or, when prefixed with a minus
sign (-), exclude from the response. Terms MUST be namespace-qualified and
MAY specify just a namespace to include or exclude all terms within that
namespace. The special value "*" matches all annotations.

Optional Parameters:
<none>

Description:
Specifies the set of annotations the client requests to be included, where
applicable, or excluded in the response.

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferenceincludeannotationsodatainc

Notes: [optional]
<None>
[was  The include-annotations preference was named
odata.include-annotations in OData version 4.0.]

####
Preference:
[odata.]maxpagesize  [was maxpagesize]

Value:
a positive integer that represents the maximum number of items each
collection in a response SHOULD contain

Optional Parameters:
<none>

Description:
Requests that each collection within the response contain no more than the
number of items specified as the positive integer value of this preference.

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferencemaxpagesizeodatamaxpagesiz

Notes: [optional]
<None>
[was The maxpagesize preference was named odata.maxpagesize in OData
version 4.0.]

####
Preference:
omit-values  [was Omit-values]

Value:
One of
   nulls -  properties containing null values may be omitted from the
response
   defaults - properties containing the property default value may be
omitted from the response

Optional Parameters:
<none>

Description:
Specifies whether a server can omit properties with a null value or
properties set to their default value from a response

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferenceomitvalues

Notes: [optional]
<none>

####
Preference:
[odata.]track-changes  [was track-changes]

Value:
<none>

Optional Parameters:
<none>

Description:
Requests that the service initiate change tracking on the result of this
request, according to the underlying protocol.

Reference:
OData Version 4.01 Part 1: Protocol –
http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferencetrackchangesodatatrackchan

Notes: [optional]
<none>
[was The track-changes preference was named odata.track-changes in OData
version 4.0.]

-- 

/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: [phone]