sap / odata-vocabularies

SAP Vocabularies for semantic markup of structured data published via OData (www.odata.org) services.

odata-vocabularies

SAP Vocabularies for semantic markup of structured data published via OData services.

SAP Vocabularies

This repository defines the following SAP vocabularies:

• Analytics: Analytical resources
• CodeList: Code Lists
• Common: Semantics common to all types of APIs
• Communication: Contact information based on vCard
• DataIntegration: Data Integration
• DirectEdit: Terms for Direct-Edit User Interfaces - experimental
• Graph: SAP Graph - experimental
• Hierarchy: Hierarchies - experimental
• HTML5: Rendering directives for UI5
• ODM: One Domain Model
• Offline: Terms for Offline OData - experimental
• PDF: PDF response format
• PersonalData: Personal data / GDPR
• Session: Sticky Sessions
• UI: Representing data in user interfaces

These vocabularies complement the OASIS OData Vocabularies published by the OASIS OData Technical Committee.

To learn how to construct an annotation value from a term definition, or vice versa, look here:

• Annotation Cheat-Sheet for CSDL JSON
• Annotation Cheat-Sheet for CSDL XML
• Annotation Cheat-Sheet for CAP CDS

Vocabulary-based annotations fully replace the old SAP Annotations for OData Version 2.0

Requirements

Each vocabulary in this repository is described by three files: the *.xml source file, an auto-generated equivalent *.json representation, and a *.md Markdown description, also auto-generated from the *.xml source.

No specific tools are needed to use these vocabulary files.

Contributors to this repository will need to run the generators, which require Node.js to be installed.

Download and Installation

The tools in this repository are only needed by contributors to refresh the *.json and *.md files after changing the *.xml source files. These tools require Node.js to be installed.

Installation

Clone or download this repository, go to its root folder, and type

npm install

Editing

Edit only the XML files, then refresh the JSON and Markdown files with

npm run build

Known Issues

No known issues.

How to obtain support

See CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md.

Licensing

Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.

odata-vocabularies's Issues

Terms in Analytics vocabulary should apply to entity set instead of type

odata-vocabularies/vocabularies/Analytics.xml

Line 79 in cad0f84

<Term Name="AggregatedProperties" Type="Collection(Analytics.AggregatedPropertyType)" Nullable="false" AppliesTo="EntityType">

This term should depend on the container, not on the schema. Set AppliesTo="EntitySet Collection" and tag with Core.AppliesViaContainer.

Similarly, the use of Analytics.Dimension, Analytics.Measure and Analytics.AccumulativeMeasure should be discouraged in favor of properties in a new term Analytics.ApplySupported (to be designed).

Too restrictive assumptions about calendar weeks

odata-vocabularies/vocabularies/Common.xml

Lines 821 to 822 in 79c5025

	<String>Property encodes a calendar week number as string following the logical pattern WW consisting of two digits.
	The string matches the regex pattern 0[1-9]|[1-4][0-9]|5[0-3]

makes too restrictive assumptions about what a week is. As explained on Wikipedia, if a leap year in the US starts on Saturday and ends on Sunday, that year has 54 weeks (the first and last of which contain only one day each), but the pattern above does not allow week numbers beyond 53.

Attempts at a calendar-week-based arithmetic should perhaps be discouraged.

No deprecation texts for complex types in markdown

The section for a deprecated complex type in the markdown file contains the word "Deprecated", but the deprecation text is not shown.

Deprecation texts for terms and properties are shown.

Missing Property "target" for DataFieldWithUrl

Hello SAP OData Vocabularies Team,

right now the UI Annotation DataFieldWithUrl doesn't have a Property "target" that could be used to define if the link is opened in a new window or tab (https://www.w3schools.com/tags/att_a_target.asp). The UI5 control sap.m.Link does provide this Property.

Best Regards
Gregor

Type for some terms is DataFieldAbstract rather than DataField

In staring at the types for the terms in this vocabulary, I am looking at the Identification and LineItem terms, both of which are defined as collections of DataFieldAbstract types.

In defining OData annotations for consumption in Fiori Elements and other smart controls, these terms are often used, and often only with the Value property, which belongs to the concrete DataField type that inherits Label, Criticality, CriticalityRepresentation and IconUrl from DataFieldAbstract, and which adds that Value property.

Here's an example:

