Show TOC

Semantics AnnotationsLocate this document in the navigation structure

Used by the core engines for data processing, analytics, and data consumption

Scope and Definition
@Scope:[#ELEMENT, #PARAMETER]
Annotation Semantics
 {
   telephone
   {
      type : array of String enum { HOME; CELL; WORK; FAX; PREF; TEXT; VOICE; VIDEO; PAGER; TEXT_PHONE; } default #PREF;
   };
   eMail
   {
      type : array of String enum { HOME; WORK; PREF; OTHER; } default #PREF;
      address : Boolean default true;
      from : Boolean default true;
      sender : Boolean default true;
      to : Boolean default true;
      cc : Boolean default true;
      bcc : Boolean default true;
      subject : Boolean default true;
      body : Boolean default true;
      keywords : Boolean default true;
      received : Boolean default true;
   };
   name
   {
      fullName : Boolean default true;
      givenName : Boolean default true;
      additionalName : Boolean default true;
      familyName : Boolean default true;
      nickName : Boolean default true;
      suffix : Boolean default true;
      prefix : Boolean default true;
      jobTitle : Boolean default true;
   };
   address
   {
      type : array of String enum { HOME; WORK; PREF; OTHER; } default #PREF;
      city : Boolean default true;
      street : Boolean default true;
	 streetNoNumber : Boolean default true;
      number : Boolean default true;
      country : Boolean default true;
      region : Boolean default true;
      subRegion : Boolean default true;
      zipCode : Boolean default true;
      postBox : Boolean default true;
      label : Boolean default true;
   };
   organization
   {
      name : Boolean default true;
      unit : Boolean default true;
      role : Boolean default true;
   };
   calendarItem
   {
      summary : Boolean default true;
      description : Boolean default true;
      categories : Boolean default true;
      dtStart : Boolean default true;
      dtEnd : Boolean default true;
      duration : Boolean default true;
      due : Boolean default true;
      completed : Boolean default true;
      priority : Boolean default true;
      class : Boolean default true;
      status : Boolean default true;
      percentComplete : Boolean default true;
      contact : Boolean default true;
      location : Boolean default true;
      transparent : Boolean default true;
      fbType : Boolean default true;
      wholeDay : Boolean default true;
   };
   businessDate
   {
      at : Boolean default true;
      from : Boolean default true;
      to : Boolean default true;
      createdAt : Boolean default true;
      lastChangedAt : Boolean default true;
   };
   systemDate
   {
      createdAt : Boolean default true;
      lastChangedAt : Boolean default true;
   };
   time : Boolean default true;
   calendar
   {
      dayOfMonth : Boolean default true;
      dayOfYear : Boolean default true;
      week : Boolean default true;
      month : Boolean default true;
      quarter : Boolean default true;
      year : Boolean default true;
      yearWeek : Boolean default true;
      yearMonth : Boolean default true;
      yearQuarter : Boolean default true;
   };
   fiscal
   {
      yearVariant : Boolean default true;
      period : Boolean default true;
      year : Boolean default true;
      yearPeriod : Boolean default true;
   };
   geoLocation
   {
      longitude : Boolean default true;
      latitude : Boolean default true;
      cartoId : Boolean default true;
      normalizedName : Boolean default true;
   };
   url
   {
      mimeType : elementRef;
   };
   contact
   {
      type : String enum {PERSON; ORGANIZATION; };
      note : Boolean default true;
      photo : Boolean default true;
      birthDate : Boolean default true;
   };
   user
   {
      id : Boolean default true;
      createdBy : Boolean default true;
      lastChangedBy : Boolean default true;
      responsible : Boolean default true;
   };
   mimeType : Boolean default true;
   text : Boolean default true;
   language : Boolean default true;
   languageReference : elementRef;
 }; 
@Scope:[#ELEMENT] 
Annotation Semantics
 {
   amount
   {
      currencyCode : elementRef;
   };
   quantity
   {
      unitOfMeasure : elementRef;
   };
   currencyCode : Boolean default true;
   unitOfMeasure : Boolean default true;
 };
Usage

Semantic annotations are used to inform the client as to which of the elements contain a phone number, a part of a name or address, or something relating to a calendar event. They must not be bound, for example, to a dedicated consumption channel. They need to be available for consumption through OData, (S)QL, and so on.

Semantic annotations complement the concept of semantic data types, while semantic data types always introduce specific behavior in the provider/core infrastructure (through dedicated operations or conversion functions).

Semantic annotations allow the standardizing of semantics that only have an impact on the consumption side (such as telephone number, mail address, city, and so on).

Annotation Meaning

Annotations belonging to Semantics.address follow the vCard standard (RFC6350Information published on non-SAP site)

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations (Exception: Semantics.address.number and Semantics.address.streetNoNumber)

Values:

Semantics.address.type[ ]

Description

Values:

String(10)

The following enumerations are provided:

Value Description
HOME Home address
WORK Work address
PREF Preferred address

Default

OTHER Other address
Semantics.address.city Boolean default true The annotated field contains a plain-text string that contains the name of a city.
Semantics.address.country The annotated field contains a plain-text string that contains the name of a country.
Semantics.address.label The annotated field contains a plain-text string representing the formatted address for printing.
Semantics.address.number The annotated field contains a street number separated from a street name.
Semantics.address.postBox The annotated field contains information about a post office box.
Semantics.address.region The annotated field contains a plain-text string that contains the name of a region.
Semantics.address.subRegion The annotated field contains a plain-text string that contains the name of a subregion.
Semantics.address.street The annotated field contains a street name and a street number.
Semantics.address.streetNoNumber The annotated field contains a street name separated from a street number.
Semantics.address.zipCode The annotated field contains a numeric string that contains the ZIP code (type of postal code used within the United States).

Annotations belonging to Semantics.amount contain a monetary amount, and the corresponding currency code is contained in the referenced field.

Scope: [ELEMENT]

Evaluation Runtime (Engine): Interpreted by ABAP Runtime Environment

Values:

Semantics.amount.currencyCode elementRef The annotated field contains a monetary amount, and the corresponding currency code is contained in the referenced field.

Annotations belonging to Semantics.businessDate contain information about changes of database table records.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): *Business data often carries time validities. When accessing data, one usually intends to get the most current or a specific state according to a defined date. It is mandatory for the engine to know the semantics in order to carry out a generic validity evaluation.
Note Many objects used in the Business Suite store data in a way that requires an algorithm to derive the actual data for a validity state. The annotation must not be used if a generic evaluation would yield incorrect results.

Values:

Semantics.businessDate.at* Boolean default true The annotated field indicates that the column contains the key dates and not intervals.
Semantics.businessDate.createdAt* The annotated field is the date (and time) when the database table record was created for the first time.
Semantics.businessDate.from* The annotated field is the date timestamp or interval that defines the validity of the data of the database table record from a business point of view.

Technical validity: The from date is different from the point in time when the record was created. The dates are not to be confused with dates contained in the data part.

Semantics.businessDate.to*
Semantics.businessDate.lastChangedAt The annotated field is the date/time when the database table record was modified for the last time.

It is usually identical to the creation date/time of the insertion, if the record has not been modified.

Evaluation Runtime (Engine): This is required to answer queries like "all changes since…" or "most recent …". The latter is very relevant, for example, for the ranking of a search result.

Annotations belonging to Semantics.calendar follow the iCalendar standard (RFC5545Information published on non-SAP site)

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values: Boolean default true

Semantics.calendar.dayOfMonth Boolean default true The value of the annotated field is a day number relative to a calendar month.
Example 1 - 31
Semantics.calendar.dayOfYear The value of the annotated field is a day number relative to a calendar year.
Example 1 - 366
Semantics.calendar.month The value of the annotated field encodes a calendar month number as a string following the logical pattern MM consisting of two digits.
Example The string matches the regex pattern 0[1-9]|1[0-2]
Semantics.calendar.quarter The value of the annotated field encodes a calendar quarter number as a string following the logical pattern Q consisting of a single digit.
Example The string matches the regex pattern [1-4]
Semantics.calendar.week The value of the annotated field encodes a calendar week number as a string following the logical pattern WW consisting of two digits.
Example The string matches the regex pattern 0[1-9]|[1-4][0-9]|5[2-3]
Semantics.calendar.year The value of the annotated field encodes a year number as a string following the logical pattern (-?)YYYY(Y*) consisting of an optional minus sign for years B.C., followed by at least four digits.
Example The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})
Semantics.calendar.yearMonth The value of the annotated field encodes a calendar year and month as a string following the logical pattern (-?)YYYY(Y*)MM consisting of an optional minus sign for years B.C., followed by at least six digits, where the last two digits represent the months January to December.
Example The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})(0[1-9]|1[0-2])
Semantics.calendar.yearQuarter The value of the annotated field encodes a calendar year and quarter as a string following the logical pattern (-?)YYYY(Y*)Q consisting of an optional minus sign for years B.C., followed by at least five digits, where the last digit represents the quarter.
Example The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})[1-4]
Semantics.calendar.yearWeek The value of the annotated field encodes a calendar year and week as a string following the logical pattern (-?)YYYY(Y*)WW consisting of an optional minus sign for years B.C., followed by at least six digits, where the last two digits represent week number in the year.
Example The string matches the regex pattern -?([1-9][0-9]{3,}|0[0-9]{3})(0[1-9]|[1-4][0-9]|5[2-3])

