Schema annotations not included in vocabulary annotations for model

[millicentachieng]

trafficstars

A schema can be annotated in one of the following two ways: Option 1

<Schema Namespace="org.example" Alias="self">
  <Annotation Term="Org.OData.Core.V1.Description" String="Example schema" />
  …
</Schema>

Option 2

<Schema Namespace="org.example" Alias="self">
 …
  <Annotations Target="org.example">
    <Annotation Term="Org.OData.Core.V1.Description" String="Example schema" />
    <Annotation Term="Org.OData.Core.V1.LongDescription" String="Example schema long description" />
    <Annotation Term="Org.OData.Core.V1.SchemaVersion" String="3.0" />
  </Annotations>
</Schema>

The resulting EdmModel after parsing the CSDL does not contain the schema annotations for option 1 and has errors for option 2.

I'm pursuing this to fulfil a requirement in the OData to Open API spec that states that: The value of the Open API document title is the value of the unqualified annotation Core.Description of the main schema or the entity container of the OData service.

[mikepizzo]

According to the OASIS CSDL Specification, it is not possible to target the schema element with external annotations.

We will investigate the wording from the OData to OpenAPI specification. I suspect a reasonable algorithm would be to check first for the presence of an entity container -- if present, look for a description there. If not present, look for a description on the schema (which can ONLY be specified inline). If not present, then I would probably just use the namespace.

[millicentachieng]

@mikepizzo, I'm following up on this. What I'm looking to get fixed is to add schema annotations (inline), as part of the model's vocabulary annotations after parsing the CSDL. Is this feasible?

[habbes]

I have reviewed the CSDL spec again, and it does explicitly state that the Schema element may contain inline annotations (edm:Annotation) elements:

It MAY contain elements edm:Action, edm:Annotations, edm:Annotation, ...

It also provides the following example of a description annotation applied to the schema:

<Schema Namespace="org.example" Alias="self">
  <Annotation Term="Core.Description" String="Example schema" />
  ...
</Schema>

So this does indeed sound like a bug or "feature gap" at best.

[habbes]

@millicentachieng would you consider contributing a PR to address this gap, we would be happy to provide the necessary guidance to navigate the code and review your PR.