Re: [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]>]

Many thanks to all who reviewed the notice for message headers whose most
recent post of August 23, 2019 is linked below [1].

We have not heard further comment resulting from the community review, so
we plan to formally make the registration request to IANA in one week
(2019-09-17).

Please let us know if there are any other steps we should take.

[1]  subject: Update to NEW PREFERENCE - allow-entityreferences, callback,
continue-on-error, include-annotations, maxpagesize, omit-values, and
track-changes
https://mailarchive.ietf.org/arch/msg/ietf-message-headers/2t0qiJMArcdXC2a9kWydXOtlppE

On Fri, Aug 23, 2019 at 6:00 PM Chet Ensign <[e-mail]>
wrote:

> 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]
>


-- 

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

Mobile: [phone]