Show TOC

Meta Model for OData V2Locate this document in the navigation structure

The implementation sap.ui.model.odata.ODataMetaModel offers a unified access to both OData Version 2.0 metadata and Version 4.0 annotations.

It uses the existing sap.ui.model.odata.ODataMetadata as a foundation and merges the OData Version 4.0 annotations from the existing sap.ui.model.odata.ODataAnnotations directly into the corresponding entity or property.

You can get an instance of sap.ui.model.odata.ODataMetaModel from an instance of sap.ui.model.odata.v2.ODataModel, see XML Templating.

Basic Structure

The basic structure of sap.ui.model.odata.ODataMetadata is shown in the following code snippet. It shows you how the most important elements of the entity model are nested. Each of these elements (except association set end) can have extensions, that is, XML attribute values from some namespace. The code snippets below show how these extensions are stored and processed.

"dataServices": {
    "schema": [{
      "association": [{
        "end": []
      }],
      "complexType": [{
        "property": []
      }],
      "entityContainer": [{
        "associationSet": [{
          "end": []
        }],
        "entitySet": [],
        "functionImport": [{
          "parameter": []
        }]
      }],
      "entityType": [{
        "property": [],
        "navigationProperty": []
      }]
    }]
  }
}

The following code snippet gives a closer look and has more properties:

{
  "version": "1.0",
  "dataServices": {
    "dataServiceVersion": "2.0",
    "schema": [{
      "namespace": "GWSAMPLE_BASIC",
      "entityType": [{
        "name": "BusinessPartner",
        "key": {
          "propertyRef": [{
            "name": "BusinessPartnerID"
          }]
        },
        "property": [{
          "name": "BusinessPartnerID",
          "type": "Edm.String",
          "nullable": "false",
          "maxLength": "10"
        }],
        "navigationProperty": [{
          "name": "ToSalesOrders",
          "relationship": "GWSAMPLE_BASIC.Assoc_BusinessPartner_SalesOrders",
          "fromRole": "FromRole_Assoc_BusinessPartner_SalesOrders",
          "toRole": "ToRole_Assoc_BusinessPartner_SalesOrders"
        }]
      }],
      "complexType": [{
        "name": "CT_Address",
        "property": [{
          "name": "City",
          "type": "Edm.String",
          "maxLength": "40"
        }]
      }],
      "association": [{
        "name": "Assoc_BusinessPartner_SalesOrders",
        "end": [{
          "type": "GWSAMPLE_BASIC.BusinessPartner",
          "multiplicity": "1",
          "role": "FromRole_Assoc_BusinessPartner_SalesOrders"
        }, {
          "type": "GWSAMPLE_BASIC.SalesOrder",
          "multiplicity": "*",
          "role": "ToRole_Assoc_BusinessPartner_SalesOrders"
        }],
        "referentialConstraint": {
          "principal": {
            "role": "FromRole_Assoc_BusinessPartner_SalesOrders",
            "propertyRef": [{
              "name": "BusinessPartnerID"
            }]
          },
          "dependent": {
            "role": "ToRole_Assoc_BusinessPartner_SalesOrders",
            "propertyRef": [{
              "name": "CustomerID"
            }]
          }
        }
      }],
      "entityContainer": [{
        "name": "GWSAMPLE_BASIC_Entities", 
        "isDefaultEntityContainer": "true",
        "entitySet": [{
          "name": "BusinessPartnerSet",
          "entityType": "GWSAMPLE_BASIC.BusinessPartner"
        }],
        "associationSet": [{
          "name": "Assoc_BusinessPartner_SalesOrders_AssocS",
          "association": "GWSAMPLE_BASIC.Assoc_BusinessPartner_SalesOrders",
          "end": [{
            "entitySet": "BusinessPartnerSet",
            "role": "FromRole_Assoc_BusinessPartner_SalesOrders"
          }, {
            "entitySet": "SalesOrderSet",
            "role": "ToRole_Assoc_BusinessPartner_SalesOrders"
          }]
        }],
        "functionImport": [{
          "name": "SalesOrder_Confirm",
          "returnType": "GWSAMPLE_BASIC.SalesOrder",
          "entitySet": "SalesOrderSet",
          "httpMethod": "POST",
          "parameter": [{
            "name": "SalesOrderID",
            "type": "Edm.String",
            "mode": "In",
            "maxLength": "10"
          }]
        }]
      }]
    }]
  }}
