Re: [odata] [OASIS Issue Tracker] (ODATA-1622) Avoid "MAY ... only if"

["Stefan Hagen" <stefan@hagen.link>]

On Tue, Dec 5, 2023, at 20:10, Ericson, George wrote:

An entity type is not an actor, so both old and new text are not clear.

 

Suggest:

A new key property MAY NOT be added to an entity type that already defines a key, (whether or not the entity type is marked as abstract).

  

Internal Use - Confidential

From: Handl, Ralf <ralf.handl@sap.com>
Sent: Tuesday, December 5, 2023 3:48 AM
To: Ericson, George <George.Ericson@dell.com>
Cc: odata@lists.oasis-open.org
Subject: Re: [odata] [OASIS Issue Tracker] (ODATA-1622) Avoid "MAY ... only if"

 

[EXTERNAL EMAIL]

The concrete case here is rephrasing an existing requirement on the API Designer:

• An entity type (whether or not it is marked as abstract) MUST NOT define a key if it inherits one.
  

 

The old text was

 

• An entity type (whether or not it is marked as abstract) MAY define a key only if it doesn't inherit one.
  

 

The new text is easier to understand (at least for Germans ð).

 

 

Internal Use - Confidential

---

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> on behalf of Ericson, George <George.Ericson@dell.com>
Sent: Monday, December 4, 2023 18:01
To: OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>; odata@lists.oasis-open.org <odata@lists.oasis-open.org>
Subject: RE: [odata] [OASIS Issue Tracker] (ODATA-1622) Avoid "MAY ... only if"

 

Ouch double negatives....

The provision should be on the provider.  Could we have an example that does not place a requirement on a client? 

G

Internal Use - Confidential

-----Original Message-----

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of OASIS Issues Tracker

Sent: Monday, December 4, 2023 9:26 AM

To: odata@lists.oasis-open.org

Subject: [odata] [OASIS Issue Tracker] (ODATA-1622) Avoid "MAY ... only if"

 

[EXTERNAL EMAIL]

 

Heiko Theissen created ODATA-1622:

-------------------------------------

 

             Summary: Avoid "MAY ... only if"

                 Key: ODATA-1622

                 URL: https://urldefense.com/v3/__https://issues.oasis-open.org/browse/ODATA-1622__;!!LpKI!n_sINK3IMZD0C2AtBbsgzSoTFbEvpXr1lhikhs0CY8TlcxtNkbhB6Av88uOeJHLr18FVBrVlIA2u3ml22dr5oF-tiEee69R97PrsXA$ [issues[.]oasis-open[.]org]

             Project: OASIS Open Data Protocol (OData) TC

          Issue Type: Improvement

          Components: CSDL JSON , CSDL XML

            Reporter: Heiko Theissen

 

 

Combining the RFC2119 term "MAY" with a negation or restrictions runs counter to what MAY wants to express.

{quote}Clients MAY do A only if B

{quote}

sounds as if

* the client may choose not to do A if B (which is not always implied)

* there is no rule for the client if not B.

 

Instead, write

{quote}Clients MUST NOT do A if (not B)

{quote}

--

This message was sent by Atlassian Jira

(v8.3.3#803004) [...]

if there is no actor and there is no option ...

I propose to remove the pseudo RFC2119 and simply state the fact to expect, i.e. rewrite (old):

    >  An entity type (whether or not it is marked as abstract) MAY define a key only if it doesn't inherit one.

as (new, but see below):

    >  An entity type (whether or not it is marked as abstract) defines a key only if it doesn't inherit one.

based on (esp. the first sentences of below cited 5. and 6.):

5. MAY   This word, or the adjective "OPTIONAL", mean 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.)

6. Guidance in the use of these Imperatives

   Imperatives of the type defined in this memo must be used with care
   and sparingly.  In particular, they MUST only be used where it is
   actually required for interoperation or to limit behavior which has
   potential for causing harm (e.g., limiting retransmisssions)  For
   example, they must not be used to try to impose a particular method
   on implementors where the method is not required for
   interoperability.

 

Also, I would keep the "(whether or not it is marked as abstract)" close to the entity it details to

not weaken the "it" in use - otherwise a repetition of "entity type" would be in order to not

mistakingly attach to the "key".  Or we could simplify further an use "any" (as I assume the "abstract"

and "non-abstract" form a direct sum for all entity types, thus to me easiest would be:

(shiny new :-) ) ...:

    >  Any entity type defines a key only if it doesn't inherit one.

In my reading this leaves open the possibility that the ET does not inherit a key and

does not define one (from a truth table perspective).

Cheers,

Stefan.

---

Stefan Hagen, Emmetten, Nidwalden, Switzerland.

read: https://stefan-hagen.website

write: stefan@hagen.link