IANA Header and Preference registration document questions.

[Mark Biamonte <Mark.Biamonte@progress.com>]

I had received the following questions from Robin Cover a while ago.  I am just getting around to answering them.  I have included what I think the answers are for most of these, but I have some questions on some.

 

Mark

====================

 

Now that the CS01 is available for OData 4.01 (Part1 and Part2), I'm trying to refresh my memory on plans for the IANA registrations.

1) Gating items ahead of registration requests to the lists?  I'm unsure whether there are any other gating items, but I see a lot of activity in the OData TC

- Part3  at CS level -- needed?

 

Part 3 has been replaced by two documents in OData 4.01

 

OData Common Schema Definition Language (CSDL) XML Representation Version 4.0.1

OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01

 

Both of these documents are at CS01

Note:  The Part1: Protocol document references OData Vocabularies Version 4.0 and that vocabularies document references OData Version 4.01. Part 3: Common Schema Definition Language (CSDL). Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part3-csdl.html which is not valid for OData 4.01.  I think this may be why Robin is asking about Part 3.

 
- Vocab at CS level needed?   [The CS Header Prefer sections cite "[OData-VocCap]" = "OData Vocabularies Version 4.0" =  CSPRD01 http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.html

 

I am not sure what the correct answer is for this one.  Is it that the vocabularies continue to evolve in a backwards compatible way?  Also I suspect the vocabularies being published on GitHub comes into play somehow.

2) Updated template document(s)  I'm guessing that you are preparing at updated version of the template document for "IANA Prefer Header Preference Registration Request".  The latest I have seems to be from 10 October 2017, with redline reminders to update the URI references to cite the relevant sections in the approved  CS version [1]

 

Yes, I am updating this document to reference the version specific OData 4.01 documents

3) HTML section URIs: In connection with #2, I think the IETF (IANA, IESG) and W3C reviewers will be expecting HTML or plain text -- not the word processor or PDF format, since URI-style hyperlinks into PDF and WordProcessor (.docx) formate are ... uh...     I extracted the URI references for the seven Prefer Header Prederences - see [2] below.   I agree with your draft to cite the sections in HTML even if the .docx is labeled "Authoritative"

 

The latest versions of the Header and Preference registration documents are referencing the HTML format of the OData 4.01 documents.  I will try adding the segments to the URL, but I had issues with doing that in the past.   

4) Latest-version aliases?  I see that the Kavi document #62149 for "IANA Header Registration Request" uses the symlink URI references (version-agnostic aliases) for "Latest Version"  I think it may be better, for purposes of IETF/W3C review, to use the instance URI references for the concrete text -- rather than mutable text.    IETF and W3C, of course, are familiar with "Latest version" aliases, but the reviewers may be more comfortable making technical review against invariate approved text as opposed to variable text.   The smart ones will know that even an OASIS  "CS01" can be sent back to WD level and revised as CS02 -- with unpredictable changes...  That is: "CS01" isn't actually final except by aspiration and hope.

 

I can change the link references to the version specific link pending approval from the TC

5) omit-values   I may be forgetting discussion about "omit-values" Prefer Header Preference, if we had any discussion; the earliest drafts I had lacked  "omit-values" as candidate for registration, but the template [1] lists it as one of seven.  I note that the CS spec heading is formulated differently for  "omit-values" than for the other six

 

This is because omit-values was not included in the OData 4.0 spec.  It is new to OData 4.01.  The other six were part of the OData 4.0 spec.  In OData 4.01 the name of the preference has changed by dropping the odata. Prefix.  The value in parentheses for some of the Preferences are the names for these preferences in OData 4.0.  OData 4.01 services will support both forms of the names for the preferences whose names have changed.

- 8.2.8.6 Preference omit-values  /* versus */

CS does not say in parens:  " (odata.omit-values )"

8.2.8.1 Preference allow-entityreferences (odata.allow-entityreferences)
8.2.8.2 Preference callback (odata.callback)
8.2.8.3 Preference continue-on-error (odata.continue-on-error)
8.2.8.4 Preference include-annotations (odata.include-annotations)
8.2.8.5 Preference maxpagesize (odata.maxpagesize)
8.2.8.9 Preference track-changes (odata.track-changes)