OASIS OData Version 1.0. Part 3: CSDL
OASIS OData Version 1.0 Part 3: CSDL
Working Draft 01
073 December 2012
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Barbara Hartel (barbara.hartel@), SAP AG
Ram Jeyaraman (Ram.Jeyaraman@), Microsoft
Editor:
Mike Pizzo (mikep@), Microsoft
Ralf Handl (ralf.handl@), SAP AG
Susan Malaika (malaika@us.), IBM
Christopher Woodruff (chris.woodruff@), Perficient, Inc
Martin Zurmuehl (martin.zurmuehl@), SAP AG
Additional artifacts:
This prose specification is one component of a Work Product which also includes:
XML schemas:
o
o
Other parts (list titles and/or file names)
o
Related work:
This specification replaces or supersedes:
Specifications replaced by this specification (hyperlink, if available)
This specification is related to:
Related specifications (hyperlink, if available)
Declared XML namespaces:
Abstract:
OData services are described by an Entity Data Model (EDM). The Common Schema Definition Language (CSDL) defines an XML representation of the entity data model exposed by an OData service.
Status:
This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.
Copyright © OASIS Open 2012. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Table of Contents
1 Introduction 8
1.1 Terminology 8
1.2 Normative References 8
1.3 Non-Normative References 8
2 Common Schema Definition Language (CSDL) Namespaces 9
2.1 Entity Data Model for Data Services Packaging (EDMX) Namespace 9
2.2 Entity Data Model (EDM) Namespace 9
3 Common Characteristics of Entity Models 10
3.1 Nominal Types 10
3.2 Structural Types 10
3.3 The edm:Documentation Element 10
3.4 Vocabulary Annotations 12
3.5 Primitive Types 12
4 Entity Model Wrapper Constructs 14
4.1 The edmx:Edmx Element 14
4.1.1 The Version Attribute 14
4.2 The edmx:DataServices Element 14
4.2.1 The DataServiceVersion Attribute 14
4.3 The edmx:Reference Element 14
4.3.1 The Url Attribute 15
4.4 The edmx:AnnotationsReference Element 15
4.4.1 The Url Attribute 15
4.5 The edmx:Include Element 15
4.5.1 The TermNamespace Attribute 16
4.5.2 The Qualifier Attribute 16
5 Schema Constructs 17
5.1 The edm:Schema Element 17
5.1.1 The Namespace Attribute 17
5.1.2 The Alias Attribute 17
5.2 The edm:Using Element 18
5.2.1 The Namespace Attribute 18
5.2.2 The Alias Attribute 18
6 Properties 19
6.1 The edm:Property Element 19
6.1.1 The Name Attribute 19
6.1.2 The Type Attribute 19
6.2 Property Facets 19
6.2.1 The Nullable Attribute 20
6.2.2 The MaxLength Attribute 20
6.2.3 The FixedLength Attribute 20
6.2.4 The Precision Attribute 20
6.2.5 The Scale Attribute 20
6.2.6 The Unicode Attribute 20
6.2.7 The Collation Attribute 20
6.2.8 The SRID Attribute 21
6.2.9 The DefaultValue Attribute 21
6.2.10 The ConcurrencyMode Attribute 21
7 Entity Type Constructs 22
7.1 The edm:EntityType Element 22
7.1.1 The Name Attribute 22
7.1.2 The BaseType Attribute 22
7.1.3 The Abstract Attribute 23
7.1.4 The OpenType Attribute 23
7.1.5 The HasStream Attribute 23
7.2 The edm:Key Element 23
7.2.1 The edm:PropertyRef Element 24
7.3 The edm:NavigationProperty Element 24
7.3.1 The Name Attribute 24
7.3.2 The Type Attribute 24
7.3.3 The Nullable Attribute 24
7.3.4 The Partner Attribute 25
7.3.5 The ContainsTarget Attribute 25
7.3.6 The edm:ReferentialConstraint Element 25
7.3.7 The edm:PropertyRef Element 25
7.3.8 The edm:OnDelete Element 26
8 Complex Type Constructs 27
8.1 The edm:ComplexType Element 27
8.1.1 The BaseType Attribute 27
8.1.2 The Abstract Attribute 27
9 Enumeration Type Constructs 28
9.1 The edm:EnumType Element 28
9.1.1 The UnderlyingType Attribute 28
9.1.2 The IsFlags Attribute 28
9.2 The edm:Member Element 28
9.2.1 The Name Attribute 28
9.2.2 The Value Attribute 29
10 Other Type Constructs 30
10.1 Collection Types 30
10.2 The edm:CollectionType Element 30
10.2.1 The ElementType Attribute 30
10.3 The edm:TypeRef Element 30
10.3.1 The Type Attribute 30
10.4 Reference Types 30
10.4.1 The edm:ReferenceType Element 31
10.4.1.1 The Type Attribute 31
10.5 Type Definitions 31
10.5.1 The Name Attribute 31
10.5.2 The UnderlyingType Attribute 31
10.5.3 TypeDefinition Facets 31
11 Entity Container Constructs 33
11.1 The edm:EntityContainer Element 34
11.1.1 The Name Attribute 34
11.1.2 The IsDefaultEntityContainer Attribute 34
11.1.3 The Extends Attribute 34
11.2 The edm:EntitySet Element 34
11.2.1 The Name Attribute 34
11.2.2 The EntityType Attribute 34
11.3 The edm:NavigationPropertyBinding Element 34
11.3.1 The Path Attribute 34
11.3.2 The EntitySet Attribute 35
11.4 The edm:Entity Element 35
11.4.1 The Name Attribute 35
11.4.2 The Type Attribute 35
11.5 The edm:FunctionImport Element 35
11.5.1 The ReturnType Attribute 35
11.5.2 The EntitySet Attribute 36
11.5.3 The EntitySetPath Attribute 36
11.5.4 The IsSideEffecting Attribute 36
11.5.5 The IsBindable Attribute 36
11.5.6 The IsComposable Attribute 36
11.6 The edm:ReturnType Element 36
11.6.1 The Type Attribute 37
11.7 The edm:Parameter Element 37
11.7.1 The Type Attribute 37
11.7.2 Parameter Facets 37
12 Vocabulary Concepts 38
13 Vocabulary Terms 39
13.1 edm:EntityType and edm:ComplexType as Type Terms 39
13.2 The edm:ValueTerm Element 39
13.2.1 The Name Attribute 39
13.2.2 The Type Attribute 39
13.2.3 The DefaultValue Attribute 39
14 Vocabulary Annotations 40
14.1 The edm:Annotations Element 40
14.2 The edm:TypeAnnotation Element 40
14.3 The edm:PropertyValue Element 40
14.4 The edm:ValueAnnotation Element 41
14.5 The Qualifier Attribute 41
15 Vocabulary Expressions 42
15.1 Constant Expressions 42
15.1.1 The edm:Binary Constant Expression 42
15.1.2 The edm:Bool Constant Expression 42
15.1.3 The edm:DateTime Constant Expression 43
15.1.4 The edm:DateTimeOffset Constant Expression 43
15.1.5 The edm:Decimal Constant Expression 43
15.1.6 The edm:Float Constant Expression 43
15.1.7 The edm:Guid Constant Expression 44
15.1.8 The edm:Int Constant Expression 44
15.1.9 The edm:String Constant Expression 44
15.1.10 The edm:Time Constant Expression 44
15.2 Dynamic Expressions 45
15.2.1 The edm:Apply Expression 45
15.2.2 The edm:AssertType Expression 45
15.2.3 The edm:Collection Expression 45
15.2.4 The edm:EntitySetReference Expression 46
15.2.5 The edm:EnumMemberReference Expression 46
15.2.6 The edm:FunctionReference Expression 46
15.2.7 The edm:If Expression 46
15.2.8 The edm:IsType Expression 47
15.2.9 The edm:LabeledElement Expression 47
15.2.10 The edm:LabeledElementReference Expression 47
15.2.11 The edm:Null Expression 48
15.2.12 The edm:ParameterReference Expression 48
15.2.13 The edm:Path Expression 48
15.2.14 The edm:PropertyReference Expression 49
15.2.15 The edm:Record Expression 49
15.2.16 The edm:ValueTermReference Expression 49
16 CSDL Examples 50
16.1 Products and Categories Example 50
16.2 Annotated Customers and Orders Example 51
17 Informative XSD for CSDL 53
18 Attribute Values 54
18.1 Namespace 54
18.2 SimpleIdentifier 54
18.3 QualifiedName 54
18.4 AnyTypeName 54
18.5 AnySingleTypeName 54
18.6 AnyKeylessTypeName 54
18.7 SingleEntityTypeName 54
18.8 SingleComplexTypeName 54
18.9 Boolean 54
19 Conformance 55
Appendix A. Acknowledgments 56
Appendix B. Non-Normative Text 57
B.1 Subsidiary section 57
B.1.1 Sub-subsidiary section 57
Appendix C. Revision History 58
Introduction
OData services are described in terms of an Entity Data Model (EDM). The Common Schema Definition Language (CSDL) defines an XML representation of the entity data model exposed by an OData service. CSDL is articulated in the Extensible Markup Language (XML) 1.1 (Second Edition) [XML-1.1] with further building blocks from the W3C XML Schema Definition Language (XSD) 1.1 as described in [XML-Schema-1] and [XML-Schema-2].
If a client requests a description of the entity model by sending a GET request to /$metadata, an OData service SHOULD provide a CSDL description of its entity model.
1 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
2 Normative References
[EPSG] European Petroleum Survey Group (EPSG). .
[OData-ABNF] OData ABNF Construction Rules Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. .
[OData-Atom] OData ATOM Format Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. .
[OData-Core] OData Protocol Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. .
[OData-JSON] OData JSON Format Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. .
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. .
[XML-1.1] Bray, T. et al., “Extensible Markup Language (XML) 1.1 (Second Edition)”, W3C Recommendation, 16 August 2006. .
[XML-Schema-1] Gao, S. et al., “W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures”, W3C Recommendation, 5 April 2012. .
[XML-Schema-2] Peterson, D. et al., “W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes”, W3C Recommendation, 5 April 2012. .
3 Non-Normative References
[Entity SQL]
Common Schema Definition Language (CSDL) Namespaces
In addition to the default XML namespace, the elements and attributes used to describe the entity model of an OData service are defined in one of the following namespaces.
1 Entity Data Model for Data Services Packaging (EDMX) Namespace
Elements and attributes associated with the top-level wrapper that contains the CSDL used to define the entity model for an OData Service are qualified with the Entity Data Model for Data Services Packaging namespace:
•
Prior versions of OData used the following namespace for EDMX:
• EDMX version 1.0:
They are non-normative for this specification.
In this specification the namespace prefix edmx is used to represent the Entity Data Model for Data Services Packaging namespace, however the prefix name is not prescriptive.
2 Entity Data Model (EDM) Namespace
Elements and attributes that define the entity model exposed by the OData Service are qualified with the Entity Data Model namespace:
•
Prior versions of CSDL used the following namespaces for EDM:
• CSDL version 1.0:
• CSDL version 1.1:
• CSDL version 1.2:
• CSDL version 2.0:
• CSDL version 3.0:
They are non-normative for this specification.
In this specification the namespace prefix edm is used to represent the Entity Data Model namespace, however the prefix name is not prescriptive.
Common Characteristics of Entity Models
A typical entity model for an OData service contains one or more model elements. Some of these elements share a few common characteristics.
1 Nominal Types
A nominal type has a name. The name MUST be a SimpleIdentifier. In combination with a Namespace this produces a fully qualified name of the form QualifiedName. The QualifiedName MUST be unique as it facilitates references to the element from other parts of the model.
When referring to nominal types, the reference MUST use one of the following:
• Fully qualified name
• Alias qualified name
Consider the following example:
...
The various ways of referring to the nominal type are:
• References in any namespace can use the fully qualified name, for example, org.example.Address
• References in any namespace can specify an alias and use an alias qualified name, for example, example.Address
2 Structural Types
Structural types are composed of other model elements. Structural types are common in entity models as they are the typical means of representing entities in the OData service. Entity types and complex types are both structural types. Row types are less common but are also structural types.
A structural property is a property that has one of the following types:
• Primitive
• Complex type
• Enumeration type
• A collection of one of the above
3 The edm:Documentation Element
The edm:Documentation element allows service authors to provide documentation for most model elements.
A model element MUST NOT contain more than one documentation element.
The following model elements MAY contain a documentation element:
• edm:Apply
• edm:AssertType
• edm:Collection
• edm:ComplexType
• edm:Entity
• edm:EntityContainer
• edm:EntitySet
• edm:EntityType
• edm:EnumType
• edm:FunctionImport
• edm:FunctionReference
• edm:If
• edm:IsType
• edm:LabeledElement
• edm:Member
• edm:NavigationProperty
• edm:Null
• edm:OnDelete
• edm:Parameter
• edm:Property
• edm:PropertyReference
• edm:PropertyValue
• edm:Record
• edm:ReferenceType
• edm:ReferentialConstraint
• edm:Schema
• edm:TypeAnnotation
• edm:TypeRef
• edm:Using
• edm:ValueAnnotation
• edm:ValueTerm
A documentation element MUST contain zero or one edm:Summary and zero or one edm:LongDescription elements. The summary and long description elements MAY contain text that serves as the summary or long description. If both a summary and long description are provided, the summary MUST precede the long description.
For example:
Product names, suppliers, prices, and units in stock.
...
...
4 Vocabulary Annotations
Many parts of the model can be annotated with additional information with the edm:TypeAnnotation and edm:ValueAnnotation elements.
A model element MUST NOT specify more than one type annotation or value annotation for a given value combination of the Term and Qualifier attributes.
Vocabulary annotations may be specified as a child of the model element or as a child of an edm:Annotations element that targets the model element.
Refer to Vocabulary Annotations for details on which model elements support vocabulary annotations.
5 Primitive Types
Structural types are composed of other structural types and primitive types. CSDL defines the following fully qualified primitive types:
|Type |Meaning |
|Edm.Binary |Fixed- or variable- length binary data |
|Edm.Boolean |Binary-valued logic |
|Edm.Byte |Unsigned 8-bit integer |
|Edm.DateTime |Date and time without a time zone offset |
|Edm.DateTimeOffset |Date and time with a time zone offset |
|Edm.Decimal |Numeric values with fixed precision and scale |
|Edm.Double |Floating-point number with 15 digits precision |
|Edm.Guid |16-byte (128-bit) unique identifier |
|Edm.Int16 |Signed 16-bit integer |
|Edm.Int32 |Signed 32-bit integer |
|Edm.Int64 |Signed 64-bit integer |
|Edm.SByte |Signed 8-bit integer |
|Edm.Single |Floating-point number with 7 digits precision |
|Edm.Stream |Fixed-length or variable-length data stream |
|Edm.String |Fixed-length or variable-length sequence of UTF-8 characters |
|Edm.Time |Clock time 0-23:59:59.9999999 |
|Edm.Geography |Abstract base type for all Geography types |
|Edm.GeographyPoint |A point in a round-earth coordinate system |
|Edm.GeographyLineString |Line string in a round-earth coordinate system |
|Edm.GeographyPolygon |Polygon in a round-earth coordinate system |
|Edm.GeographyMultiPoint |Collection of points in a round-earth coordinate system |
|Edm.GeographyMultiLineString |Collection of line strings in a round-earth coordinate system |
|Edm.GeographyMultiPolygon |Collection of polygons in a round-earth coordinate system |
|Edm.GeographyCollection |Collection of arbitrary Geography values |
|Edm.Geometry |Abstract base type for all Geometry types |
|Edm.GeometryPoint |Point in a flat-earth coordinate system |
|Edm.GeometryLineString |Line string in a flat-earth coordinate system |
|Edm.GeometryPolygon |Polygon in a flat -earth coordinate system |
|Edm.GeometryMultiPoint |Collection of points in a flat -earth coordinate system |
|Edm.GeometryMultiLineString |Collection of line strings in a flat -earth coordinate system |
|Edm.GeometryMultiPolygon |Collection of polygons in a flat -earth coordinate system |
|Edm.GeometryCollection |Collection of arbitrary Geometry values |
Some of these types allow facet attributes. These are defined in section 6.3.
See [OData-ABNF] for the representation of primitive type values in URLs, and [OData-Atom] and [OData-JSON] for the representation in requests and responses.
Entity Model Wrapper Constructs
An OData service exposes a single entity model. This model may consist of several schemas, and these schemas may be distributed over several physical locations. The entity model wrapper provides a single point of access to these parts by including them directly or referencing their physical locations. It can be accessed by sending a GET request to /$metadata.
1 The edmx:Edmx Element
The document returned by $metadata MUST contain a single root edmx:Edmx element. This element MUST contain a single direct child edmx:DataServices element. The data services element contains a description of the entity model(s) exposed by the OData service.
In addition to the data services element, Edmx may have zero or more edmx:Reference elements and zero or more edmx:AnnotationsReference elements. Reference elements specify the location of schemas referenced by the OData service. Annotations reference elements specify the location of annotations to be applied to the OData service.
The following example demonstrates the basic structure of the edmx:Edmx element and the edmx:DataServices element:
1 The Version Attribute
The Version attribute MUST be present on the edmx:Edmx element.
The Version attribute is a string value that specifies the version of the EDMX wrapper, and must be of the form .. This version of the specification defines version 1.0 of the EDMX Wrapper.
2 The edmx:DataServices Element
The edmx:DataServices element contains zero or more edm:Schema elements which define the schema(s) exposed by the OData service.
1 The DataServiceVersion Attribute
The DataServiceVersion attribute describes the version of OData protocol required to consume the service. This version of the specification defines the data service version value 4.0. The values 1.0, 2.0, and 3.0 are reserved for the OData protocol versions 1.0, 2.0 and 3.0 that are not specified by this document.
3 The edmx:Reference Element
The edmx:Reference element specifies external entity models referenced by this EDMX. Referenced models are available in their entirety to referencing models. All entity types, complex types and other named elements in a referenced model can be accessed from a referencing model.
The following example demonstrates usage of the reference element to reference entity models that contain entity types and complex types that are used as vocabulary terms:
1 The Url Attribute
The edmx:Reference element MUST specify a Url attribute. The URL attribute uniquely identifies a model. The URL may be backed by a CSDL document describing the referenced model. Alternatively, the URL may be used to load a well-known model from a different location.
4 The edmx:AnnotationsReference Element
The edmx:AnnotationsReference element specifies the location of an external document that contains annotations for this entity model. Only edm:Annotations, edm:TypeAnnotation and edm:ValueAnnotation elements will be read from the referenced model.
The annotations reference element MUST contain one or more edmx:Include elements that specify the annotations to include from the target document.
The following example demonstrates usage of the annotations reference element to reference documents that contain annotations:
All annotations from are included. For , only the following annotations are included:
• Annotations that use a term from the org.example.validation namespace
• Annotations that use a term from the org.example.display namespace and specify a Slate qualifier
1 The Url Attribute
The edmx:AnnotationsReference element MUST specify a Url attribute. The value of the URL attribute uniquely identifies a model. The URL may be backed by a CSDL document describing the referenced model. Alternatively, the URL may be used to load a well-known model from a different location.
5 The edmx:Include Element
The edmx:Include element specifies which annotations to include from an annotations reference. An include element that does not have an TermNamespace attribute or an Qualifier attribute includes all annotations within the document. If both TermNamespace and Qualifier have values, only annotations that meet both restrictions will be included.
1 The TermNamespace Attribute
An edmx:Include element MAY provide a Namespace value for the TermNamespace attribute. A term namespace is a string that disambiguates terms with the same name.
For instance, assume both org.schema and org.microformats define a term named Address. Although the terms have the same name, they are uniquely identifiable since each term is in a model with a unique namespace.
If a value is supplied, the include element will import the set of annotations that apply terms from the namespace in the value. The term namespace attribute also provides consumers insight about what namespaces are used in the annotations document. If there are no include elements that have a term namespace of interest to the consumer, the consumer can opt to not download the document.
2 The Qualifier Attribute
An edmx:Include element MAY have a value for the Qualifier attribute. A qualifier is used to apply an annotation to a subset of consumers. For instance, a service author may want to supply a different set of annotations for various device form factors.
If a value is supplied, the include element will import the set of annotations that apply the qualifier in the value. The qualifier attribute also provides consumers insight about which qualifiers are used in the annotations document. If there are no include elements that have a qualifier of interest to the consumer, the consumer can opt to not download the document.
Schema Constructs
Each entity model exposed by the OData service is described one or more schemas. The schema acts as a container for all of the entity types, complex types and other parts of the entity model.
1 The edm:Schema Element
The edm:Schema is the root of an entity model exposed by an OData service. Although an edmx:DataServices element contains zero or more Schema elements, many OData services will contain exactly one schema.
An edm:Schema element contains zero or more of the following elements:
• edm:Annotations
• edm:ComplexType
• edm:EntityContainer
• edm:EntityType
• edm:TypeDefinition
• edm:EnumType
• edm:Using
• edm:ValueTerm
Values of the Name attribute must be unique across all direct sub-elements of schema, including entity types, complex types, type definitions, enumeration types, and value terms.
In addition the edm:Schema element MAY have one edm:Documentation child element.
1 The Namespace Attribute
A schema is identified by the value of the Namespace attribute. The schema’s namespace is combined with the name of elements in the entity model to create unique names. A schema MAY span across more than one CSDL document, each of them containing an edm:Schema element with the same value for the Namespace attribute.
Identifiers that are used to name types MUST be unique within a namespace to prevent ambiguity. See Nominal Types for more detail.
A schema that contains nominal types MUST specify a Namespace value for the namespace attribute. A schema that contains only vocabulary annotations MAY specify a Namespace value for the namespace attribute. The Namespace attribute MUST NOT use the reserved values System, Transient or Edm.
2 The Alias Attribute
A schema MAY provide a SimpleIdentifier value for the Alias attribute. An alias allows a CSDL document to qualify nominal types with a short string rather than a long namespace. For instance, org.example.vocabularies.display may simply have an alias of Self. An alias qualified name is resolved to a fully qualified name by examining aliases on edm:Using and edm:Schema elements.
An alias is scoped to the container in which it is declared. For example, a model referencing an annotations document cannot use any aliases defined in that annotations document. A referencing model defines its own aliases with the edm:Using element.
2 The edm:Using Element
The edm:Using element imports the contents of a specified namespace. A using element binds an alias to the namespace of any entity model.
Importing the contents of another model with a using element may alter the importing model. For instance, a model may import an entity model containing an entity type derived from an entity type in the importing model. In that case an edm:EntitySet in the importing model may return either entity type.
1 The Namespace Attribute
The edm:Using element MUST provide a Namespace value to the Namespace attribute. The value provided to the namespace attribute SHOULD match the namespace of an entity model that is in scope.
2 The Alias Attribute
An edm:Using element MAY define a SimpleIdentifier value for the Alias attribute. An alias allows a CSDL model to substitute a short string for a long namespace. For instance, org.example.vocabularies.display may be bound to an alias of display. An alias qualified name is resolved to a fully qualified name by examining aliases on edm:Using and edm:Schema elements.
Properties
As mentioned in Structural Types, structural types are composed of other structural types and primitive types. Structural types expose a collection of zero or more edm:Property elements.
For example, the following complex type has two properties:
Open entity types allow properties to be added dynamically. When requesting the value of a missing property from an open entity type, the instance MUST return null.
1 The edm:Property Element
An edm:Property element allows the construction of structural types from a scalar value or a collection of scalar values.
For instance, the following property could be used to hold zero or more strings representing the names of measurement units:
A property MUST specify a unique name as well as a type and zero or more facets. Facets are attributes that modify or constrain the acceptable values for a property value.
1 The Name Attribute
A property MUST specify a SimpleIdentifier value for the Name attribute. The name attribute allows a name to be assigned to the property. This name is used when serializing or deserializing OData payloads and can be used for other purposes, such as code generation.
The value of the name attribute MUST be unique within the set of properties and navigation properties for the type and any of its base types.
2 The Type Attribute
A property MUST specify a value for the Type attribute. The value of this attribute determines the type for the value of the property on instances of the containing type.
The value of the type attribute MUST be of the form AnyKeylessTypeName. The value of the type attribute MUST resolve to a complex type, enumeration type or primitive type, or a collection of complex, enumeration or primitive types.
2 Property Facets
Property facets allow a model to provide additional constraints or data about the value of structural properties. Facets are expressed as attributes on the property element.
Facets apply to the type referenced in the element where the facet is declared. If the type is a collection type declared with attribute notation, the facets apply to the types in the collection. In the following example, the Nullable facet applies to the DateTime type.
In the following example the Nullable attribute MUST be placed on the child element that references the DateTime type. Facet attributes MUST NOT be applied to Collection type references.
1 The Nullable Attribute
Any edm:Property MAY define a Boolean value for the Nullable facet attribute. The value of this attribute determines whether a value is required for the property on instances of the containing type.
If no value is specified, the nullable facet defaults to true.
2 The MaxLength Attribute
A binary, stream or string edm:Property MAY define a positive integer value for the MaxLength facet attribute. The value of this attribute specifies the maximum length of the value of the property on a type instance. Instead of an integer value the constant Max MAY be specified as a shorthand for the maximum length supported by the server.
3 The FixedLength Attribute
A binary, stream or string edm:Property MAY define a positive integer value for the FixedLength facet attribute. The value of this attribute specifies the size of the array used to store the value of the property on a type instance.
4 The Precision Attribute
A temporal or decimal edm:Property MAY define a value for the Precision attribute.
For a decimal property the value of this attribute specifies the maximum number of digits allowed in the property’s value; it MUST be a positive integer. For a temporal property the value of this attribute specifies the number of decimal places allowed in the seconds portion of the property’s value; it MUST be a non-negative integer.
5 The Scale Attribute
A decimal edm:Property MAY define a non-negative integer value for the Scale attribute. The value of this attribute specifies the maximum number of digits allowed to the right of the decimal point.
The value of the Scale attribute MUST be less than or equal to the value of the Precision attribute.
6 The Unicode Attribute
A string property MAY define a Boolean value for the Unicode attribute.
A true value assigned to this attribute indicates that the value of the property is encoded with Unicode. A false value assigned to this attribute indicates that the value of the property is encoded with ASCII.
If no value is defined for this attribute, the value defaults to true.
7 The Collation Attribute
A string property MAY define a value for the Collation attribute. The value of this attribute specifies a collation sequence that can be used for comparison and ordering operations.
The value of the collation attribute MUST be one of the following:
• Binary
• Boolean
• Byte
• DateTime
• DateTimeOffset
• Time
• Decimal
• Double
• Single
• Guid
• Int16
• Int32
• Int64
• String
• SByte
8 The SRID Attribute
A spatial property MAY define a value for the SRID attribute. The value of this attribute identifies which spatial reference system is applied to values of the property on type instances.
The value of the SRID attribute MUST be a non-negative integer or the special value variable. If no value is specified, the attribute defaults to 0 for Geometry types or 4326 for Geography types.
The valid values of the SRID attribute and their meanings are as defined by the European Petroleum Survey Group [EPSG].
9 The DefaultValue Attribute
A property MAY define a value for the DefaultValue attribute. The value of this attribute determines the value of the property on new type instances.
10 The ConcurrencyMode Attribute
An edm:Property MAY define a value for the ConcurrencyMode attribute. The value of this attribute indicates how concurrency should be handled for the property.
The value of the concurrency mode attribute MUST be None or Fixed. If no value is specified, the value defaults to None.
When used on a property of an entity type, the concurrency mode attribute specifies that the value of that property SHOULD be used for optimistic concurrency checks.
The concurrency mode attribute MUST NOT be applied to any properties of a complex type.
The concurrency mode attribute MUST NOT be applied to properties whose type is a complex type.
Entity Type Constructs
Entity types are nominal structural types with a key that consists of one or more references to structural properties. An entity type by definition has an independent existence and can be created, updated or deleted independently of any other types. An entity type is the template for an entity: any uniquely identifiable record such as a customer or order.
A key MUST be supplied if and only if the entity type does not specify a base type. The key consists of one or more references to structural properties of the entity type.
An entity type can define two types of properties. A structural property is a named reference to a primitive or complex type, or a collection of primitive or complex types. A navigation property is a named reference to another entity type or collection of entity types. All properties MUST have a unique name. Properties MUST NOT have the same name as the declaring entity type.
An open entity type allows properties to be added to an instance of the type dynamically. Any request for the value of a missing property on an open entity type MUST return null.
A simple example of an entity type is as follows:
The following example shows an entity type based on the previous example:
1 The edm:EntityType Element
The edm:EntityType element represents an entity type in the entity model.
An entity type MUST contain exactly one edm:Key element or specify a value for the BaseType attribute, but not both.
If no base type is specified, the edm:EntityType element MUST contain one or more edm:Property elements describing the properties of the entity type. The entity type element also can contain zero or more edm:NavigationProperty elements.
1 The Name Attribute
A value of the form SimpleIdentifier MUST be provided for the Name attribute because an entity type is a nominal type. The value identifies the entity type and MUST be unique within the entity type’s namespace.
2 The BaseType Attribute
An entity type can inherit from another entity type by specifying a SingleEntityTypeName value for the BaseType attribute.
An entity type that provides a value for the base type attribute MUST NOT declare a key with the edm:Key element.
An entity type inherits the key as well as structural and navigation properties declared on the entity type’s base type.
An entity type MUST NOT introduce an inheritance cycle via the base type attribute.
3 The Abstract Attribute
An entity type MAY indicate that it cannot be instantiated by providing a Boolean value of true to the Abstract attribute. If not specified, the Abstract attribute defaults to false.
4 The OpenType Attribute
An entity type MAY indicate that it can be freely extended by providing a Boolean value of true to the OpenType attribute. An open entity type allows entity instances to add properties dynamically simply by adding uniquely named values to the payload.
If no value is provided for the open type attribute, the value of the open type attribute is set to false.
An entity type derived from an open entity type MUST NOT provide a value of false for the open type attribute.
Note: navigation properties may be dynamically added to instances of any entity type, without the need to mark the entity type as open. These dynamic navigation properties are exposed as links in the same way as declared navigation properties. Clients MUST always be prepared to deal with additional links in instances of any entity type.
5 The HasStream Attribute
An entity type MAY contain the HasStream attribute.
A value of true specifies that the entity type is a media entity. Media entities are entities that represent a media stream, such as a photo. For more information on Media Entities, see [OData-Core].
If no value is provided for the HasStream attribute, the value of the HasStream attribute is set to false.
2 The edm:Key Element
An entity MUST be uniquely identifiable. If an entity type does not specify a base type, the entity type MUST contain exactly one edm:Key element. An entity type’s key refers to the set of properties that uniquely identify an instance of the entity type.
If specified, the key MUST contain one or more edm:PropertyRef elements. An edm:PropertyRef element references an edm:Property. The properties that compose the key MUST be non-nullable primitives or enumeration types.
The following entity type has a simple key:
The following entity type has a composite key:
1 The edm:PropertyRef Element
The edm:PropertyRef element provides an edm:Key with a reference to a single property of an entity type. A SimpleIdentifier value MUST be supplied to the Name attribute. This value MUST resolve to one of the properties of the entity type.
3 The edm:NavigationProperty Element
A navigation property allows navigation from an entity to related entities.
In the following example, the Product entity type has a navigation property to a Category, which has a navigation link back to one or more products:
...
...
1 The Name Attribute
The navigation property MUST provide a SimpleIdentifier value to the Name attribute. The name attribute is a meaningful string that characterizes the relationship when navigating from the entity that declared the navigation property to the related entity.
The name of the navigation property MUST be unique within the set of structural and navigation properties of the containing entity type and any base types of the entity type.
2 The Type Attribute
A navigation property MUST specify a value for the Type attribute. The value of the type attribute MUST resolve to an entity type or a collection of an entity type in scope, i.e. either declared in the same model or a model imported with an edm:Using element.
If the value is an entity type name, there can be at most one related entity. If it is a collection, an arbitrary number of entities can be related.
The related entities MUST be of the specified entity type or one of its subtypes.
3 The Nullable Attribute
A navigation property whose Type attribute specifies an entity typea collection MAY specify a Boolean value for the Nullable attribute. The value of this attribute determines whether a navigation target is required for the navigation property on instances of the containing type.
If no value is specified, the nullable attribute defaults to true.
A navigation property whose Type attribute specifies a collection MUST NOT specify a value for the Nullable attribute as the collection always exists, it may just be empty.
4 The Partner Attribute
A navigation property MAY specify a SimpleIdentifier value for the Partner attribute. If specified, the value of this attribute MUST be the name of a direct or inherited navigation property in the entity type specified in the Type attribute. The type of the partner navigation property MUST be the containing entity type of the current navigation property or one of its parent entity types.
5 The ContainsTarget Attribute
A Boolean value MAY be assigned to the ContainsTarget attribute. If no value is assigned to the ContainsTarget attribute, the attribute defaults to false. If the value assigned to the ContainsTarget attribute is true, the entity type to which the navigation property belongs is said to contain the destination of the navigation property.
It MUST NOT be possible for an entity type to contain itself by following more than one containment navigation property.
When a navigation property with ContainsTarget="true" navigates between entity types in the same entity set it is called recursive containment. If the containment is recursive, the partner navigation property MUST be nullable and specify a single entity type (i.e. have a multiplicity of 0..1). If the containment is not recursive, the partner navigation property MUST NOT be nullable (i.e. have a multiplicity of 1).
If the containment is recursive, a navigation property binding for the containment navigation property MUST specify the same entity set that encloses the navigation property binding.
An entity set MUST NOT be specified in more than one navigation property binding for a containment navigation property.
6 The edm:ReferentialConstraint Element
A navigation property whose Type attribute specifies a single entity type MAY define a referential constraint. A referential constraint asserts that if the navigation property is not null, the properties of the source entity listed in the referential constraint MUST have the same values as the corresponding key properties of the related entity.
A referential constraint MUST contain one or more edm:PropertyRef elements.
In the example that follows, the category must exist for a product in that category to exist, and the category ID of the product is identical to the ID of the category:
...
7 The edm:PropertyRef Element
The edm:PropertyRef elements indicate the properties that take part in the referential constraint on the source entity type. The edm:ReferentialConstraint element MUST contain the same number of edm:PropertyRef elements as the edm:Key of the navigation target entity type.
The property references MUST appear in the same order as the corresponding key property references of the target entity type. The referenced property in the source entity type MUST have the same data type as the corresponding key property of the target entity type.
The property references MUST be path expressions resolving to primitive properties of the entity type itself or to primitive properties of complex properties (recursively) of the entity type.
8 The edm:OnDelete Element
A navigation property MAY define an edm:OnDelete element. It prescribes the action that should be taken when the (last) entity targeted by the navigation property is deleted.
If present, the edm:OnDelete element MUST define a value for the Action attribute. The value assigned to the action attribute MUST be Cascade or None.
Complex Type Constructs
Complex types are keyless nominal structured types. The lack of a key means that complex types cannot be created, updated or deleted independently of an entity type. Complex types allow entity models to group properties into common structures if the group of properties does not need to be managed independently.
All properties MUST have a unique name. Properties MUST NOT have the same name as the declaring complex type.
The following example demonstrates a complex type that is used by two entity types:
...
...
1 The edm:ComplexType Element
The edm:ComplexType element represents a complex type in an entity model.
The complex type MUST declare a SimpleIdentifier value for the Name attribute as well as one or more edm:Property elements. Complex types MUST NOT have any navigation properties.
1 The BaseType Attribute
A complex type can inherit from another complex type by specifying a SingleComplexTypeName value for the BaseType attribute.
A complex type inherits the properties declared on the complex type’s base type.
A complex type MUST NOT introduce an inheritance cycle via the base type attribute.
2 The Abstract Attribute
A complex type MAY indicate that it cannot be instantiated by providing a Boolean value of true to the Abstract attribute. If not specified, the Abstract attribute defaults to false.
Enumeration Type Constructs
Enumeration types are nominal scalar types that represent a series of related values. Enumeration types expose these related values as members of the enumeration.
Enumeration types typically allow the selection of a single member. The IsFlags attribute allows entity model authors to indicate that more than one value can be selected.
The following example shows a simple flags-enabled enum:
1 The edm:EnumType Element
The edm:EnumType element represents an enumeration type in an entity model.
The enumeration type MUST provide a SimpleIdentifier as the value of the Name attribute.
The enumeration type element contains zero or more child edm:Member elements enumerating the members of the enum.
1 The UnderlyingType Attribute
An enumeration type has an underlying type which specifies the allowable values for member mapping.
An enumeration type MAY include an UnderlyingType attribute to specify an underlying type whose value MUST be one of Edm.Byte, Edm.SByte, Edm.Int16, Edm.Int32, or Edm.Int64. If the UnderlyingType attribute is not specified, a 32-bit integer MUST be used as the underlying type.
2 The IsFlags Attribute
An enumeration type MAY specify a Boolean value for the IsFlags attribute. A value of true indicates that the enumeration type allows multiple members to be selected simultaneously.
2 The edm:Member Element
An enumeration type typically has two or more members. Members represent discrete options for the enumeration type.
Enumeration members are declared with the edm:Member element.
For example, the following enumeration type has three discrete members:
1 The Name Attribute
Each enumeration member MUST provide a SimpleIdentifier value for the Name attribute. The enumeration type MUST NOT declare two members with the same name.
2 The Value Attribute
The value of an enum member allows entity instances to be sorted by a property that has an enum member for its value. If the value is not explicitly set, the value MUST be assigned to 0 for the first member or one plus the previous member value for any subsequent members.
The value MUST be a valid value for the UnderlyingType of the enumeration type.
In the example that follows, FirstClass MUST be assigned a value of 0, TwoDay a value of 4, and Overnight a value of 5.
Other Type Constructs
1 Collection Types
A collection type provides a means of representing a collection of scalar, complex or entity types.
A collection type can be represented with attribute notation or element notation, as shown in these two equivalent examples:
If specified with attribute notation, the collection type MUST be a collection of entity types, complex types, or scalar types. If specified with element notation, the collection type can also be a collection of other collection types, or reference types or row types.
2 The edm:CollectionType Element
The edm:CollectionType element represents a collection of other types in an entity model.
1 The ElementType Attribute
The collection type element can identify the types contained in the collection by specifying a SimpleIdentifier or QualifiedName value for the ElementType attribute.
Alternatively the collection type can identify the types contained in the collection by specifying one of the following child elements:
• edm:CollectionType
• edm:ReferenceType
• edm:TypeRef
The collection type MUST identify the types contained in the collection with exactly one of the methods indicated above.
The collection type can define relevant facets for scalar types.
3 The edm:TypeRef Element
The edm:TypeRef element is used to reference a nominal type.
1 The Type Attribute
The edm:TypeRef element MUST provide a SimpleIdentifier or QualifiedName value for the Type attribute.
The type ref can define relevant facets for scalar types.
4 Reference Types
A reference type specifies a reference to an entity instance. A reference to an entity instance is a special structure consisting primarily of the entity instance key. A reference to an entity instance is useful when a large number of entities would otherwise be returned.
A reference type can be specified with attribute notation or element notation, as shown in the following two examples:
1 The edm:ReferenceType Element
The edm:ReferenceType element represents a reference type in an entity model.
1 The Type Attribute
A reference type MUST specify a SingleEntityTypeName value for the Type attribute. The value of this attribute names the type for which the reference type contains key information.
5 Type Definitions
A type definition specifies a specialization of one of the primitive types.
1 The Name Attribute
The edm:TypeDefinition element MUST provide a SimpleIdentifier as the value of the Name attribute.
2 The UnderlyingType Attribute
The edm:TypeDefinition element MUST provide the name of a primitive type as the value of the UnderlyingType attribute. It MUST NOT provide the name of a type definition as the value of the UnderlyingType attribute.
3 TypeDefinition Facets
The edm:TypeDefinition element MAY provide values for zero or more facets applicable to the underlying type.
Type definitions can be used wherever a primitive type is used (other than as the underlying type in a new type definition), and are type-comparable with their underlying types and any type definitions defined using the same underlying type.
Additional facets appropriate for the underlying type may be specified in the usage, but the facets specified in the type definition must not be respecified.
Annotations MAY be applied to a type definition, and are considered applied wherever the type definition is used. Applying the same annotation to a property whose type definition already defines that annotation is an error.
Where type definitions are used, the type definition is returned in place of the primitive type wherever the type is specified in a response.
Example:
Entity Container Constructs
An entity model can also describe how entities are logically grouped and even model the store or stores from which the entities can be retrieved. This is achieved through the declaration of entity containers and entity sets.
An entity set is a nominal type that allows access to entity type instances. Simple entity models frequently have one entity set per entity type, for example:
Other entity models may expose multiple entity sets per type. For instance, an entity model may have the following entity sets:
In this case the Products entity set could expose products that have not been discontinued and the DiscontinuedProducts entity set could expose products that have been discontinued.
An entity set can expose instances of the specified entity type as well as any entity type inherited from the specified entity type.
A named entity allows addressing a single entity directly from the entity container without having to know its key. This allows defining a shortcut to “important” entities, or having “singleton” entities without the need for a one-element entity set.
A function import is used to expose functions that are defined in a data store. For example, the following function import exposes a stored procedure that returns the top ten revenue generating products for a given fiscal year:
An entity container is the entity model equivalent of a single data store. An entity container aggregates entity sets, root entities, and function imports.
A full example of an entity container is as follows:
1 The edm:EntityContainer Element
The edm:EntityContainer element represents an entity container in an entity model. It corresponds to a logical data store and contains zero or more edm:EntitySet, edm:Entity, or edm:FunctionImport elements. Function import, entity set, and entity names MUST be unique within an entity container.
1 The Name Attribute
The entity container MUST provide a unique SimpleIdentifier value for the Name attribute.
2 The IsDefaultEntityContainer Attribute
The entity container MAY provide a Boolean value for the IsDefaultEntityContainer attribute. Each CSDL document that is used to describe a data service MUST mark exactly one entity container with this attribute to denote that it is the default.
3 The Extends Attribute
An entity container MAY provide a QualifiedName value for the Extends attribute. The value provided to the Extends attribute MUST resolve to an entity container in the entity model. All of the children in the extending entity container are added to the children of the extended entity container.
2 The edm:EntitySet Element
The edm:EntitySet element is a nominal type that represents an entity set in an entity model.
1 The Name Attribute
An entity set MUST provide a SimpleIdentifier value for the Name attribute.
2 The EntityType Attribute
An entity set also has an EntityType attribute that MUST be provided with a SingleEntityTypeName that resolves to an entity type in the model. Each entity type in the model may have zero or more entity sets that reference the entity type.
An entity set MUST contain only instances of the entity type specified by the EntityType attribute or its subtypes. The entity type named by the entity type attribute MAY be abstract.
3 The edm:NavigationPropertyBinding Element
An entity set SHOULD contain an edm:NavigationPropertyBinding element for each navigation property of its entity type. If the related instances can come from multiple entity sets, multiple navigation property bindings MAY be specified for the same navigation property.
1 The Path Attribute
A navigation property binding MUST name a navigation property of the entity set’s entity type or one of its subtypes in the Path attribute. If the navigation property is defined on a subtype, the path attribute MUST contain the QualifiedName of the entity type, followed by a forward slash, followed by the navigation property name.
2 The EntitySet Attribute
A navigation property binding MUST specify a value for the EntitySet attribute. The value MUST be the name of the entity set that contains the related instances targeted by the navigation property specified in the Path attribute. If the target entity set is not defined in the current same entity container as the enclosing EntitySet elementmodel, the entity set name must be qualified with the namespace or alias of the schema that defines the entity set, followed by the entity container.
Examples:
• EntitySet="SomeSet" for an entity set in the default same container as the enclosing entity set of the current model,
• EntitySet="SomeModel.SomeContainer.SomeSet" for an entity set in any container of an imported model in scope.
4 The edm:Entity Element
The edm:Entity element represents a single entity in an entity model.
1 The Name Attribute
A named entity MUST provide a SimpleIdentifier value for the Name attribute.
2 The Type Attribute
A named entity also has a Type attribute that MUST be provided with a SingleEntityTypeName that resolves to an entity type in the model. Each entity type in the model may have zero or more named entities that reference the entity type.
A named entity MUST reference an instance of the entity type specified by the Type attribute or its subtypes. The entity type named by the Type attribute MAY be abstract.
5 The edm:FunctionImport Element
The edm:FunctionImport element is a nominal type that represents a Function or Action in an entity model.
Functions MUST NOT have observable side-effects and MUST return a single or collection of primitive types or nominal structured types. Functions MAY be composable.
Actions MAY have side-effects and MAY return a single or collection of primitive types or nominal structured types. Actions are not composable.
A function import MUST provide a SimpleIdentifier value for the Name attribute.
The function import MAY specify a return type using the edm:ReturnType element. The return type must be a scalar, entity or complex type, or a collection of scalar, entity or complex types.
If the function import specifies a return type that is an entity or a collection of entities, it MUST include either an EntitySet Attribute or an EntitySetPath Attribute to specify the entity set of the returned entity or collection of entities.
The function import may also define zero or more edm:Parameter elements to be used during the execution of the function.
1 The ReturnType Attribute
If the return type is written with attribute notation, an AnyTypeName value MUST be provided for the ReturnType attribute.
If a value is provided for the return type attribute, the edm:FunctionImport element MUST NOT contain an edm:ReturnType element.
2 The EntitySet Attribute
If the return type is an entity or a collection of entities, a SimpleIdentifier value MAY be defined for the EntitySet attribute that names the entity set to which the returned entities belong.
If the return type is not an entity or a collection of entities, a value MUST NOT be defined for the EntitySet attribute.
If the EntitySet attribute is assigned a value, the EntitySetPath attribute MUST NOT be assigned a value.
3 The EntitySetPath Attribute
The function import MAY specify a value for the EntitySetPath attribute if determination of the entity set for the return type is contingent on a parameter.
The value for the EntitySetPath attribute consists of a series of segments joined together with forward slashes.
The first segment of the entity set path MUST have the same name as one of the function import’s parameters. The remaining segments of the entity set path MUST represent navigation or type casts.
A navigation segment simply names the SimpleIdentifier of the navigation property to be traversed. A type cast segment names the QualifiedName of the entity type that should be returned from the type cast.
4 The IsSideEffecting Attribute
A function import that may have side effects represents an Action. A function import that does not have side effects represents a Function.
The function import MAY specify a Boolean value for the IsSideEffecting attribute. If no value is specified for the IsSideEffecting attribute, the value defaults to true, indicating that the function import represents an Action.
If the value of the IsSideEffecting attribute is true, the value of the IsComposable attribute MUST be false.
5 The IsBindable Attribute
A function import can specify a Boolean value for the IsBindable attribute. If no value is specified for the IsBindable attribute, the value defaults to false.
If the is bindable attribute is set to true, the function import MUST contain at least one edm:Parameter element, and the first such parameter must represent an entity or collection of entities.
6 The IsComposable Attribute
A function import can specify a Boolean value for the IsComposable attribute. If no value is specified for the is composable attribute, the value defaults to false.
If the value of the IsComposable attribute is true, the value of the IsSideEffecting attribute MUST be false.
6 The edm:ReturnType Element
If the return type is written with element notation, the function import MUST contain a single edm:ReturnType element.
If element notation is used, a similar set of attributes can be used to specify the return type of the function.
1 The Type Attribute
The Type attribute corresponds to the ReturnType attribute on edm:FunctionImport, and the names and functionality of the EntitySet and EntitySetPath attributes remain the same.
7 The edm:Parameter Element
The edm:Parameter element allows one or more parameters to be passed to the function. This enables the function to return a dynamic set of instances – for example, the top-selling products by year. In this case the year must be specified as a parameter to the function with the edm:Parameter element.
The Name attribute MUST be used to assign a unique SimpleIdentifier value to the parameter.
1 The Type Attribute
The parameter MUST indicate which set of types can be passed to the parameter by providing an AnyTypeName value for the Type attribute.
2 Parameter Facets
A parameter may specify values for the Nullable, DefaultValue, MaxLength, Precision, Scale, or SRID attributes. The descriptions of these facets and their implications are covered in section 6.3.
Vocabulary Concepts
Vocabulary terms and annotations provide a means of semantically enriching an entity model and the type instances accessible through that entity model. Annotations can be used for two fundamental purposes:
• To extend type instances with additional information
• To enable new types to be instantiated from existing type instances
Type instances can be extended with additional information through the application of value annotations. A value annotation attaches a value term to a type instance and provides a means of calculating a value for the value term.
For example, the following entity type includes a value annotation that allows a display name to be calculated from an entity instance:
...
Type annotations allow a different type to be instantiated from an instance of an entity type. The type annotation attaches a type term to a type instance and provides a means of instantiating the type named in the term.
For instance, the following entity type includes a type annotation that allows a SearchResult to be instantiated from a Product:
...
Products(
ID
)
Description
Type and value annotations can be defined at a universal or instance level. Universal annotations are applied directly in the entity model as described in CSDL. Instance annotations are applied to entity instances in the response payload.
Type and value annotations can be used to apply type and value terms respectively. These terms may be part of a well-known vocabulary or part of a company-specific or product-specific vocabulary.
Vocabulary Terms
There are two types of vocabulary terms that can be applied: type terms and value terms.
A type term implies that a type can be instantiated from the annotated element. Either an edm:EntityType or an edm:ComplexType can be used as a type term.
A value term annotates an element with additional data. A value term has a single value which may be a primitive type, complex type, or collection of primitive or complex types.
1 edm:EntityType and edm:ComplexType as Type Terms
There are no special requirements for an edm:EntityType or an edm:ComplexType to be used as a type term. Type terms need not be in the same model as the type annotations or the annotated types.
2 The edm:ValueTerm Element
The edm:ValueTerm element represents a value term in an entity model.
1 The Name Attribute
The value term MUST provide a SimpleIdentifier value for the Name attribute. The name attribute allows the term to be applied with a value annotation.
2 The Type Attribute
The value term MUST provide an AnyKeylessTypeName value for the Type attribute. The type attribute indicates what type of value must be returned by the expression contained in the value annotation.
3 The DefaultValue Attribute
A value term MAY define a value for the DefaultValue attribute. The value of this attribute determines the value of the value term when applied in an edm:ValueAnnotation without providing an expression.
Vocabulary Annotations
Vocabulary terms are used to annotate other parts of the model. The following model elements may be annotated with a value term:
• edm:Annotations
• edm:ComplexType
• edm:EntitySet
• edm:EntityType
• edm:EnumType
• edm:FunctionImport
• edm:NavigationProperty
• edm:Parameter
• edm:Property
• edm:ValueTerm
A value annotation extends a model element or type instance with additional information.
Type terms are used to annotate an entity type or complex type. In this situation, an instance of the type term may be created for each instance of the entity type or complex type the term is applied to.
1 The edm:Annotations Element
The edm:Annotations element is used to apply a group of type or value annotations to a single model element.
An annotations element MUST assign a SimpleIdentifier or QualifiedName value to the Target attribute. The value of the target attribute SHOULD resolve to a model element in the entity model.
An annotations element MAY contain zero or more edm:TypeAnnotation and edm:ValueAnnotation elements.
2 The edm:TypeAnnotation Element
The edm:TypeAnnotation element represents a type annotation. A type annotation binds a type term to a part of the entity model.
A type annotation MUST be used as a child of the part of the model it annotates or a child of an edm:Annotations element that targets the appropriate part of the model.
A type annotation MUST provide a SimpleIdentifier or QualifiedName value for the Term attribute. The value of the term attribute SHOULD resolve to an entity type or complex type.
A type annotation MAY contain zero or more edm:PropertyValue elements.
3 The edm:PropertyValue Element
The edm:PropertyValue element supplies a value to a property on the type instantiated by a type annotation. The value is obtained by evaluating an expression.
The property value element MUST assign a SimpleIdentifier value to the Property attribute. The value of the property attribute SHOULD resolve to a property on the term referenced by the type annotation.
A property value MUST contain exactly one expression. The expression MAY be provided using element notation or attribute notation.
4 The edm:ValueAnnotation Element
The edm:ValueAnnotation element represents a value annotation. A value annotation attaches a named value to a model element.
A value annotation MUST be used as a child of the model element it annotates or a child of an edm:Annotations element that targets the appropriate model element.
A value annotation MUST provide a SimpleIdentifier or QualifiedName value for the Term attribute. The value of the term attribute SHOULD resolve to a value term.
A value annotation MAY contain at most one expression. The expression MAY be provided using element notation or attribute notation.
5 The Qualifier Attribute
The qualifier attribute allows service authors a means of conditionally applying a type annotation. For instance, the following value annotation hints that it should only be applied to slate devices:
The value of the Qualifier attribute is an arbitrary string.
An edm:Annotations element MUST provide at most one value for the qualifier attribute.
Type or value annotations MUST provide at most one value for the qualifier attribute. Type or value annotations that are children of an annotations element MUST NOT provide a value for the qualifier attribute.
Vocabulary Expressions
Values for a value term or properties of a type term are obtained by calculating expressions. There are a variety of expressions that allow service authors to supply constant or dynamic values.
All vocabulary expressions may be specified as an element, for example:
Customers
The constant expressions and the edm:Path expression also support attribute notation:
1 Constant Expressions
Constant expressions allow the service author to supply an unchanging value to a value term or property of a type term.
The following examples show two value annotations intended as user interface hints:
1 The edm:Binary Constant Expression
The edm:Binary constant expression evaluates to a primitive binary value. A binary expression MUST be assigned a value of the type xs:hexBinary, see [XML-Schema-2], section 3.2.15.
A binary expression may be written with either element notation or attribute notation, as shown in the following examples:
3f3c6d78206c
2 The edm:Bool Constant Expression
The edm:Bool constant expression evaluates to a primitive Boolean value. A Boolean expression MUST be assigned a value of the type Boolean.
A Boolean expression may be written with either element notation or attribute notation, as shown in the following examples:
true
3 The edm:DateTime Constant Expression
The edm:DateTime constant expression evaluates to a primitive date/time value. A date/time expression MUST be assigned a value of the type xs:dateTime, see [XML-Schema-2], section 3.2.7. The UTC offset portion of this value MUST be discarded.
ISSUE: Discarding the offset makes the timestamp meaningless. Falls into the larger issue of which meaning a DateTime without timezone has.
PROPOSAL: DateTime without explicit timezone means UTC. The timestamp value has to be converted to UTC before discarding the offset.
A date/time expression may be written with either element notation or attribute notation, as shown in the following examples:
2000-01-01T16:00:00.000
4 The edm:DateTimeOffset Constant Expression
The edm:DateTimeOffset constant expression evaluates to a primitive date/time value with a UTC offset. An edm:DateTimeOffset expression MUST be assigned a value of the type xs:dateTime, see [XML-Schema-2], section 3.2.7.
An edm:DateTimeOffset expression may be written with either element notation or attribute notation, as shown in the following examples:
2000-01-01T16:00:00.000-09:00
5 The edm:Decimal Constant Expression
The edm:Decimal constant expression evaluates to a primitive decimal value. A decimal expression MUST be assigned a value of the type xs:decimal, see [XML-Schema-2], section 3.2.3.
A decimal expression may be written with either element notation or attribute notation, as shown in the following examples:
3.14
6 The edm:Float Constant Expression
The edm:Float constant expression evaluates to a primitive floating point (or double) value. A floating point expression MUST be assigned a value of the type xs:double, see [XML-Schema-2], section 3.2.5.
A floating point expression may be written with either element notation or attribute notation, as shown in the following examples:
3.14
7 The edm:Guid Constant Expression
The edm:Guid constant expression evaluates to a primitive 32-character string value. A guid expression MUST be assigned a value conforming to the rule guid in [OData-ABNF].
A guid expression may be written with either element notation or attribute notation, as shown in the following examples:
21EC2020-3AEA-1069-A2DD-08002B30309D
8 The edm:Int Constant Expression
The edm:Int constant expression evaluates to a primitive integral value. An integral expression MUST be assigned a value of the type xs:integer, see [XML-Schema-2], section 3.3.13.
An integral expression may be written with either element notation or attribute notation, as shown in the following examples:
42
9 The edm:String Constant Expression
The edm:String constant expression evaluates to a primitive string value. A string expression MUST be assigned a value of the type xs:string see [XML-Schema-2], section 3.2.1.
A string expression may be written with either element notation or attribute notation, as shown in the following examples:
Product Catalog
10 The edm:Time Constant Expression
The edm:Time constant expression evaluates to a primitive time value. On platforms that do not support a primitive time value, the Time constant expression evaluates to a primitive date/time value. A time expression MUST be assigned a value of the type xs:duration see [XML-Schema-2], section 3.2.6..
A time expression may be written with either element notation or attribute notation, as shown in the following examples:
PT21:00:00-08:00H45M
2 Dynamic Expressions
1 The edm:Apply Expression
The edm:Apply expression enables a value to be obtained by applying a client-side function. An apply expression MUST assign a string value to the Function attribute. The value of the function attribute SHOULD be a QualifiedName. The value of the function attribute is used to locate the client-side function that should be applied.
The edm:Apply expression MUST contain zero or more expressions. The expressions contained within the apply expression are used as parameters to the function.
The apply expression MUST be written with element notation, as shown in the following example:
Product
Catalog
2 The edm:AssertType Expression
The edm:AssertType expression asserts that a value obtained from a child expression is of a specified type. The value calculated by the assert type expression is the value obtained from the child expression casted to the specified type.
The assert type expression MUST assign a value of the type AnySingleTypeName to the Type attribute.
The edm:AssertType expression MUST contain exactly one expression. The expression contained within the assert type expression is used as a parameter to the type assertion.
The edm:AssertType expression MUST be written with element notation, as shown in the following example:
Product Catalog
3 The edm:Collection Expression
The edm:Collection expression enables a value to be obtained from zero or more child expressions. The value calculated by the collection expression is the collection of the values calculated by each of the child expressions.
A collection expression MUST contain zero or more child expressions. The values of the child expressions MUST all be type compatible. Each child expression MUST be a constant expression or an edm:Record expression.
A collection expression MUST be written with element notation, as shown in the following example:
Product
Supplier
Customer
4 The edm:EntitySetReference Expression
The value of an edm:EntitySetReference is a reference to an entity set. A reference to an entity set is a collection of entities.
The edm:EntitySetReference expression MUST contain a value of the type QualifiedName. The value of the entity set reference expression MUST resolve to an entity set.
The edm:EntitySetReference expression MUST be written with element notation, as shown in the following example:
Self.SaleProducts
5 The edm:EnumMemberReference Expression
The value of an edm:EnumMemberReference is a reference to a member of an enumeration type.
The edm:EnumMemberReference expression MUST contain a value of the type QualifiedName. The value of the enum member reference expression MUST resolve to a member of an enumeration type.
The edm:EnumMemberReference expression MUST be written with element notation, as shown in the following example:
org.example.address.Type.Mailing
6 The edm:FunctionReference Expression
The value of an edm:FunctionReference is a reference to the return type of a function.
The edm:FunctionReference expression MUST contain a value of the type QualifiedName. The value of the function reference expression MUST resolve to a valid signature of a function.
The edm:FunctionReference expression MUST contain zero or more expressions. The expressions contained within the function reference expression are used to determine which overload of the function is being referenced.
The edm:FunctionReference expression MUST be written with element notation, as shown in the following example:
BirthDate
7 The edm:If Expression
The edm:If expression enables a value to be obtained by evaluating a conditional expression.
An edm:if expression MUST contain exactly three child expressions. The first child expression is the conditional expression and MUST evaluate to a Boolean result.
The second and third child expressions are the expressions which are evaluated conditionally. If the conditional expression evaluates to true, the second child expression MUST be evaluated and its value MUST be returned as the result of the edm:If expression. If the conditional expression evaluates to false, the third child expression MUST be evaluated and its value MUST be returned as the result of the edm:If expression.
The second child expression MUST return a value that is type compatible with the value returned from the third child expression.
The edm:If expression MUST be written with element notation, as shown in the following example:
IsFemale
Female
Male
8 The edm:IsType Expression
The edm:IsType expression evaluates a child expression and returns a Boolean value indicating whether the child expression returns the specified type. The is type expression MUST assign a value of the type AnySingleTypeName to the Type attribute.
An edm:IsType expression MUST contain exactly one child expression. The edm:isType expression MUST return true if the child expression returns a type that is compatible with the type named in the Type attribute. The edm:isType expression MUST return false if the child expression returns a type that is not compatible with the type named in the Type attribute.
The edm:IsType expression MUST be written with element notation, as shown in the following example:
Customer
9 The edm:LabeledElement Expression
The edm:LabeledElement expression assigns a name to a child expression. The value of the child expression can then be reused elsewhere with an edm:LabeledElementReference expression. The labeled element expression MUST assign a value of the type SimpleIdentifier to the Name attribute.
A labeled element expression MUST contain exactly one child expression written either in attribute notation or element notation. The value of the child expression is passed through the labeled element expression. The value of the child expression can also be accessed elsewhere by a labeled element reference expression.
A labeled element expression MUST be written with element notation, as shown in the following example:
FirstName
10 The edm:LabeledElementReference Expression
The edm:LabeledElementReference expression returns the value of a labeled element expression.
The labeled element reference expression MUST contain a value of the type SimpleIdentifier. The value of the SimpleIdentifier MUST resolve to a labeled element expression.
The edm:LabeledElementReference expression MUST be written with element notation, as shown in the following example:
DisplayName
11 The edm:Null Expression
The edm:Null expression returns an untyped null value. The edm:Null expression MUST NOT contain any other elements or expressions.
The edm:Null expression MUST be written with element notation, as shown in the following example:
12 The edm:ParameterReference Expression
The value of an edm:ParameterReference expression is a reference to a function parameter.
The edm:ParameterReference expression MUST contain a value of the type QualifiedName. The value of the parameter reference expression MUST resolve to a parameter.
The edm:ParameterReference expression MUST be written with element notation, as shown in the following example:
Image
13 The edm:Path Expression
The edm:Path expression enables a value to be obtained by traversing an object graph.
The value assigned to the path expression MUST be composed of zero or more segments joined together by forward slashes. Each segment MUST represent a type cast, a property or a navigation property.
If the path segment represents a type cast, the segment MUST be of the type QualifiedName. If the path segment represents a property or a navigation property, the segment MUST be of the type SimpleIdentifier and MUST resolve to a property or a navigation property of the same name.
If a path segment traverses a navigation property that has a cardinality of many, the path MUST NOT have any subsequent segments.
If the edm:Path expression is an empty string or an empty element, the path MUST refer to the containing object.
The edm:Path expression may be written with either element notation or attribute notation, as shown in the following examples:
FirstName
14 The edm:PropertyReference Expression
The value of an edm:PropertyReference is a reference to a structural property.
The edm:PropertyReference expression MUST contain a value of the type QualifiedName. The value of the property reference expression MUST resolve to a valid signature of a property.
15 The edm:Record Expression
The edm:Record expression enables a new entity type or complex type instance to be constructed.
A record expression can specify a SimpleIdentifier or QualifiedName value for the Type attribute. If no value is specified for the type attribute, the type is derived from the expression’s context. If a value is specified, the value MUST resolve to an entity type or complex type in the entity model.
A record expression MUST contain zero or more edm:PropertyValue elements. For each non-nullable property of the record construct’s type an child element MUST be provided. For derived types this rule applies only to properties directly defined by the derived type.
A record expression MUST be written with element notation, as shown in the following example:
16 The edm:ValueTermReference Expression
The value of an edm:ValueTermReference expression is a reference to a value term.
The edm:ValueTermReference expression MUST contain a value of the type QualifiedName. The value of the value term reference expression MUST resolve to a valid signature of a value term.
CSDL Examples
Following are two basic examples of valid EDM models as represented in CSDL. These examples demonstrate many of the topics covered above.
1 Products and Categories Example
2 Annotated Customers and Orders Example
FirstName
LastName
Informative XSD for CSDL
The non-normative schema for CSDL can be found in .
It only defines the shape of a well-formed CSDL document, but is not descriptive enough to define what a correct CSDL document is.
Attribute Values
1 Namespace
A Namespace is a character sequence conforming to the rule namespace in [OData-ABNF].Non-normatively speaking it is a dot-separated sequence of SimpleIdentifiers.
2 SimpleIdentifier
A SimpleIdentifier is a character sequence conforming to rule odataIdentifier in [OData-ABNF].
Non-normatively speaking it starts with a letter or underscore, followed by at most 478 letters, underscores or digits.
3 QualifiedName
For model elements that are direct children of a schema: the namespace or alias of the schema that defines the model element, followed by a dot and the name of the model element, see rule qualifiedTypeName in [OData-ABNF].
For model elements that are direct children of an entity container: the simple or qualified name of the entity container, followed by a dot and the name of the model element, see rules, qualifiedActionName and qualifiedFunctinoName in [OData-ABNF].
4 AnyTypeName
The simple or qualified name of a primitive type, complex type, enumeration type, or entity type, or a collection of one of these types, see rule qualifiedTypeName in [OData-ABNF].
The type must be in scope, i.e. if a SimpleIdentifier is used, the type MUST be defined in the same schema, and if a QualifiedName is used, the type MUST be defined in the schema identified by the namespace or alias portion of the qualified name, and the identified schema MUST have been imported with edm:Using.
5 AnySingleTypeName
The simple or qualified name of a primitive type, complex type, enumeration type, or entity type in scope.
6 AnyKeylessTypeName
The simple or qualified name of a primitive type, complex type, or enumeration type in scope, or a collection of one of these types.
7 SingleEntityTypeName
The simple or qualified name of an entity type in scope.
8 SingleComplexTypeName
The simple or qualified name of a complex type in scope.
9 Boolean
One of the literals true and false.
Conformance
The last numbered section in the specification must be the Conformance section. Conformance Statements/Clauses go here.
Acknowledgments
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
[Participant Name, Affiliation | Individual Member]
[Participant Name, Affiliation | Individual Member]
Non-Normative Text
text
1. Subsidiary section
text
1. Sub-subsidiary section
text
Revision History
|Revision |Date |Editor |Changes Made |
|01 |2012-08-dd |Ralf Handl |Translated contribution into OASIS format |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- minecraft version 1 0 download
- free fences version 1 0 desktop organizer
- 1 or 3 374 374 1 0 0 0 1 168 1 1 default username and password
- 1 or 3 711 711 1 0 0 0 1 168 1 1 default username and password
- 1 or 3 693 693 1 0 0 0 1 168 1 1 default username and password
- 1 or 3 593 593 1 0 0 0 1 or 2dvchrbu 168 1 1 default username and password
- 1 or 3 910 910 1 0 0 0 1 168 1 1 default username and password
- 1 or 3 364 364 1 0 0 0 1 168 1 1 admin username and password
- 192 1 or 3 33 33 1 0 0 0 1 1 1 default username and password
- 1 or 3 633 633 1 0 0 0 1 168 1 1 admin username and password
- 192 1 or 3 735 735 1 0 0 0 1 1 1 default username and password
- 1 or 3 297 297 1 0 0 0 1 168 1 1 username and password verizon