+1
Internal Use - Confidential
From: Handl, Ralf <ralf.handl@sap.com>
Sent: Wednesday, December 6, 2023 4:10 AM
To: Stefan Hagen <stefan@hagen.link>; Ericson, George <George.Ericson@dell.com>
Cc: odata@lists.oasis-open.org
Subject: Re: [odata] [OASIS Issue Tracker] (ODATA-1622) Avoid "MAY ... only if"
After re-reading the sentence in context of subsection
6.5
Key [docs.oasis-open.org] I noticed that this modeling restriction is already stated in the first paragraph of this section
-
An entity is uniquely identified within an entity set by its key. A key MAY be specified if the entity type does not specify a
base
type [docs.oasis-open.org] that already has a key declared.
I would prefer not to alter the first statement as it seems to conform to your points below and is in style with the (majority of) other normative statements in this specification.
Please respond if you disagree.
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
[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
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.
> 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 [rfc-editor.org]. 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 [rfc-editor.org]. 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:
> 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).
Stefan Hagen, Emmetten, Nidwalden, Switzerland.