Subject: Request for status re: NEW PREFERENCE - allow-entityreferences, callback, continue-on-error, include-annotations, maxpagesize, omit-values, and track-changes

From: Chet Ensign <[email-masked]>
Date: Thu, 6 Dec 2018 13:49:56 -0500

This message refers to the New Preference submission on August 29, 2018 in
https://lists.w3.org/Archives/Public/ietf-http-wg/2018JulSep/0277.html.

We have not seen any discussion, approval, or denial so I'm writing to ask
if anything further is needed from the members of the Technical Committee.

Thanks very much for clarifying,

/chet ensign

On Wed, Aug 29, 2018 at 2:33 PM Chet Ensign <[email-masked]>
wrote:

> This message 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 requested to be registered are
>
> allow-entityreferences
> callback
> continue-on-error
> include-annotations
> maxpagesize
> omit-values
> track-changes
>
> The details as required by RFC 7240 for registering these preferences
> follow:
>
> ####
>
> Preference:
>
>     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]
>
>     The allow-entityreferences preference was named
> odata.allow-entityreferences in OData version 4.0.
>
> ####
>
> Preference:
>
>     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]
>
>     The callback preference was named odata.callback in OData version 4.0.
>
> ####
>
> Preference:
>
>     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]
>     The continue-on-error preference was named odata.continue-on-error in
> OData version 4.0.
>
> ####
>
> Preference:
>
>     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]
>
>     The include-annotations preference was named odata.include-annotations
> in OData version 4.0.
>
> ####
>
> Preference:
>
>     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]
>     The maxpagesize preference was named odata.maxpagesize in OData
> version 4.0.
>
> ####
>
> Preference:
>
>     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:
>
>     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]
>     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
>
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393
>

-- 

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

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

---

From: Mike Bishop <[email-masked]>
Date: Thu, 6 Dec 2018 19:00:19 +0000

That registry is Specification Required, so you don’t need approval from the working group to register something.  Just send the request to IANA<https://www.iana.org/form/protocol-assignment>.  They’ll ask the Designated Expert to review.

From: Chet Ensign <[email-masked]>
Sent: Thursday, December 6, 2018 10:50 AM
To: [email-masked]
Cc: Mark Biamonte (Progress) <[email-masked]>; Ralf Handl (SAP) <[email-masked]>
Subject: Request for status re: NEW PREFERENCE - allow-entityreferences, callback, continue-on-error, include-annotations, maxpagesize, omit-values, and track-changes

This message refers to the New Preference submission on August 29, 2018 in https://lists.w3.org/Archives/Public/ietf-http-wg/2018JulSep/0277.html.

We have not seen any discussion, approval, or denial so I'm writing to ask if anything further is needed from the members of the Technical Committee.

/chet ensign
On Wed, Aug 29, 2018 at 2:33 PM Chet Ensign <[email-masked]<mailto:[email-masked]>> wrote:
This message 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.

allow-entityreferences
callback
continue-on-error
include-annotations
maxpagesize
omit-values
track-changes

The details as required by RFC 7240 for registering these preferences follow:

####

Preference:

    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:

Notes: [optional]

    The allow-entityreferences preference was named odata.allow-entityreferences in OData version 4.0.

####

Preference:

    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:

Notes: [optional]

####

Preference:

    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:

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

####

Preference:

    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:

Notes: [optional]

    The include-annotations preference was named odata.include-annotations in OData version 4.0.

####

Preference:

    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:

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

####

Preference:

    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:

Notes: [optional]
    <none>

####

Preference:

    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:

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

---
/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

--

/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

---

From: Mike Bishop <[email-masked]>
Date: Thu, 6 Dec 2018 19:01:50 +0000

Hm, actually – looking closer, it does say to e-mail the WG list and the Designated Expert will pick it up from there.  That’s… interesting.

From: Mike Bishop
Sent: Thursday, December 6, 2018 11:00 AM
To: 'Chet Ensign' <[email-masked]>; [email-masked]
Cc: Mark Biamonte (Progress) <[email-masked]>; Ralf Handl (SAP) <[email-masked]>
Subject: RE: Request for status re: NEW PREFERENCE - allow-entityreferences, callback, continue-on-error, include-annotations, maxpagesize, omit-values, and track-changes

From: Chet Ensign <[email-masked]<mailto:[email-masked]>>
Sent: Thursday, December 6, 2018 10:50 AM
To: [email-masked]<mailto:[email-masked]>
Cc: Mark Biamonte (Progress) <[email-masked]<mailto:[email-masked]>>; Ralf Handl (SAP) <[email-masked]<mailto:[email-masked]>>
Subject: Request for status re: NEW PREFERENCE - allow-entityreferences, callback, continue-on-error, include-annotations, maxpagesize, omit-values, and track-changes