annotate CatalogService.Books with @(
    UI: {
        Identification: [ {Value: title} ],
        SelectionFields: [ title ],
        LineItem: [
            {Value: ID},
            {Value: title},
            {Value: author.name},
            {Value: author_ID},
            {Value: stock}
        ],
        HeaderInfo: {
            TypeName: '{i18n>Book}',
            TypeNamePlural: '{i18n>Books}',
            Title: {Value: title},
            Description: {Value: author.name}
        }
    }
);

The Identification term is defined as a collection of the DataFieldAbstract type which doesn't have the Value property.

<Term Name="Identification" Type="Collection(UI.DataFieldAbstract)" Nullable="false" AppliesTo="EntityType">
  <Annotation Term="UI.ThingPerspective" />
  <Annotation Term="Core.Description" String="Collection of fields identifying the object" />
</Term>

Is it not more appropriate (accurate?) to define it (and LineItem, and possibly others) to be of type Collection(UI.DataField) instead?

Help required with non-working Common.SortOrder annotation

Hello,
I'm currently working on SAP Price Calculation product.
I would like to have some help with an issue i have when using sorting (common.sortOrder annotation).

For the context, we have an object called "PricingSchemes" with a service "PricingSchemeService".
The annotation for this service is this one :

service.cds

annotate PricingSchemeService.PricingSchemes with @(
  UI: {
    DeleteHidden : true,
	  SelectionFields: [ code, name ],
		LineItem: [
		  {Value: code, Label: '{i18n>Code}'},
		  {Value: name, Label: '{i18n>Name}'},
	      {Value: description, Label: '{i18n>Description}'},
		  {Value: description, Label: 'Test'},
          {
            $Type : 'UI.DataFieldForAction',
            Label : '{i18n>Copy}',
            Action : 'PricingSchemeService.draftCopy',
            ![@UI.Importance] : #High
          }
		],
    Identification: [
      {
        Value: code,
        Label:  '{i18n>Code}'
      },
      {
        $Type : 'UI.DataFieldForAction',
        Label : '{i18n>Copy}',
        Action : 'PricingSchemeService.draftCopy',
        ![@UI.Importance] : #High
      }
    ],
    HeaderInfo         : {
        TypeName       : '{i18n>PricingScheme}',
        TypeNamePlural : '{i18n>PricingSchemes}',
        Title          : { Value : code, Label: '{i18n>Code}' },
        Description    : { Value : name, Label: '{i18n>Name}' }
    },
    HeaderFacets:[
      {
          $Type  : 'UI.ReferenceFacet',
          Target : '@UI.FieldGroup#HeaderFacets'
      }
    ],
    Facets: [
        {$Type: 'UI.ReferenceFacet', Label: '{i18n>PricingSchemeItemsList}', Target: 'items/@UI.LineItem'},
        {$Type  : 'UI.ReferenceFacet', Label  : '{i18n>AdministrativeData}', Target : '@UI.FieldGroup#PricingSchemeAdministrativeData'}
    ],
    FieldGroup#HeaderFacets : {
        Data : [
            {Value : description, Label : '{i18n>Description}'}
        ]
    },
    FieldGroup#PricingSchemeAdministrativeData : {Data : [
        {
            Value : createdAt,
            Label : '{i18n>createdAt}'
        },
        {
            Value : createdBy,
            Label : '{i18n>createdBy}'
        },
        {
            Value : modifiedAt,
            Label : '{i18n>modifiedAt}'
        },
        {
            Value : modifiedBy,
            Label : '{i18n>modifiedBy}'
        },
    ]},
	}
);

This is actually using the default sorting (by ID, asc) while we would like to define or own sorting.
I've first be using "UI.PresentationVariant" annotation and it works well.

UI.PresentationVariant : {
    Visualizations : [
        '@UI.LineItem'
    ],
    RequestAtLeast : [
       code
    ],
    SortOrder : [
        {
            Property : code,
            Descending : false
        }
    ]
  }

However, the sorting is only done on the frontend requests, while we would prefer it to be generalize to all API call. (For example, i've been reproducing the correct API call using Postman, and it doesn't apply the sorting)

I've then found this page : https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/Common.md

NOTE : At this point, PresentationVariant is no longer in the UI annotation.

So, now, I've been trying to add the Common.SortOrder annotation I found in this documentation. By adding this piece of code into the annotation block:

Common: {
    SortOrder: [
      {
        Property: code,
        Descending: false
      }
    ]
  },
  UI: {...}