Accessing Objects and Properties

The objects in the OData meta model are arranged in arrays. /dataServices/schema, for example, is an array of schemas where each schema has an entityType property with an array of entity types, and so on. So, /dataServices/schema/0/entityType/16 can be the path to the entity type with name "Order" in the schema with namespace "MySchema".

However, these paths are not stable: If an entity type with lower index is removed from the schema, the path to "Order" changes to /dataServices/schema/0/entityType/15. To avoid problems with changing indexes, getObject and getProperty support XPath-like queries for the indexes. Each index can be replaced by a query in square brackets. You can, for example, address the schema by using the path /dataServices/schema/[${namespace}==='MySchema'] or address the entity by using the path /dataServices/schema/[${namespace}==='MySchema']/entityType/[${name}==='Order'].

The syntax inside the square brackets corresponds to the expression binding syntax. The query is executed for each object in the array until the result is true (truthy) for the first time. This object is then chosen. To embed such a path into an expression binding, use a complex binding syntax: ${path:'...'}. Example: {:= ${path:'target>extensions/[${name} === \'semantics\']/value'} === 'email'}

Each of these queries is self-contained. The query can refer to properties of the current candidate via a relative path, for example ${name}, but it cannot refer to variables such as ${meta>} that are available in XML templating at that point.

Extensions

Extensions are stored as an array of objects, each with a namespace, a name, and a value. Annotations from the "http://www.sap.com/Protocols/SAPData" namespace are lifted up from the extensions array and transformed from objects into simple properties with an sap: prefix added to their name, see line number 8 in the following code snippet.

Note

As this happens in addition, the following example shows both representations. By this, the respective annotations can be addressed via a simple relative path instead of searching an array.

1  {
2    "name": "BusinessPartnerID",
3    "extensions": [{
4      "name": "label",
5      "value": "Bus. Part. ID",
6      "namespace": "http://www.sap.com/Protocols/SAPData"
7    }],
8    "sap:label": "Bus. Part. ID"
9  }
OData v4 Annotations

Each element of the entity model (except association set end) can be annotated. These annotations from the existing sap.ui.model.odata.ODataAnnotations are merged directly into the corresponding element. The following code snippet shows how the structure from the existing sap.ui.model.odata.ODataMetadata, as explained above and including extensions and constraints such as nullable or maxLength, is fleshed out with lifted v2 annotations and inlined v4 annotations, such as Org.OData.Measures.V1.Unit or com.sap.vocabularies.UI.v1.Identification. If you want to navigate the structure, for example for XML templating, it is important to understand this structure.

ODataMetaModel JSON Format:

