OData JSON Format Version 1.0, RFC 2119, and a sample question on MAY usage.

[Moberg Dale <dmoberg@axway.com>]

Eventually OASIS TC specifications need a conformance section, and by using RFC 2119 conventions, the task for writers/readers in finding conformance-related items can be guided by searching for the MUSTS/MUST-NOTs, and checking to make sure that the SHOULDs and MAYs should be upgraded to a MUST or omitted for interop reasons.

 

MAY is always a tricky because this ‘ word, or the adjective "OPTIONAL", means that an item is

   truly optional.  One vendor may choose to include the item because a

   particular marketplace requires it or because the vendor feels that

   it enhances the product while another vendor may omit the same item.

   An implementation which does not include a particular option MUST be

   prepared to interoperate with another implementation which does

   include the option, though perhaps with reduced functionality. In the

   same vein an implementation which does include a particular option

   MUST be prepared to interoperate with another implementation which

   does not include the option (except, of course, for the feature the

   option provides.)

 

 

So in Section 3.1 it is said that

 

An entity in a payload MAY be a complete entity, a projected entity (see [OData-Core, section 10.2.3.2 The $select System Query Option]), or a partial entity update (see [OData-Core, section 10.3.1.2. Differential Update]).

 

I suspect that the RFC 2119 technical specification meaning is not really intended here. If it is intended, an explanation of whether each of these are OPTIONAL, or whether all are OPTIONAL, would be needed at least. If the intent is to say that every payload is one or the other of the subtypes, then actually a “MUST either” could replace the “MAY”.

 

Anyway, I have not made it all the way through the JSON draft yet, but there are other problematic MAYs beyond the one mentioned above. Given 2119 conventions and an interest in not getting fouled up in  interop “gotchas,” could the editors check whether the MAYs are really doing what they intend? It is often safer to even avoid lower-case “may” when possible.  

---