With this, I can build my project (so I guess its not a syntax problem) and push it to my MTX database (using Cloud Foundry cf push) without any problem.

But when I launch my backend, there isn't any sorting (neither on the UI nor on Postman calls). It's using the default sort (by ID, asc).

Thank you for your time,
Christophe GENARD

Allow PropertyPath and String for SemanticObjectProperty attribute of SemanticObjectMappingType

Hello SAP OData Vocabularies Team,

our Fiori Elements application lists the messages sent for different business objects. In this example for Sales Orders and also Purchase Orders:

Semantic Object	Action	DocumentID	Semantic Object Property
SalesOrder	manage	10004711	SalesOrder
PurchaseOrder	manage	55004533	PurchaseOrder

The requirement is to allow navigation to the original Objects. But the ID field of the target is not DocumentID but SalesOrder or PurchaseOrder. To achieve a working navigation to the Object Page of the target business object I try to use the Mapping attribute of the DataFieldForIntentBasedNavigation. That works fine for one business object. But unfortunately the SemanticObjectProperty attribute of SemanticObjectMappingType is only defined as a String. For my use case I need to fill it dynamically from the column "Semantic Object Property" of the above sample table. I hope that the last resort isn't DataFieldWithUrl.

Best Regards
Gregor

how do we enable oData $expand queries on list page

Hi,

We have a scenario, which uses CAP and UI annotations for UI.
We have two entities
entity Risks : managed {
.....
bp : Association to BusinessPartners;

}
using {  API_BUSINESS_PARTNER as external } from '../srv/external/API_BUSINESS_PARTNER.csn';
entity BusinessPartners as projection on external.A_BusinessPartner {
key BusinessPartner,
LastName,
FirstName
}

where API_Business_Partner connects to S4HANA onpremise system.

For the UI we are using a list page, where it should display LastName.
In this case, $expand works properly if the data is in csv and the moment I connect to S4HANA system it return null for bp.

Please do help us with it, in case if we are missing something.

Thanks and Regards,
Shankari G R

ConnectedFields annotation

Hi,

I've faced an issue while trying to use ConnectedFields annotation. Let's imagine I want to create List Report for Products and for some column I want to see 'Product Number - Product Description' format display. For instance, we can have following CDS annotations:

//...
UI : {

        LineItem : [
            { $Type : 'UI.DataFieldForAnnotation', Target : '@UI.ConnectedFields#ProductNumberDescr' },
            { $Type : 'UI.DataField', Value : weight },
            { $Type : 'UI.DataField', Value : weightUnit }
        ],

        ConnectedFields#ProductNumberDescr : {
            Label : 'Product',
            Template : '{Number}-{Description}',
            Data : {
                Number : { $Type : 'UI.DataField', Value : number },
                Description : { $Type : 'UI.DataField', Value : description }
            }
        },
    },
//...

After compiling, we will get xml markup which looks really similar like in example mentioned in documentation

<Annotation Term="UI.ConnectedFields" Qualifier="ProductNumberDescr">
          <Record Type="UI.ConnectedFieldsType">
            <PropertyValue Property="Data">
              <Record Type="Core.Dictionary">
                <PropertyValue Property="Description">
                  <Record Type="UI.DataField">
                    <PropertyValue Property="Value" Path="description"/>
                  </Record>
                </PropertyValue>
                <PropertyValue Property="Number">
                  <Record Type="UI.DataField">
                    <PropertyValue Property="Value" Path="number"/>
                  </Record>
                </PropertyValue>
              </Record>
            </PropertyValue>
            <PropertyValue Property="Label" String="Product"/>
            <PropertyValue Property="Template" String="{Number}-{Description}"/>
          </Record>
</Annotation>

Anyway it doesn't work: we won't see any field in List. I guess for Data property we should specify array, so corresponding Data property should look something like:

//...
Data : [ { Number : { $Type : 'UI.DataField', Value : number } },
             { Description : { $Type : 'UI.DataField', Value : description } } ]
//...

For both cases cds gives me descriptive error
For the 1st case:
record type 'Core.Dictionary' doesn't have a property 'Description'
record type 'Core.Dictionary' doesn't have a property 'Number'
and for the 2nd
found collection value, but expected non-collection type Core.Dictionary

Is everything specified correct. I used UI vocabulary as a reference

Thanks in advance