"dataServices" : {
    "schema" : [{
        "namespace" : "GWSAMPLE_BASIC",
        "entityType" : [{
            "name" : "Product",
            "property" : [{
                "name" : "ProductID",
                "type" : "Edm.String",
                "nullable" : "false",
                "maxLength" : "10"
            }, {
                "name" : "SupplierName",
                "type" : "Edm.String",
                "maxLength" : "80",
                "extensions" : [{
                  "name" : "label",
                  "value" : "Company Name",
                  "namespace" : "http://www.sap.com/Protocols/SAPData"
                }, {
                  "name" : "creatable",
                  "value" : "false",
                  "namespace" : "http://www.sap.com/Protocols/SAPData"
                }, {
                  "name" : "updatable",
                  "value" : "false",
                  "namespace" : "http://www.sap.com/Protocols/SAPData"
                }],
                "sap:label" : "Company Name",
                "sap:creatable" : "false",
                "sap:updatable" : "false"
                "Org.OData.Core.V1.Computed" : {
                    "Bool" : "true"
                }
            }, {
                "name" : "WeightMeasure",
                "type" : "Edm.Decimal",
                "precision" : "13",
                "scale" : "3",
                "Org.OData.Measures.V1.Unit" : {
                    "Path" : "WeightUnit"
                }
            }, {
                "name" : "WeightUnit",
                "type" : "Edm.String",
                "maxLength" : "3"
            }],
            "com.sap.vocabularies.UI.v1.DataPoint" : {
                "Value" : {
                    "Path" : "WeightMeasure",
                    "EdmType" : "Edm.Decimal"
                }
            },
            "com.sap.vocabularies.UI.v1.Identification" : [{
                "Value" : {"Path" : "ProductID"}
            }, {
                "Value" : {"Path" : "SupplierName"}
            }, {
                "Value" : {"Path" : "WeightMeasure"}
            }]
        }]
    }]
}
Enhancement of the OData Meta Model

In addition to the easy access to the SAP-specific OData annotations, such as sap:label, corresponding vocabulary-based annotations are mixed in if they are not yet defined in the OData Version 4.0 annotations of the existing sap.ui.model.odata.ODataAnnotations. The following tables show the transformations that are implemented. In the examples shown below, AnyPath is a path expression as defined in the OData Version 4.0 specificationInformation published on non-SAP site, section 14.5.12.

Transformations defined at EntitySet:

OData V2 SAP Extension

Resulting OData V4 Annotation

 
sap:creatable = "false"

"Org.OData.Capabilities.V1.InsertRestrictions": { "Insertable" : { "Bool" : "false" } }

sap:deletable = "false"

"Org.OData.Capabilities.V1.DeleteRestrictions": { "Deletable" : { "Bool" : "false" } }

sap:deletable-path = "AnyPath"

Where AnyPath is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be deleted or not.

 
"Org.OData.Capabilities.V1.DeleteRestrictions": { "Deletable" : { "Path" : "AnyPath" } }
 
sap:label = "foo"

Where foo is any text.

 
"com.sap.vocabularies.Common.v1.Label": {"String" : "foo" }
 
sap:pageable = "false"

"Org.OData.Capabilities.V1.SkipSupported": {"Bool" : "false" },
"Org.OData.Capabilities.V1.TopSupported": {"Bool" : "false" }

sap:requires-filter = "true"

"Org.OData.Capabilities.V1.FilterRestrictions": { "RequiresFilter" : { "Bool" : "true" } }

sap:searchable = "false"

Alternatively, do not use the sap:searchable annotation.

 
"Org.OData.Capabilities.V1.SearchRestrictions": { "Searchable" : { "Bool" : "false" } }

sap:topable = "false"

"Org.OData.Capabilities.V1.TopSupported": {"Bool" : "false" }

sap:updatable = "false"

"Org.OData.Capabilities.V1.UpdateRestrictions": { "Updatable" : { "Bool" : "false" } }

sap:updatable-path = "AnyPath"

Where AnyPath is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be updated or not.

 
"Org.OData.Capabilities.V1.UpdateRestrictions": { "Updatable" : { "Path" : "AnyPath" } }

Transformations defined at Property:

OData V2 SAP Extension

Resulting OData V4 Annotation

 
sap:label = "foo"

Where foo is any text.

 
"com.sap.vocabularies.Common.v1.Label": {"String" : "foo" }
Note

The resulting annotation is added at different places, not to the Property.

 
sap:creatable = "true"

and

sap:updatable = "false"
 
"Org.OData.Core.V1.Immutable": { "Bool" : "true" }

sap:creatable = "false"

and

sap:updatable = "false"
 
"Org.OData.Core.V1.Computed": { "Bool" : "true"}

sap:display-format = "NonNegative"
Note

