Semantics Annotations
Used by the core engines for data processing, analytics, and data consumption
@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;
};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
(RFC6350 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 (RFC5545 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 (RFC5545 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 (RFC6350 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 code Scope: [ELEMENT] Evaluation Runtime (Engine): Interpreted by ABAP Runtime Environment Value: Boolean default true |
|
|
Annotations belonging to Semantics.email follow RFC5322 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 (RFC6350 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 (RFC6350 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 RFC5322 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. | |
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.
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.
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:
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:
DEFINE VIEW chartOfAccountsTexts AS SELECT FROM ...
{
key ktopl AS chartOfAccounts,
@Semantics.language: true
key spras AS language,
@Semantics.text: true
ktplt AS chartOfAccountsName
}