Annotations belonging to Semantics.calendarItem follow the iCalendar standard (RFC5545Information published on non-SAP site) for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free or busy information, independent of any particular calendar service or protocol

Scope: [ELEMENT, PARAMETER]

Values:

Semantics.calendarItem.categories Boolean default true The value of the annotated field is used to specify categories or subtypes of the calendar item. The categories are useful in searching for a calendar item of a particular type and category.
Semantics.calendarItem.class The value of the annotated field provides a method of capturing the scope of the access the calendar owner intends for information within an individual calendar entry.
The default value is PUBLIC. Other values are PRIVATE, CONFIDENTIAL, iana-token (iCalendar class registered with IANA), or x-name (experimental, non-standard parameter).
Note

Applications must treat x-name and iana-token values they do not recognize the same way as they would the PRIVATE value.

Semantics.calendarItem.completed The value of the annotated field defines the date and time that a to-do was actually completed.
Semantics.calendarItem.contact The value of the annotated field is used to represent contact information or alternately a reference to contact information associated with the calendar item.
Semantics.calendarItem.description The value of the annotated field provides a description of the calendar item.
Semantics.calendarItem.due The value of the annotated field defines the date and time that a to-do is expected to be completed.
Semantics.calendarItem.duration The value of the annotated field is used to identify properties that contain a duration of time.
Semantics.calendarItem.dtEnd The value of the annotated field specifies the date and time that a calendar item ends.
Semantics.calendarItem.dtStart The value of the annotated field specifies the date and time that a calendar item starts.
Semantics.calendarItem.fbType The value of the annotated field specifies the free or busy time type.
Semantics.calendarItem.location The value of the annotated field defines a location related to a calendar component.
Example LOCATION:Conference Room - F123\, Bldg. 002

LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf": Conference Room - F123\, Bldg. 002

Semantics.calendarItem.percentCompl. The value of the annotated field is used by an assignee or delegatee of a to-do to convey the percent completion of a to-do to the "organizer".
Semantics.calendarItem.priority The value of the annotated field defines the relative priority for a calendar item.
Semantics.calendarItem.status The value of the annotated field defines the overall status or confirmation for the calendar item.
Semantics.calendarItem.summary The value of the annotated field defines a short summary or subject for the calendar item.
Semantics.calendarItem.transparent The value of the annotated field defines whether or not an event is transparent to busy time searches.
Semantics.calendarItem.wholeDay The value of the annotated field defines whether or not an event covers whole days instead of exact time slots.

Annotations belonging to Semantics.contact follow the vCard standard (RFC6350Information published on non-SAP site)

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values:

Semantics.contact.type

Value: String

The following enumerations are provided:

Value Description
PERSON Content relates to an individual
ORGANIZATION Content relates to an organization, company, etc.
Semantics.contact.birthDate Boolean default true This annotated field contains the birth date of the individual.
Semantics.contact.note This annotated field specifies supplemental information or a comment that is associated with the vCard.
Semantics.contact.photo This annotated field contains an image or photograph related to the contact.
Semantics.currencyCode

This annotation tags a field containing a currency code

This can be either an ISO codeInformation published on non-SAP site or an SAP currency code (data type CUKY).

Scope: [ELEMENT]

Evaluation Runtime (Engine): Interpreted by ABAP Runtime Environment

Value: Boolean default true

Annotations belonging to Semantics.email follow RFC5322Information published on non-SAP site).

Note The attribute address should be used in case a mail address is included – independent from the specialized semantics from, sender, to, cc, or bcc.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Semantics.email.type

Description

Values: String

The following enumerations are provided:

Value Description
HOME Private email address
WORK Business email address
PREF Preferred email address
OTHER Other email address
Semantics.email.address Boolean default true The value of the annotation contains the addresses of the sender and the recipient of an email. An address can be an individual mailbox or a group of mailboxes.
Semantics.email.bcc The value of the annotation contains the recipient list that receive an email, but whose email addresses are not revealed to other recipients of the same email.
Semantics.email.body The value of the annotation contains lines of US-ASCII characters.
Semantics.email.cc The value of the annotation contains the recipient list that receive an email that is not directed to them directly.
Semantics.email.from The value of the annotation specifies the author(s) of a message. This can be a person or persons, or a system.
Semantics.email.keywords The value of the annotated field contains a comma-separated list of one or more words or quoted strings.
Semantics.email.received The value of the annotated field contains a trace information at the beginning of the message content when an SMTP server receives a message for delivery or further processing.
Semantics.email.sender The value of the annotated field specifies the mailbox of the agent responsible for the actual transmission of the message. For example, if a secretary were to send a message for another person, the mailbox of the secretary would appear in the Sender field.
Semantics.email.subject The value of the annotated field contains the topic of the message.
Semantics.email.to The value of the annotation contains the recipient list that receive an email that is primarily directed to them directly.

Annotations belonging to Semantics.fiscal are required for time-based calculations in analytical use cases.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): Some attributes contain the respective information (as plain integers), and the processor needs the semantics in order to identify them.

Values (optional): Boolean default true

Semantics.fiscal.period Boolean default true A fiscal period is covered by financial reports, for example, an annual report covers a fiscal period of one year, but a quarterly report includes accounting data for three months.

The value of the annotated field encodes a fiscal period as a string following the logical pattern PPP consisting of three digits. This fiscal period usually is a quarter of a year.

Example The string matches the regex pattern [0-9]{3}
Semantics.fiscal.year The value of the annotated field encodes a fiscal year number as a string following the logical pattern YYYY consisting of four digits.
Example The string matches the regex pattern [1-9][0-9]{3}
Semantics.fiscal.yearPeriod The value of the annotated field encodes a fiscal year and period as a string following the logical pattern YYYYPPP consisting of seven digits. The last three digits represent the fiscal period in the year.
Example The string matches the regex pattern ([1-9][0-9]{3})([0-9]{3})
Semantics.fiscal.yearVariant The value of the annotated field encodes a fiscal year variant, which describes the number of periods in a fiscal year and how they match the calendar year.

Annotations belong to Semantics.geoLocation contain geo-coordinates for depicting data on a map.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Values:

Semantics.geoLocation.cartoId Boolean default true  
Semantics.geoLocation.latitude The value of the annotated field specifies the latitude of the location such as a city.
Semantics.geoLocation.longitude The value of the annotated field specifies the longitude of the location such as a city.
Semantics.geoLocation.normalizedName The value of the annotated field contains the readable name of the location.
Semantics.language

This annotation identifies a language.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values (optional): Boolean default true

Semantics.languageReference

This annotation references a field that identifies languages. You can use this annotation if you cannot define a language as constant value.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Values (optional): elementRef

Semantics.mimeType

This annotation describes the mime type of a resource (identified by a URL or directly available as binary content).

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

This is required when accessing the document content, for example, in a content crawl, during text analysis, or when opening the document for viewing.

In UIs, documents are usually presented with an icon that symbolizes their mime type.

Values: Boolean default true

Annotations belonging to Semantics.name follow the vCard standard (RFC6350Information published on non-SAP site).

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values:

Semantics.name.additionalName Boolean default true The value of the annotation contains the second first name of an individual.
Semantics.name.familyName The value of the annotation contains the surname of an individual.
Semantics.name.fullName The value of the annotation contains the full name of an individual.
Semantics.name.givenName The value of the annotation contains the first name of an individual.
Semantics.name.jobTitle The value of the annotation contains the job title of an individual.
Semantics.name.nickName The value of the annotation contains the nickname of an individual.
Semantics.name.prefix The value of the annotation contains the honorific prefix of an individual.
Semantics.name.suffix The value of the annotation contains the honorific suffix of an individual.

Annotations belonging to Semantics.organization follow the vCard standard (RFC6350Information published on non-SAP site).

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values:

Semantics.organization.name Boolean default true The value of the annotated field contains the organization name.
Semantics.organization.role The value of the annotated field specify the function or part played in a particular situation by the object the vCard represents.
Example ROLE:Project Leader
Semantics.organization.unit The value of the annotated field contains the name of the organization unit.

Annotations belonging to Semantics.quantity contain a measured quantity, and the corresponding unit of measure is contained in the referenced field.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values:

Semantics.quantity.unitOfMeasure elementRef The value of the annotated field specifies a unit of measure related to a measured quantity.

Annotations belonging to Semantics.systemDate specify the date/time that is recorded by the technical infrastructure/database.

Note The sub-annotations have the same semantics as the equally named attributes of the businessDate annotation. The difference is that values contain the date/time of the creation/change and are recorded by the database.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Values:

Semantics.systemDate.createdAt Boolean default true Timestamp when database record was created.
Semantics.systemDate.lastChangedAt Timestamp when database record was last changed.

Annotations belonging to Semantics.telephone follow the vCard standard RFC5322Information published on non-SAP site)

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values: String(10)

Semantics.telephone.type

Values: default #PREF

The following enumerations are provided:

Value Description
CELL Cell phone
FAX Fax
HOME Private phone
PAGER Pager
PREF Preferred phone
TEXT Phone that supports text messages (SMS)
TEXT_PHONE Telecommunication device for people with hearing or speech difficulties
VIDEO Video conferencing phone
VOICE Voice phone
WORK Business phone
Semantics.text

This annotation identifies a human-readable text that is not necessarily language-dependent.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values: Boolean default true

Semantics.time

This annotation is used to indicate a date semantic for the NVARCHAR-based ABAP type TIMS.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Value : Boolean default true

Semantics.unitOfMeasure

This annotation tags a field as containing a unit of measure.

Note There seems to be currently no internationally recognized standard list for units of measure available.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Values: Boolean default true

Annotations belonging to Semantics.url contain a URL, and its mime type is contained in the referenced second field.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations

Values:

Semantics.url.mimeType elementRef This annotated field is required when opening a document for viewing, or when accessing document content during text analysis. In UIs, documents are usually presented with an icon that symbolizes their mime type.

Annotations belonging to Semantics.user define the ID of the user related to the data record.

The attribute id should be used if the user ID without additional semantics is included. If the dedicated semantics of the user ID are known, the attributes ceratedBy, lastChangedBy or responsible should be used.

Scope: [ELEMENT, PARAMETER]

Evaluation Runtime (Engine):

Values:

Semantics.user.createdBy Boolean default true The value of the annotated field specifies who created a data record.
Semantics.user.id The value of the annotated field contains the ID of a user.
Semantics.user.lastChangedBy The value of the annotated field specifies who changed a data record at last.
Semantics.user.responsible The value of the annotated field specifies who is the person responsible for a data record.
Examples

Example 1

The following CDS view fetches the contact data. Here, the annotations assign to the corresponding fields the relevant semantic information, such as first name, last name, and so on.

Sample Code
DEFINE VIEW ContactPerson ...
ASSOCIATION [1..1] TO FormattedName AS _FormattedName ON ...
{
  ...
  @Semantics.name.givenName
  FirstName, 

  @Semantics.name.additionalName
  MiddleName, 

  @Semantics.name.familyName
  LastName, 

  @Semantics.user.id
  SystemUser, 

  Initials, 

  GenderCode, 

  AddressUUID, 

  @Semantics.telephone.type: [#WORK, #PREF] 
  PhoneNumber, 

  @Semantics.telephone.type: [#FAX] 
  FaxNumber, 

  @Semantics.telephone.type: [#CELL] 
  MobilePhoneNumber,

  @Semantics.eMail.address 
  EmailAddress, 

  PreferredLanguage,

  @Semantics.contact.birthDate 
  BirthDate,

  @Semantics.name.fullName
  _FormattedName.FormattedContactName,
  ...
}

Example 2

The following CDS view fetches sales order items. Here, the annotations assign the units and currencies to the corresponding fields.

Sample Code
DEFINE VIEW SalesOrderItem as select from ... 
{
    ...
    
    @Semantics.currencyCode
    currency_code as CurrencyCode,
    
    @Semantics.amount.currencyCode: 'CurrencyCode' 
    gross_amount as GrossAmount,
    
    @Semantics.unitOfMeasure
    unit_of_measure as UnitOfMeasure,
    
    @Semantics.quantity.unitOfMeasure: 'UnitOfMeasure' 
    quantity as Quantity,
    
    ...   
}

Example 3

The following CDS view fetches geographic data of cities annotating the corresponding location fields according to a standardized format:

Sample Code
DEFINE VIEW myGeoAttributeView as select from ... 
{ 
  @Semantics.address.city
  cartoid,

  @Semantics.geoLocation.longitude
  Longitude,

  @Semantics.geoLocation.latitude
  latitude,

  @Semantics.geoLocation.normalizedName
  name
}

Example 4

The following CDS view fetches language-dependant data annotating the corresponding language fields and text fields:

Sample Code
DEFINE VIEW chartOfAccountsTexts AS SELECT FROM ...
{
  key ktopl AS chartOfAccounts,

  @Semantics.language: true
  key spras AS language,

  @Semantics.text: true   
  ktplt AS chartOfAccountsName
}