NonNegative indicates that only non-negative numeric values are provided and persisted, other input leads to errors; intended for Edm.String fields that are internally stored as NUMC.

 
"com.sap.vocabularies.Common.v1.IsDigitSequence": { "Bool" : "true" }
 
sap:display-format = "UpperCase"

 
"com.sap.vocabularies.Common.v1.IsUpperCase": { "Bool" : "true" }
 
sap:field-control = "AnyPath"

Where AnyPath is a path expression that identifies a property containing a numeric value that controls visibility..

 
"com.sap.vocabularies.Common.v1.FieldControl": { "Path" : "AnyPath" }

sap:filterable = "false"
 
"Org.OData.Capabilities.V1.FilterRestrictions":
{ "NonFilterableProperties" : [
{ "PropertyPath" : "PropA " },
{ "PropertyPath" : "PropC " }] }

For example, if sap:filterable is set to false for properties PropA and PropC.

Note

The resulting annotation is added to the EntitySet, not to the Property.

 
sap:filter-restriction="multi-value"

For example, at a BusinessPartnerID property of a BusinessPartner type.

 
"com.sap.vocabularies.Common.v1.FilterExpressionRestrictions":
[{ "Property" : { "PropertyPath" : "BusinessPartnerID" },
"AllowedExpressions" : { "EnumMember":
"com.sap.vocabularies.Common.v1.FilterExpressionType/MultiValue" } }]

At the corresponding entity set, for example, BusinessPartnerSet.multi-value is mapped to MultiValue, single-value is mapped to SingleValue, and interval is mapped to SingleInterval.

Note

The resulting annotation is added to the EntitySet, not to the Property.

 
sap:heading = "foo"

Where foo is any text.

 
"com.sap.vocabularies.Common.v1.Heading": { "String" : "foo" }
 
sap:precision = "AnyPath"

Where AnyPath is a path expression that identifies a property in the context of the entity type containing the number of significant decimal places for a numeric value.

 
"Org.OData.Measures.V1.Scale": { "Path" : "AnyPath" }

sap:quickinfo = "foo"

Where foo is any text.

 
"com.sap.vocabularies.Common.v1.QuickInfo": { "String" : "foo" }
 
sap:required-in-filter = "true"

If sap:required-in-filter is set to TRUE for the PropA and PropC properties:

"Org.OData.Capabilities.V1.FilterRestrictions": {
"RequiredProperties" : [
{ "PropertyPath" : "PropA " },
 { "PropertyPath" : "PropC " }] }
Note

The resulting annotation is added to the EntitySet, not to the Property.

 
sap:sortable = "false"

If sap:sortable is set to FALSE for the PropA and PropC properties:

"Org.OData.Capabilities.V1.SortRestrictions": {
"NonSortableProperties" : [ 
{ "PropertyPath" : "PropA " }, 
{ "PropertyPath" : "PropC " }]}
Note

The resulting annotation is added to the EntitySet, not to the Property.

 
sap:text = "AnyPath"

Where AnyPath is a path expression that identifies a property in the context of the entity type containing a human-readable text for the value of this property.

 
"com.sap.vocabularies.Common.v1.Text":{ "Path" : "AnyPath" }

sap:unit="WeightUnit"

or

sap:unit="CurrencyCode"

Where WeightUnit and CurrencyCode are names of properties in the same entity and WeightUnit points to a property with sap-semantics:unit-of-measure and CurrencyCodepoints to a property with sap-semantics:currency-code.

 
"Org.OData.Measures.V1.Unit": { "Path" : "WeightUnit" }

or

"Org.OData.Measures.V1.ISOCurrency": { "Path" : "CurrencyCode" }

sap:visible="false"
 
"com.sap.vocabularies.Common.v1.FieldControl": { "EnumMember" :
"com.sap.vocabularies.Common.v1.FieldControlType/Hidden" }

Depending on the value of the sap:semantics annotation, different vocabulary-based annotations are generated. The following transformations are implemented and defined at property. In the examples of the resulting JSON at the "defined at" object, PROPERTY is a placeholder for the name of the property at which the sap:semantics annotation is defined.