/chet ensign

allow-entityreferences
callback
continue-on-error
include-annotations
maxpagesize
omit-values
track-changes

####

Preference:

    allow-entityreferences

Value:

    <none>
Optional Parameters:

   <none>
Description:

Reference:

Notes: [optional]

####

Preference:

    callback

Value:

    <none>
Optional Parameters:

Reference:

Notes: [optional]

####

Preference:

    continue-on-error

Value:

    <none>
Optional Parameters:

    <none>
Description:

Notes: [optional]

####

Preference:

    include-annotations

Value:

Optional Parameters:

    <none>
Description:

Notes: [optional]

####

Preference:

    maxpagesize

Value:

    <none>
Description:

Notes: [optional]

####

Preference:

    Omit-values

Value:

    One of

    <none>
Description:

Notes: [optional]
    <none>

####

Preference:

    track-changes

Value:

    <none>
Optional Parameters:

    <none>
Description:

Reference:

Notes: [optional]

---
/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

--

/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

---

From: Chet Ensign <[email-masked]>
Date: Thu, 6 Dec 2018 14:07:16 -0500

Thank you Mike. That is why I asked. I don't mind sending the request on to
IANA but the process I saw was that the Designated Expert was to do it.

/chet

On Thu, Dec 6, 2018 at 2:01 PM Mike Bishop <[email-masked]> wrote:

> Hm, actually – looking closer, it does say to e-mail the WG list and the
> Designated Expert will pick it up from there.  That’s… interesting.
>
>
>
> *From:* Mike Bishop
> *Sent:* Thursday, December 6, 2018 11:00 AM
> *To:* 'Chet Ensign' <[email-masked]>; [email-masked]
> *Cc:* Mark Biamonte (Progress) <[email-masked]>; Ralf Handl
> (SAP) <[email-masked]>
> *Subject:* RE: Request for status re: NEW PREFERENCE -
> allow-entityreferences, callback, continue-on-error, include-annotations,
> maxpagesize, omit-values, and track-changes
>
>
>
> That registry is Specification Required, so you don’t need approval from
> the working group to register something.  Just send the request to IANA
> <https://www.iana.org/form/protocol-assignment>.  They’ll ask the
> Designated Expert to review.
>
>
>
> *From:* Chet Ensign <[email-masked]>
> *Sent:* Thursday, December 6, 2018 10:50 AM
> *To:* [email-masked]
> *Cc:* Mark Biamonte (Progress) <[email-masked]>; Ralf Handl
> (SAP) <[email-masked]>
> *Subject:* Request for status re: NEW PREFERENCE -
> allow-entityreferences, callback, continue-on-error, include-annotations,
> maxpagesize, omit-values, and track-changes
>
>
>

-- 

/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 7 Dec 2018 15:28:10 +1100

Hi Chet,

I think the intent is to gather feedback on this list and then proceed with the Expert Review. I've CC'ed the experts so they're aware.

My feedback is similar to the discussions that have occurred around the message headers your'e registering; the names you've chosen are very general, and the protocol you're defining is very specific. Why are these being renamed?

Cheers,

> On 7 Dec 2018, at 5:49 am, Chet Ensign <[email-masked]> wrote:
> 
> On Wed, Aug 29, 2018 at 2:33 PM Chet Ensign <[email-masked]> wrote:

--
Mark Nottingham   https://www.mnot.net/

---

From: James M Snell <[email-masked]>
Date: Fri, 7 Dec 2018 03:38:18 -0800

On Thu, Dec 6, 2018, 20:28 Mark Nottingham <[email-masked] wrote:

> Hi Chet,
>
> I think the intent is to gather feedback on this list and then proceed
> with the Expert Review. I've CC'ed the experts so they're aware.
>

Yes, that was the intent exactly.

- James

> My feedback is similar to the discussions that have occurred around the
> message headers your'e registering; the names you've chosen are very
> general, and the protocol you're defining is very specific. Why are these
> being renamed?
>
> Cheers,
>
>
> > This message refers to the New Preference submission on August 29, 2018
> in https://lists.w3.org/Archives/Public/ietf-http-wg/2018JulSep/0277.html.
>
> >
> > We have not seen any discussion, approval, or denial so I'm writing to
> ask if anything further is needed from the members of the Technical
> Committee.
> >
> > This message 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.
> >
> >
> >     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:
> >
> >     url - The URL of a callback endpoint to be invoked by the service
> when data is available.  The URL parameter is required
> >
> > Description:
> >
> >     The include-annotations preference was named
> odata.include-annotations in OData version 4.0.
> >
> > ####
> >
> > Preference:
> >
> >     maxpagesize
> >
> > Value:
> >
> >     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:
> >

