search

oasis-tcs / odata-specs

OASIS OData TC: Markdown sources for OData specification drafts. https://github.com/oasis-tcs/odata-specs
https://oasis-tcs.github.io/odata-specs/
Other
5 stars 2 forks source link

Allow to create annotations in CSDL with a less verbose format to increase adoption #374

Open ralfhandl opened 4 months ago

ralfhandl commented 4 months ago

CSDL XML annotations can be quite verbose. E.g. 

<Annotation Term="Org.OData.Core.V1.Revisions">
  <Collection>
    <Record>
      <PropertyValue Property="Version" String="2023-03/PrivatePreview:analytics" />
      <PropertyValue Property="Kind" EnumMember="Org.OData.Core.V1.RevisionKind/Deprecated" />
      <PropertyValue Property="Description" String="Private preview for Analytics APIs" />
    </Record>
  </Collection>
</Annotation>

But Annotation can also be expressed in a much cleaner, more readable and less verbose form in CSDL JSON.

Proposal

Allow embedding CSDL JSON annotation values according to 14 Vocabulary and Annotation as CData in CSDL XML

<Annotation Term="Org.OData.Core.V1.Revisions">
  <![CDATA[
    [
      {
        "Version": "2023-03/PrivatePreview:analytics",
        "Kind": "Deprecated",
        "Description": "Private preview for Analytics APIs"
      }
    ]
  ]]>
</Annotation>

Imported from ODATA-1597

ralfhandl commented 1 month ago

Whom would that benefit?

Existing clients knowing how to interpret "pure" XML annotations will be tripped up or forced learn parsing JSON and interpreting CSDL JSON annotations.

Unfortunately CSDL XML and CSDL JSON are not isomorphic, with differences preventing lossless round-tripping especially in the representation of annotations.