OData V2 SAP Extension

Resulting OData V4 Annotation

 
sap:semantics = "currency-code"

see sap:unit above

 
sap:semantics = "unit-of-measure"

see sap:unit above

 
sap:semantics = name
 
"com.sap.vocabularies.Communication.v1.Contact" : { "fn" : { "Path" : "PROPERTY" } }
 
sap:semantics = givenname
 
"com.sap.vocabularies.Communication.v1.Contact" : { "n" : { "given" : { "Path" : "PROPERTY" } } }
 
sap:semantics = middlename
 
"com.sap.vocabularies.Communication.v1.Contact" : { "n" : { "additional" : { "Path" : "PROPERTY" } } }
 
sap:semantics = familyname
 
"com.sap.vocabularies.Communication.v1.Contact" : { "n" : { "surname" : { "Path" : "PROPERTY" } } }
 
sap:semantics = nickname
 
"com.sap.vocabularies.Communication.v1.Contact" : { "nickname" : { "Path" : "PROPERTY" } }
 
sap:semantics = honorific
 
"com.sap.vocabularies.Communication.v1.Contact" : { "n" : { "prefix" : { "Path" : "PROPERTY" } } }
 
sap:semantics = suffix
 
"com.sap.vocabularies.Communication.v1.Contact" : { "n" : { "suffix" : { "Path" : "PROPERTY" } } }
 
sap:semantics = note
 
"com.sap.vocabularies.Communication.v1.Contact" : { "note" : { "Path" : "PROPERTY" } }
 
sap:semantics = photo
 
"com.sap.vocabularies.Communication.v1.Contact" : { "photo" : { "Path" : "PROPERTY" } }
 
sap:semantics = city
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "locality" : { "Path" : "PROPERTY" } } }
 
sap:semantics = street
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "street" : { "Path" : "PROPERTY" } } }
 
sap:semantics = country
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "country" : { "Path" : "PROPERTY" } } }
 
sap:semantics = region
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "region" : { "Path" : "PROPERTY" } } }
 
sap:semantics = zip
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "code" : { "Path" : "PROPERTY" } } }
 
sap:semantics = pobox
 
"com.sap.vocabularies.Communication.v1.Contact" : { "adr" : { "pobox" : { "Path" : "PROPERTY" } } }
 
sap:semantics = org
 
"com.sap.vocabularies.Communication.v1.Contact" : { "org" : { "Path" : "PROPERTY" } }
 
sap:semantics = org-unit
 
"com.sap.vocabularies.Communication.v1.Contact" : { "orgunit" : { "Path" : "PROPERTY" } }
 
sap:semantics = org-role
 
"com.sap.vocabularies.Communication.v1.Contact" : { "role" : { "Path" : "PROPERTY" } }
 
sap:semantics = title
 
"com.sap.vocabularies.Communication.v1.Contact" : { "title" : { "Path" : "PROPERTY" } }
 
sap:semantics = bday
 
"com.sap.vocabularies.Communication.v1.Contact" : { "bday" : { "Path" : "PROPERTY" } }
 
sap:semantics = dtstart
 
"com.sap.vocabularies.Communication.v1.Event" : { "dtstart" : { "Path" : "PROPERTY" } }
 
sap:semantics = dtend
 
"com.sap.vocabularies.Communication.v1.Event" : { "dtend" : { "Path" : "PROPERTY" } }
 
sap:semantics = class
 
"com.sap.vocabularies.Communication.v1.Event" : { "class" : { "Path" : "PROPERTY" } }
 
sap:semantics = status
 
"com.sap.vocabularies.Communication.v1.Event" : { "status" : { "Path" : "PROPERTY" } }
 
sap:semantics = transp
 
"com.sap.vocabularies.Communication.v1.Event" : { "transp" : { "Path" : "PROPERTY" } }
 
sap:semantics = fbtype
 
