Date post: | 07-Jul-2018 |
Category: |
Documents |
Upload: | dama1233626 |
View: | 213 times |
Download: | 0 times |
of 20
8/19/2019 DOC-44986 (1)
1/20
Generated by Jive on 2016-01-19+01:00
1
SAP Annotations for OData Version 2.0
IntroductionOData services provide a uniform interface for interacting with their resources, and in additionare self-describing:
• The service document (located at the service root) lists the available top-level resources, and• The service metadata document (located at the address $metadata relative to the service root)
describes the structure of all resources in the service.
This structural metadata makes it easy to understand a service, and human-readabledocumentation can be directly embedded into the metadata document, helping developersconsume an OData service.This alone is a huge benefit, yet metadata can be taken onestep further by embedding machine-readable additional metadata that can be leveraged bydevelopment tools, client libraries, and generic clients to better interact with the service.Onearea are semantic annotations that tell which of the OData properties contain e.g. a phone number,a part of a name or address, or something related to a calendar event or an analytic query. Thisis important for apps running on mobile devices that want to seamlessly integrate into contacts,calendar, and telephony.The next area are capability annotations that describe which of the possibleinteractions defined by OData's uniform interface are supported by which parts of a concreteservice. These annotations will e.g. tell whether an entity set allows inserts, updates, or deletes,whether it requires a filter, and which properties can be used in filter expressions. They alsoadvertise capabilities that go beyond the base set defined by OData, e.g. whether an entity setallows free-text search via an SAP-defined query option on page .
Contents
• Introduction on page 1• Contents on page 1• AtomPub Service Document on page 2
• Element app:service on page 2• Element app:collection on page 2
• Metadata Document on page 2• Element edm:Schema on page 3• Element edm:EntityContainer on page 3• Element edm:EntitySet on page 4
• Attribute sap:semantics on page 5• Element edm:EntityType on page 6
• Attribute sap:semantics on page 6• Element edm:Property on page 7
• Attributes sap:unit and sap:precision on page 11• Attribute sap:field-control on page 12• Attribute sap:semantics on page 12• Attribute sap:filter-restriction on page 16• Attribute sap:aggregation-role on page 16• Attribute sap:parameter on page 16• Attribute sap:preserve-flag-for on page 17
• Element edm:NavigationProperty on page 17• Element edm:FunctionImport on page 17
8/19/2019 DOC-44986 (1)
2/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
2
• Element sap:value-constraint on page 18• Element edm:Parameter on page 19• Element edm:AssociationSet on page 19
• Instance Annotations on page 19• Query Option search on page 19
AtomPub Service DocumentAtomPub allows extending the service document with elements and attributes from XMLnamespaces other than AtomPub. The following sections describe which elements of theservice document (namespace prefix app) can be annotated with attributes and elements fromthe namespace http://www.sap.com/Protocols/SAPData (namespace prefix sap) and from thenamespace http://www.w3.org/2005/Atom (namespace prefix atom), and what these annotationsmean.
Element app:service
The app:service element can be annotated with two elements from the atom namespace:• contains the link to this service document, and• contains the link to latest version of this service.
If the latest-version link deviates from the self link, a client may inspect the newer version of theservice and decide (probably after asking its user) to switch over to the newer service version.
Element app:collection
The app:collection element can be annotated with three elements:• contains the human-readable name or caption for a single member of the
collection. This typically is the singular form of the content of the element of this
collection.• contains the link to an OpenSearch description document that
describes how to use free-text search for this collection. For those not familiar with OpenSearch: justappend the SAP-specific query option search on page to the URL of the collection.
• contains the linkto the collection of the same service that allows subscribing to content changes of the annotatedcollection. For more information see the HowTo Guides - Subscription & Notification with SAPNetWeaver Gateway - Series.
It can also contain the attribute sap:addressable with the same value as for the corresponding entity set in the
metadata document.
Metadata DocumentOData's Conceptual Schema Definition Language (CSDL) allows annotating most model elementswith XML attributes or elements from foreign XML namespaces. The following sections describewhich elements of the metadata document (namespace prefix edm) can be annotated withattributes and elements from the namespace http://www.sap.com/Protocols/SAPData (namespace
http://msdn.microsoft.com/en-us/library/dd541474.aspxhttp://scn.sap.com/community/gateway/blog/2012/05/07/howto-guides--subscription-notification-with-sap-netweaver-gateway--serieshttp://scn.sap.com/community/gateway/blog/2012/05/07/howto-guides--subscription-notification-with-sap-netweaver-gateway--serieshttp://tools.ietf.org/html/rfc5023http://www.sap.com/Protocols/SAPDatahttp://msdn.microsoft.com/en-us/library/dd541474.aspxhttp://scn.sap.com/community/gateway/blog/2012/05/07/howto-guides--subscription-notification-with-sap-netweaver-gateway--serieshttp://scn.sap.com/community/gateway/blog/2012/05/07/howto-guides--subscription-notification-with-sap-netweaver-gateway--serieshttp://www.sap.com/Protocols/SAPData/rel#subscribehttp://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_documenthttp://www.w3.org/2005/Atomhttp://www.sap.com/Protocols/SAPDatahttp://tools.ietf.org/html/rfc5023
8/19/2019 DOC-44986 (1)
3/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
3
prefix sap), and what these annotations mean. For binary attributes the meaning is desribed forthe value "true".
Element edm:Schema
Schemas can be annotated with the following attributes. If not stated explicitly, consumers can assume them to
have the default value listed in the second column. This default value reflects the "normal" behavior.
Attribute Name Default Value Meaning
schema-version 0000 A non-negative number indicating
the version of the schema. This
can be considered a sub/minor
version of the service version. It
should be incremented whenever
additive changes are made in a
subsequent shipment of the sameservice version, and it can be used
by clients to detect whether the
service meets their minimal data
provisioning needs.
Element edm:EntityContainer
Entity containers can be annotated with the following attributes. If not stated explicitly, consumers can assume
them to have the default value listed in the second column. This default value reflects the "normal" behavior.
Attribute Name Default Value Meaning
supported-formats atom json A white-space separated list of
format shortnames. Possible list
items:
• atom• json• xlsx
The default is sap:supported-
formats="atom json".
use-batch falseWrap all requests to resourcesof this service in batch requests;
only the service document and
the metadata document can be
accessed unwrapped.This avoids
exposing sensitive data in URLs
8/19/2019 DOC-44986 (1)
4/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
4
(even with HTTPS URLs can be
visible in log files)
Element edm:EntitySetEntity sets can be annotated with the following attributes. If not stated explicitly, consumers canassume them to have the default value listed in the second column. This default value reflectsthe "normal" behavior that can be expected from any OData service.
Attribute Name Default Value Meaning
label - Description, will also be used asatom:title in the service document
creatable true New entities can be created in thisset
updatable true Entities in this set can be updated
updatable-path - Entities in this set can be updatedor not depending on their state.The value of this attribute is apath expression that identifies aBoolean property in the contextof the entity type of the entity set.The value of this property indicateswhether the entity can be updatedor not.
deletable true Entities can be deleted from thisset
deletable-path - Entities in this set can be deletedor not depending on their state.The value of this attribute is apath expression that identifies aBoolean property in the contextof the entity type of the entity set.The value of this property indicateswhether the entity can be deletedor not.
searchable false Supports custom query optionsearch
pageable true Supports system query options
$top and $skip
topable true Supports system query option $top
countable true Supports system query option$inlinecount=allpages and pathsuffix /$count
addressable true Use “false” if this entity
set can only be accessed
http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3
8/19/2019 DOC-44986 (1)
5/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
5
within its containing entity,
e.g. SalesOrderItems
within SalesOrders through
SalesOrders(4711)/Items.
Direct access to non-
addressable entity collections
will result in a 404 responsecode. The set may however
allow access to single
entities identified by their
key properties values, e.g.
SalesOrderItems(OrderID=4711,Item
requires-filter false Use “true” if this set cannot
be queried without providing
a $filter expression. If accessedwithout a filter expression, it willrespond with a human-readableerror message explaining whichkinds of filter expressions arerequired as a minimum
change-tracking false Changes to entities of this setcan be tracked. Consumers cansubscribe by adding an HTTPPrefer header odata.track-changesto the request. The responsewill then include a delta link forrequesting information aboutchanges in the future.
maxpagesize - Maximum number of entities
returned in an OData response.If more entities are included inthe result of an OData request,the service applies server-drivenpaging.
delta-link-validity - The maximum duration in secondsa delta link in an OData responseremains valid. Afterwards,resources associated with thechange tracking subscription maybe cleaned up and will be nolonger available.
semantics - See table below
Attribute sap:semantics
This attribute can take the following values in the context of an entity type:
Value Meaning
8/19/2019 DOC-44986 (1)
6/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
6
aggregate The entities of this set are automatically aggregatedif the query option $select is specified. Each propertylisted in $select is treated according to its aggregationrole, see description of attribute sap:aggregation-rolebelow
fixed-values The entity set represents a list of fixed values, i.e. it isunlikely to change often, and the list is typically short
Element edm:EntityType
Entity types can be annotated with the following attributes:
Attribute Name Meaning
label Description, will also be used as sap:member-title in
the service document
semantics See table below
Attribute sap:semantics
This attribute can take the following values in the context of an entity type:
Value Meaning
vcard Entities of this type contain contact informationfollowing the vCard standard, see values forsap:semantics on property level on page
vevent Entities of this type contain event/appointmentinformation following the iCalendar standard, seevalues for sap:semantics on property level on page
vtodo Entities of this type contain todo/task informationfollowing the iCalendar standard, see values forsap:semantics on property level on page
parameters This entity type represents parameters for ananalytical query
aggregate Entity sets with this type return result feeds withaggregated values for properties annotated with
sap:aggregation-role="measure".The aggregationtakes into account the dimension properties specifiedin the $select system query option of the request. Seealso description of annotation sap:aggregation-role.
variant This entity type represents query selection variantsbundling parameter selections and filter expressionsfor obtaining specific query results
http://tools.ietf.org/html/rfc5545#section-3.2.9http://tools.ietf.org/html/rfc5545#section-3.2.9
8/19/2019 DOC-44986 (1)
7/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
7
Element edm:Property
The annotation sap:labelis required for properties. All other annotations are optional.
Attribute Name Default Value Meaning
label - A short, human-readable textsuitable for labels and captions inUIs
heading - A short, human-readable textsuitable for column headings in UIs
quickinfo - A human-readable text suitable fortool tips in UIs
semantics - See table below
creatable true Values for this property can bechosen by client when creating
an instance. “False” if valueis always set by the server,e.g. document number fromnumber range.
updatable true Values of this property can bechanged. Must be “false” if itis “false” at entity set level. If updatability can change perentity or based on the entities'state, do not use this staticannotation and use sap:field-control instead.
sortable true Can be used in $orderby systemquery option.
filterable true Can be used in $filter system queryoption.
required-in-filter false Must be used in $filter systemquery option.
filter-restriction - See table below
text - A path expression that identifies aproperty in the context of the entitytype containing a human-readable
text for the value of this property.unit - A path expression that identifies a
property in the context of the entitytype containing the currency codeor unit of measure for a numericvalue.
precision - A path expression that identifiesa property in the context of the
http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3
8/19/2019 DOC-44986 (1)
8/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
8
entity type containing the numberof significant decimal places for anumeric value.
visible true Values of this property are typicallyvisible to end users. If visibilitycan change per entity or based on
the entities' state, do not use thisstatic annotation and use sap:field-control instead.
field-control 3 A path expression that identifies
a property containing a numeric
value that controls visibility:
• 0 = hidden,• 1 = read-only,• 3 = optional,• 7 = mandatory
See section below for details
validation-regexp - Values for this property haveto match the specified regularexpression. The regularexpression is a JavaScript RegularExpression.
display-format - There are currently three possible
values:
• “Date” indicates thatonly the date part of anEdm.DateTime value is
relevant• "NonNegative" indicates that
only non-negative numericvalues are provided andpersisted, other input will leadto errors
• "UpperCase" indicates thatuppercase values are providedand persisted, lowercase inputwill be converted
lower-boundary - A property holding the upperboundary of a value range includes
this attribute. The value of thisattribute is always the name ofanother property in the same type.It points to the property holding therelated lower boundary.
upper-boundary - A property holding the lowerboundary of a value range includesthis attribute. The value of thisattribute is always the name of
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressionshttp://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressionshttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressionshttp://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3
8/19/2019 DOC-44986 (1)
9/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
9
another property in the same type.It points to the property holding therelated upper boundary.
aggregation-role - See table below
super-ordinate - If values of this property are
meaningful (unique) only in thecontext provided by the value ofanother property, then this attributeholds the name of the context-providing property. The value ofthis attribute is always the name ofanother property in the same type.
attribute-for - A property representing anattribute of another propertyincludes this attribute. The value ofthis attribute is always the name ofanother property in the same type.
It points to the property for whichthis property is an attribute.
hierarchy-node-for - A property holding node IDs fora hierarchy structure of values ofsome other property includes thisattribute. The value of this attributeis always the name of anotherproperty in the same type. It pointsto the property for whose valuesthe hierarchy is defined.
hierarchy-node-external-key-for - A property holding the externalkey of a hierarchy node includes
this attribute. The external key isa human-readable identification ofa node. The value of this attributeis always the name of anotherproperty in the same type. It pointsto the related property holding thehierarchy node ID.
hierarchy-level-for - A property holding level numbersfor a hierarchy structure of valuesof some other property includesthis attribute. The value of thisattribute is always the name of
another property in the same type.It points to the related propertyholding the hierarchy node ID. Aproperty holding level numbers hasan integer data type. The root nodeof the hierarchy is at level 0.
hierarchy-parent-node-for - A property holding parent node IDsfor a hierarchy structure of values
8/19/2019 DOC-44986 (1)
10/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
10
of some other property includesthis attribute. The value of thisattribute is always the name ofanother property in the same type.It points to the related propertyholding the hierarchy node ID. For
the root node of the hierarchy theparent node ID is null.
hierarchy-parent-navigation-for - A navigation property for accessingthe parent entity of a node. Itoffers an alternative method foraccessing the parent node ID, ifthe entity type does not have adedicated property for that.
hierarchy-drill-state-for - A property holding the drill stateof a hierarchy node includes thisattribute. The drill state is indicatedby one of the following values:
collapsed, expanded, leaf. Thevalue of this attribute is always thename of another property in thesame type. It points to the relatedproperty holding the hierarchynode ID. For a collapsed hierarchynode or a leaf, the hierarchy nodeID of such an entity does not occuras parent node ID of any otherentity in the set.
hierarchy-node-descendant-count-for
- A property holding the descendantcount for a hierarchy node includes
this attribute. The descendantcount of a node is the number ofits descendants in the hierarchystructure of the result consideringonly those nodes matching anyspecified $filter and $search. Thevalue of this attribute is alwaysthe name of another propertyin the same type. It points tothe related property holding thehierarchy node ID. A propertyholding descendant counts has aninteger data type.
parameter - See table below
is-annotation false Represents an instanceannotation.
updatable-path - If a property can be updated or
not depending on the state of its
entity, it can be annotated with this
8/19/2019 DOC-44986 (1)
11/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
11
attribute. The value of this attribute
is always a path expression that
identifies a Boolean property in
the context of the entity type. This
related property indicates whether
the annotated property can beupdated for the containing entity or
not.
Note: if used in addition to the
more expressive field-control on
page 12 annotation, the values
of the two must be in sync.
preserve-flag-for - See below
filter-for - A property whose value is a $filterexpression includes this attribute.
The $filter expression must bevalid for the entity type specified inthis attribute.
Attributes sap:unit and sap:precision
Amounts in a currency or absolute measures MUST be represented as simple properties with anappropriate numeric Edm type, preferably Edm.Decimal. These numeric properties SHOULD referto a string property containing the ISO currency or unit of measure with the sap:unit attribute.
They MAY refer to a numeric property containing the (non-negative) number of decimal places tobe used for displaying the amount or measure with the sap:precision attribute.
Example in metadata document:
Example in Atom entry:
50
http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part3-csdl/odata-v4.0-errata02-os-part3-csdl-complete.html#_The_edm:Path_Expression_3
8/19/2019 DOC-44986 (1)
12/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
12
KGM
86.9
2
EUR
Euro
Using a reference attribute instead of predefined complex types like Measure or Money withamount and unit properties allows several amounts to share the same unit. Transporting theamounts as “raw” numeric values instead of preformatted strings allows clients to format themaccording to device-specific settings (that may well differ from the server-side user settings) orprocess them on the client (if e.g. the client is Excel).
Attribute sap:field-control
Whether a property can or must contain a value may depend on the state of its entity, so it is impossible to
express this up-front via metadata annotations. In these cases the "edit state" of the property can be expressed
via a separate "field control" property, and the link between data properties and their field-control properties is
expressed with the sap:field-control attribute.
Example in metadata document:
The field-control property can be in the same type as shown above, or it can be in a nested complex type, or in
an entity type that is associated 1:1. This allows separating field-control data from "real" data. If for example the
field-control property is contained in a complex property or navigation property named fc, the attribute value is
a path relative to the parent of the annotated property, e.g. sap:field-control="fc/Address".
The possible values for a field-control property are:
Value Meaning
7 Mandatory - property must contain a value
3 Optional - property may contain a null value
1 Read-only - property cannot be changed
0 Hidden - property should not be visible on user
interfaces
Attribute sap:semantics
The possible values in the context of a property are:
Value Meaning
8/19/2019 DOC-44986 (1)
13/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
13
tel Telephone number
tel;type=cell,work Work cellphone number; see explanation below tablefor more values
tel;type=fax Fax number
email Email addressemail;type=pref Preferred email address
url Web URL
name Formatted text of the full name
givenname First name or given name of a person
middlename Middle name of a person
familyname Last name or family name of a person
nickname Descriptive name given instead of or in addtion to theone marked as "name"
honorific Title of a person (Ph.D., Dr., ...)
suffix Suffix to the name of a person
note Supplemental information or a comment that isassociated with the vCard
photo URL of a photo of a person
city Address: city
street Address: street
country Address: country
region Address: state or province
zip Address: postal code
pobox Address: post office box
org Organization name
org-unit Organizational unit
org-role Organizational role
title Job title
bday Birth date
summary Calendar: summary of a calendar component
description Calendar: description of a calendar component,detailing the summary
categories Calendar: comma-separated list of categories for acalendar component
dtstart Calendar: the date and time that a calendarcomponent starts
8/19/2019 DOC-44986 (1)
14/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
14
dtend Calendar: the date and time that a calendarcomponent ends
duration Calendar: duration as an alternative to dtend, seexs:duration
due Calendar: the date and time that a to-do is expected
to be completed
completed Calendar: the date and time that a to-do was actuallycompleted
priority Calendar: the relative priority for a calendarcomponent, 0 for undefined, 1 for highest, ... 9 forlowest
class Calendar: access classification for a calendarcomponent
status Calendar: overall status or confirmation for thecalendar component
percent-complete Calendar: percent completion of a to-do., rangingfrom 0 to 100 (integer)
contact Calendar: contact information or alternatively areference to contact information associated with thecalendar component
location Calendar: the intended venue for the activity definedby a calendar component
transp Calendar: defines whether or not an event istransparaent to busy time searches
fbtype Calendar: free/busy time type, see [iCalendar,
Section 3.2.9]
wholeday Calendar: "true" or "false, depending on whether anevent is scheduled for an entire day
year Calendar: year as string following the regex pattern(-?)YYYY(Y*) consisting of an optional minus sign foryears B.C. followed by at least four digits
yearmonth Calendar: year and month as string following theregex pattern (-?)YYYY(Y*)MM consisting of anoptional minus sign for years B.C. followed by atleast six digits, the last two digits are a numberbetween 01 and 12 representing the months January
to December
yearmonthday Calendar: year, month and day as string following thelogical pattern (-?)YYYY(Y*)MMDD consisting of anoptional minus sign for years B.C. followed by at leasteight digits, where the last four digits represent themonths January to December (MM) and the day ofthe month (DD). The string matches the regex pattern-?([1-9][0-9]{3,}|0[0-9]{3})(0[1-9]|1[0-2])(0[1-9]|[12]
http://tools.ietf.org/html/rfc5545#section-3.2.9http://tools.ietf.org/html/rfc5545#section-3.2.9http://www.w3.org/TR/xmlschema11-2/#duration
8/19/2019 DOC-44986 (1)
15/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
15
[0-9]|3[01]) The regex pattern does not reflect theadditional constraint for "Day-of-month Values": Theday value must be no more than 30 if month is one of04, 06, 09, or 11, no more than 28 if month is 02 andyear is not divisible by 4, or is divisible by 100 but notby 400, and no more than 29 if month is 02 and year
is divisible by 400, or by 4 but not by 100from Mail: author of message, see [RFC5322, section
3.6.2]
sender Mail: mailbox of agent responsible for actualtransmission
to Mai: comma-separated list of primary recipients, see[RFC5322, section 3.6.3]
cc Mail: carbon copy, comma-separated
bcc Mail: blind carbon copy, comma-separated
subject Mail: topic of the message
body Mail: message body
keywords Mail: comma-separated list of important words andphrases that might be useful for the recipient
received Mail: DateTime the message was received
geo-lon Geolocation: longitude
geo-lat Geolocation: latitude
currency-code ISO currency code
unit-of-measure Unit of measure, preferably ISO
count Aggregation: the number of leaf entities that havebeen aggregated into the response entity (count(*)in SQL). Only valid for one property of an entity typethat is annotated with sap:semantics="aggregate".
For “tel” the type values are (see [vCard, section 6.4.1]):• "home" to indicate a telephone number associated with a residence• "work" to indicate a telephone number associated with a place of work• “pref" to indicate a preferred-use telephone number• "text" to indicate a telephone number supporting text messages (SMS)• "voice" to indicate a voice telephone number• "fax" to indicate a facsimile telephone number• "cell" to indicate a cellular telephone number
• "video" to indicate a video conferencing telephone number• "pager" to indicate a paging device telephone number• "textphone" to indicate a telecommunication device for people with hearing or speech difficulties
For “email” the type values are:• "home" to indicate an email address associated with a residence• "work" to indicate an email address associated with a place of work• “pref" to indicate a preferred-use email address
http://tools.ietf.org/html/rfc6350#section-6.4.1http://tools.ietf.org/html/rfc5322#section-3.6.2http://tools.ietf.org/html/rfc6350#section-6.4.1http://tools.ietf.org/html/rfc5322#section-3.6.3http://tools.ietf.org/html/rfc5322#section-3.6.2http://tools.ietf.org/html/rfc5322#section-3.6.2
8/19/2019 DOC-44986 (1)
16/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
16
For “url” and constituents of an address the type values are:• "home" to indicate an address associated with a residence• "work" to indicate an address associated with a place of work• “org" to indicate an address associated with the organization• “pref” to indicate a preferred address “other” to indicate some other address
These type values can be specified as a value list (like "type=work,pref").
Attribute sap:filter-restriction
A property can be annotated with this attribute, if filter restrictions exist. The attribute can takethe following values:
Value Meaning
single-value Only a single “eq”clause is possible.
multi-value Several “eq” clauses, separated by or, arepossible.
interval At most one “ge” and one “le” clause,
separated by “and”, alternatively a single “eq”
clause.
Attribute sap:aggregation-role
A property can be annotated with this attribute, if it has an aggregation role. The attribute cantake the following values:
Value Meaning
dimension The property represents the key of adimension. Only valid for properties of an entity type that is annotated with
sap:semantics=“aggregate“.
measure The property represents a measure whosevalues will be aggregated according to theaggregating behavior of the containingentity type. Only valid for properties of an entity type that is annotated withsap:semantics=“aggregate“.
totaled-properties-list The property value is a comma-separated list oftotaled dimension property names.
Attribute sap:parameterA property can be annotated with this attribute, if it represents a parameter. The attribute cantake the following values:
Value Meaning
mandatory A value must be supplied for this parameter.
optional A value for this parameter can be left out byspecifying an empty string (applicable only for
8/19/2019 DOC-44986 (1)
17/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
17
parameter properties of type Edm.String). A valuefor this parameter can be left out by specifying anempty string (applicable only for parameter propertiesof type Edm.String). For parameters of other types,the default value conveyed in the metadata should beassigned, if the parameter shall be omitted.
Attribute sap:preserve-flag-for
A property holding the preservation state for another property includes this attribute.Thepreservation state is a Boolean flag indicating whether or not the value of a named entityproperty is protected against updates causedby side-effects of updates to the entityset.Example:Consider an entity set holding order items with unit price, quantity, and totalamount. All three properties supports preservation, as shown here for the unit price:
For a given order item, a consumer can set the preservationflag for the total amount and update the unit price. This would instruct the provider to recalculatethe quantity instead of the total amount.
Element edm:NavigationProperty
Attribute Name Default Value Meaning
filterable true Can be used as a path segment forproperties in $filter system queryoption
Element edm:FunctionImport
Attribute Name Meaning
action-for Value is the qualified name of an entity type in scope.Indicates that the function or action operates oninstances of that entity type. The function importMUST have a required parameter for each keyproperty of that entity type. Parameter name andtype must be identical to the name and type of thecorresponding key property.
applicable-path Value is a path to a Boolean property in the entitytype named in the action-for attribute. The propertyindicates whether the function import can be invokedfor the entity. The path can be the name of a Booleanproperty, or the name of a complex property followedby a forward slash and the path to a Boolean propertyin the complex type.
label Description
8/19/2019 DOC-44986 (1)
18/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
18
planning-function This function processes or generates plan data thatmay be exposed by entity sets of aggregate entitytypes in the same service. Its logic may have side-effects on these entity sets.
Example: a function import that allows approving a leave request. The LeaveRequest entitytype has a single key property ID and a complex property ControlData with a Boolean property
NeedsApproval that controls the applicability of two alternative actions, approval and rejection:
A function import can optionally include an annotation with an sap:value-constraint element.
Element sap:value-constraint
This element describes a dependency of function import parameters to key properties of anentity set, comparable to a referential constraint. Example: For a function import with twoparameters for country and region, the possible arguments can be determined via some Regionsentity set.
It has a set attribute that identifies the entity set containing the list of allowed parameter value combinations.
Nested sap:parameter-ref elements link the function import parameters specified with the name attribute to a
key property of the entity type of the specified entity set. The sequence of sap:parameter-ref elements matches
the sequence of the edm:PropertyRef elements of the Key element.
8/19/2019 DOC-44986 (1)
19/20
SAP Annotations for OData Version 2.0
Generated by Jive on 2016-01-19+01:00
19
Element edm:Parameter
Attribute Name Meaning
label Description
Element edm:AssociationSet
Attribute Name Default Value Meaning
creatable true Relations can be created
updatable true Relations can be changed
deletable true Relations can be deleted
Instance AnnotationsAn annotation of an element in the OData metadata document adds information at the structurallevel of the service. Sometimes extra pieces of information are needed in the OData responsefor individual entities and their properties. To distinguish these two cases the former are calledmetadata annotations, while annotations of the entities in the OData response are calledinstance annotations.Metadata annotations add information to the model structure. They arefully described by adding the appropriate AnnotationElement or AnnotationAttribute to a modelelement.For instance annotations, this is different, because it must be possible to add differentannotation values for every entity or every entity property, respectively. Therefore, if instanceannotations are relevant for instances of some entity type, the structure of the entity typegets extended by properties specifically added for the purpose of holding annotation values inthe result entities. These extra properties are also annotated with sap:is-annotation=”true” to
identify them asannotation holders and separate them from the other properties of the entity type.A single entitycan have multiple instance annotations, for each of which an extra property gets added to theunderlying type:
• Zero or more for the entity itself.• Zero or more for every property contained in the entity.
Properties representing instance annotations are always introduced by AnnotationAttributes inthe metadata document. The following sections describe the possible occurrences.Example:
Query Option searchModern user interfaces typically feature a search box for entering a free-text search term, andhow exactly this search term is used to find "matching" things is up to the application. Thecustom query option search is intended exactly for passing such a free-text search term to thebackend and let the backend decide against which properties of each entity in the entity setthe term is matched, and how. It may also be matched against properties of related entities,e.g. GET ~/Orders?search=blue to find all orders with items that refer to a blue product. Service
8/19/2019 DOC-44986 (1)
20/20
SAP Annotations for OData Version 2.0
implementations using SAP NetWeaver Gateway OData Channel will receive the search termin the parameter IV_SEARCH_STRING of method GET_ENTITYSET, see http://help.sap.com/saphelp_gateway20sp06/helpdata/en/7b/7ea4676342455c99072ce8815f799d/frameset.htmfor details. Note that search works similar to $filter: it will return a subset of the entities that arereturned when no search term is specified. And it combines with $filter, returning only entities thatfulfill both conditions.
http://help.sap.com/saphelp_gateway20sp06/helpdata/en/7b/7ea4676342455c99072ce8815f799d/frameset.htmhttp://help.sap.com/saphelp_gateway20sp06/helpdata/en/7b/7ea4676342455c99072ce8815f799d/frameset.htm