---

From: Chet Ensign <[email-masked]>
Date: Tue, 18 Dec 2018 16:18:14 -0500

Mark N, I just checked the list archive
https://lists.w3.org/Archives/Public/ietf-http-wg/2018OctDec/ and I don't
see that Mark B's reply to you made it to the list. He may not be
subscribed to it. I copy it here so that everyone interested sees his reply
to your question.

---

from:  Mark Biamonte <[email-masked]>
to: Mark Nottingham <[email-masked]>,
Chet Ensign <[email-masked]>
cc: "[email-masked] Group" <[email-masked]>,
"Ralf Handl (SAP)" <[email-masked]>,
"Julian F. Reschke" <[email-masked]>,
James M Snell <[email-masked]>

Hi Mark,

Our thinking is that a number of the preferences may be of general use and
are not specific to OData.  Looking at each of the preferences the ones we
feel are of general interest and independent of OData are

·         callback as an add-on to respond-async can be used with any
payload format – respond-async defined in -
https://tools.ietf.org/html/rfc7240 - author is James Snell

·         maxpagesize as an add-on to the "next" link relation, see
https://www.iana.org/assignments/link-relations/link-relations.xhtml.

·         Can be used in Atom with <link rel="next" ... /> as we do it in
the OData Atom format

·         Can be used with a link header with this relation, see
https://tools.ietf.org/html/rfc5988 - author is Mark Nottingham

·         omit-values – interesting for other JSON or “name-value pair”
formats

·         track-changes – can be used with other payload formats that allow
representing “diffs”, e.g. JSON PATCH - https://tools.ietf.org/html/rfc6902
- author is Mark Nottingham

The remaining three are less obvious to us as to whether they would be
useful in other cases

·         allow-entityreferences – needs a concept and representation of
“references” to be useful

·         continue-on-error – needs a “batch” or “bulk” format

·         include-annotations – needs annotations

Do you or other experts know of existing specs that utilize the concept of
references, batch or bulk operations or annotations?  If so could any of
these remaining three be useful to those specs?

Regards

Mark

-- 

/chet
----------------
Chet Ensign

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 20 Dec 2018 19:05:45 +1100

Hi Chet and Mark,

I agree that some of these are potentially generic. See specific comments below.

Generally, we like to see extensions that are generic being documented in a way that isn't specific to one application. For example, WebDAV's previous definitions of HTTP methods and status codes is now considered bad practice; if they were done today, we'd make sure to define them in their own document.

Note that's not a formal policy for HTTP preferences (AFAIK; ultimately it's up to the experts); just a preference that's been expressed and accepted in the community for other extension points that seems pretty applicable here. Experience has shown that people who aren't intimately familiar with the context will assume that those extensions are limited to that application.

Would there be a willingness in your community to spin some of these extensions into a separate, non-ODATA-specific document? Something else from OASIS would be fine, it doesn't need to be an RFC. I imagine that ODATA might still have something to say about their specific use in that protocol (which might resolve the question below).

Cheers,

> On 19 Dec 2018, at 8:18 am, Chet Ensign <[email-masked]> wrote:
> 
> Hi Mark,
> 
> Our thinking is that a number of the preferences may be of general use and are not specific to OData.  Looking at each of the preferences the ones we feel are of general interest and independent of OData are
> 
> ·         callback as an add-on to respond-async can be used with any payload format – respond-async defined in - https://tools.ietf.org/html/rfc7240 - author is James Snell  
> 
> ·         maxpagesize as an add-on to the "next" link relation, see https://www.iana.org/assignments/link-relations/link-relations.xhtml.  
> 
> ·         Can be used in Atom with <link rel="next" ... /> as we do it in the OData Atom format  
> 
> ·         Can be used with a link header with this relation, see https://tools.ietf.org/html/rfc5988 - author is Mark Nottingham 
> 
> ·         omit-values – interesting for other JSON or “name-value pair” formats  
> 
> ·         track-changes – can be used with other payload formats that allow representing “diffs”, e.g. JSON PATCH - https://tools.ietf.org/html/rfc6902 - author is Mark Nottingham 

I think I agree that these are potentially generic. However, their descriptions mention ODATA-specific concepts; e.g., "delta links" and ODATA capabilities. Could you factor those out into more generic things, omit them, or move them to ODATA-specific text elsewhere?

> The remaining three are less obvious to us as to whether they would be useful in other cases
> 
> ·         allow-entityreferences – needs a concept and representation of “references” to be useful  
> 
> Do you or other experts know of existing specs that utilize the concept of references, batch or bulk operations or annotations?  If so could any of these remaining three be useful to those specs?

I think I agree that these are less likely to be useful generic. I'd encourage you to continue using the odata.* names.

Cheers,