"com.sap.vocabularies.Communication.v1.Event" : { "fbtype" : { "Path" : "PROPERTY" } }
 
sap:semantics = wholeday
 
"com.sap.vocabularies.Communication.v1.Event" : { "wholeday" : { "Path" : "PROPERTY" } }
 
sap:semantics = location
 
"com.sap.vocabularies.Communication.v1.Event" : { "location" : { "Path" : "PROPERTY" } }
 
sap:semantics = due
 
"com.sap.vocabularies.Communication.v1.Task" : { "due" : { "Path" : "PROPERTY" } }
 
sap:semantics = completed
 
"com.sap.vocabularies.Communication.v1.Task" : { "completed" : { "Path" : "PROPERTY" } }
 
sap:semantics = percent-complete
 
"com.sap.vocabularies.Communication.v1.Task" : { "percentcomplete" : { "Path" : "PROPERTY" } }
 
sap:semantics = priority
 
"com.sap.vocabularies.Communication.v1.Task" : { "priority" : { "Path" : "PROPERTY" } }
 
sap:semantics = from
 
"com.sap.vocabularies.Communication.v1.Message" : { "from" : { "Path" : "PROPERTY" } }
 
sap:semantics = sender
 
"com.sap.vocabularies.Communication.v1.Message" : { "sender" : { "Path" : "PROPERTY" } }
 
sap:semantics = subject
 
"com.sap.vocabularies.Communication.v1.Message" : { "subject" : { "Path" : "PROPERTY" } }
 
sap:semantics = body
 
"com.sap.vocabularies.Communication.v1.Message" : { "body" : { "Path" : "PROPERTY" } }
 
sap:semantics = received
 
"com.sap.vocabularies.Communication.v1.Message" : { "received" : { "Path" : "PROPERTY" } }
 
sap:semantics = tel

At the EntityType or ComplexType:

"com.sap.vocabularies.Communication.v1.Contact" : { 
"tel" : [{
"uri" : { "Path" : "ATTRIBUTE" }
}]}

Where ATTRIBUTE is the name of the annotated attribute of an EntityType or ComplexType.

At Property:

"com.sap.vocabularies.Communication.v1.IsPhoneNumber" : { "Bool" : "true" }
 
sap:semantics = tel;type=cell,work

At the EntityType or ComplexType:

"com.sap.vocabularies.Communication.v1.Contact" : { 
"tel" : [{
"type" : {
"EnumMember": "com.sap.vocabularies.Communication.v1.PhoneType/cell"
+ " com.sap.vocabularies.Communication.v1.PhoneType/work"
},
"uri" : { "Path" : "ATTRIBUTE" }
}]}

Where ATTRIBUTE is the name of the annotated attribute of an EntityType or ComplexType.

At Property:

"com.sap.vocabularies.Communication.v1.IsPhoneNumber" : { "Bool" : "true" }
 
sap:semantics = email

At the EntityType or ComplexType:

"com.sap.vocabularies.Communication.v1.Contact" : { 
"address" : [{
"uri" : { "Path" : "ATTRIBUTE" }
}]}

Where ATTRIBUTE is the name of the annotated attribute of an EntityType or ComplexType.

At Property:

"com.sap.vocabularies.Communication.v1.IsEmailAddress" : { "Bool" : "true" }
 
sap:semantics = email;type=work,pref

At the EntityType or ComplexType:

"com.sap.vocabularies.Communication.v1.Contact" : { 
"email" : [{
"address" : { "Path" : "ATTRIBUTE" },
"type" : {
"EnumMember" : "com.sap.vocabularies.Communication.v1.ContactInformationType/work"
+ "com.sap.vocabularies.Communication.v1.ContactInformationType/preferred"
}
}]}

Where ATTRIBUTE is the name of the annotated attribute of an EntityType or ComplexType.

At Property:

"com.sap.vocabularies.Communication.v1.IsEmailAddress" : { "Bool" : "true" }
Related Information