OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: instance annotations


Which doesnât help for the Error Message case: there is nothing to derive from, the error message is not modeled as a structured type (yet).

 

But itâs a thought:

 

      namespace sap.common

 

      include "https://docs.oasis-open.org/odata/odata-json-format/v4.02/os/schemas/odata.rsdl" as odata

      type ErrorMessage extends odata.ErrorMessage { â }

 

Then our error responses would become instances of the derived type

 

{

  "@type": "https://github.com/SAP/odata/types/sap.common.rsdl#sap.common.ErrorMessage",

  "error": {

    "code": "err123",

    "message": "Unsupported functionality",

    "target": "query",

    â SAP-specific fields go here

 

Whoâs going to open an issue for V4.02 or V5.0?

 

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of Ericson, George
Sent: Tuesday, 23 February 2021 17:36
To: Handl, Ralf <ralf.handl@sap.com>; Michael Pizzo <mikep@microsoft.com>; Christof Sprenger <chrispre@microsoft.com>
Cc: odata@lists.oasis-open.org
Subject: [odata] RE: instance annotations

 

I like the Redfish solution better.  (But I like fishâ).

They define an additional property named oem that is incorporated in most classes of their model.  The oem property has a complex type named Oem.

The OEM can then subclass the OEM property within their specializations of the base class.

 

George

 

From: Handl, Ralf <ralf.handl@sap.com>
Sent: Tuesday, February 23, 2021 11:10 AM
To: Ericson, George; Michael Pizzo; Christof Sprenger
Cc: odata@lists.oasis-open.org
Subject: RE: instance annotations

 

[EXTERNAL EMAIL]

We also use âinstance annotationsâ to extend the OData Error Response which only allows adding annotations to its JSON objects.

 

In this case there is no model element where we could attach a âmetadata annotationâ.

 

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of Ericson, George
Sent: Monday, 22 February 2021 19:02
To: Handl, Ralf <ralf.handl@sap.com>; Michael Pizzo <mikep@microsoft.com>; Christof Sprenger <chrispre@microsoft.com>
Cc: odata@lists.oasis-open.org
Subject: [odata] RE: instance annotations

 

Ralf,

 

Just curiousâ.

 

What is SAPâs rational for applying a Term to an instance (i.e. a realization of a model element), as opposed to adding a property/method to the model element?

 

Thanks,
George

 

From: Handl, Ralf <ralf.handl@sap.com>
Sent: Monday, February 22, 2021 12:22 PM
To: Ericson, George; Michael Pizzo; Christof Sprenger
Cc: odata@lists.oasis-open.org
Subject: RE: instance annotations

 

[EXTERNAL EMAIL]

We use the tagging term Common.IsInstanceAnnotation to mark terms that are intended for instance annotations, see https://github.com/SAP/odata-vocabularies/blob/master/vocabularies/Common.md#IsInstanceAnnotation

 

PS: @Michael Pizzo, @Christof Sprenger: I did not receive your mails in this thread, only Georgeâs response to your mails.

 

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of Ericson, George
Sent: Monday, 22 February 2021 17:24
To: Michael Pizzo <mikep@microsoft.com>; Christof Sprenger <chrispre@microsoft.com>
Cc: odata@lists.oasis-open.org
Subject: [odata] RE: instance annotations

 

There are examples where an annotation is meant to be applied to an instance and not the model that describes the instance.

 

For example in the Redfish vocabulary there is this:

      <Term Name="Settings" Type="Settings.Settings">

        <Annotation Term="OData.Description" String="The link to the settings resource that represents the settings to apply to this resource."/>

      </Term>

 

As I understand it, this Term could have been alternatively defined as a âSettingsâ property of the model that it is applied to.

 

My preference would be to use instance annotations only as a way to pass information about the underlying Model that an instance is realized from.  If we want to dig deeper, we could ask a representative of the Redfish team to provide more rational.

 

Thanks,

George

 

 

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of Michael Pizzo
Sent: Saturday, February 20, 2021 2:01 PM
To: Christof Sprenger
Cc: odata@lists.oasis-open.org
Subject: [odata] RE: instance annotations

 

[EXTERNAL EMAIL]

We don't currently have a way to specify that an annotation term is intended for use as an instance annotation â to my recollection, it has never come up.

 

How would this information be useful to the client?  Is it just a matter of documenting how the term is intended to be used, or is it required at runtime in order to invoke some type of logic?

 

If it's part of documenting the usage, then we generally try to convey that in the description â having a machine-readable way to determine if a term is intended as an instance annotation is useful if code needs to determine applicability.

 

For comparison, the AppliesTo attribute for metadata annotations is intended to help schema designers know where they can put what terms (i.e., you can have a drop-down of terms that are applicable to a particular model element without having to understand the semantics of the term.)  AppliesTo is *not* intended to be restrictive (i.e., clients should not throw an error if a term is used somewhere that is not called out in AppliesTo).

 

Similarly, clients should never error due to an unexpected/unknown instance annotation, so I wouldn't add a way to distinguish a term as intended for an instance annotation in order to add client validation.

 

From: odata@lists.oasis-open.org <odata@lists.oasis-open.org> On Behalf Of Christof Sprenger
Sent: Thursday, February 18, 2021 2:58 PM
To: odata@lists.oasis-open.org
Subject: [EXTERNAL] [odata] instance annotations

 

Hello,

 

I would have expected to find something in the annotation term applicability table that allows me to specify that an annotation is intended as an instance annotation.

 

OData Common Schema Definition Language (CSDL) XML Representation Version 4.01 (oasis-open.org)

 

Am I misunderstanding something how a term is supposed to be defined that can be used as an instance annotation? Or is this a gap in the standard?

 

Christof



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]