OData Common Schema Definition Language (CSDL) Version 1.0
Working Draft 01
0328SeptemberAugust 2012
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Barbara Hartel (), SAP AG
Ram Jeyaraman (), Microsoft
Editor:
Mike Pizzo (), Microsoft
Ralf Handl (), SAP AG
Susan Malaika (), IBM
Christopher Woodruff (), Perficient, Inc
Martin Zurmuehl (), SAP AG
Additional artifacts:
This prose specification is one component of a Work Product which also includes:
- XML schemas:(list file names or directory name)
- Other parts (list titles and/or file names)
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:
- list namespaces declared within this specification
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
1Introduction
1.1 Terminology
1.2 Normative References
1.3 Non-Normative References
2Common Schema Definition Language (CSDL) Namespaces
2.1 Entity Data Model for Data Services Packaging (EDMX) Namespace
2.2 Entity Data Model (EDM) Namespace
2.3 Data Service Metadata Namespace
3Common Characteristics of Entity Models
3.1 Nominal Types
3.2 Structural Types
3.3 The edm:Documentation Element
3.4 Vocabulary Annotations
3.5 Primitive Types
4Entity Model Wrapper Constructs
4.1 The edmx:Edmx Element
4.1.1 The Version Attribute
4.2 The edmx:DataServices Element
4.2.1 The metadata:DataServiceVersion Attribute
4.3 The edmx:Reference Element
4.3.1 The edmx:Url Attribute
4.4 The edmx:AnnotationsReference Element
4.4.1 The edmx:Url Attribute
4.5 The edmx:Include Element
4.5.1 The edmx:TermNamespace Attribute
4.5.2 The edmx:Qualifier Attribute
5Schema Constructs
5.1 The edm:Schema Element
5.1.1 The edm:Namespace Attribute
5.1.2 The edm:Alias Attribute
5.2 The edm:Using Element
5.2.1 The edm:Namespace Attribute
5.2.2 The edm:Alias Attribute
6Properties
6.1 The edm:Property Element
6.1.1 The edm:Name Attribute
6.2 The edm:Type Attribute
6.3 Property Facets
6.3.1 The edm:Nullable Attribute
6.3.2 The edm:MaxLength Attribute
6.3.3 The edm:FixedLength Attribute
6.3.4 The edm:Precision Attribute
6.3.5 The edm:Scale Attribute
6.3.6 The edm:Unicode Attribute
6.3.7 The edm:Collation Attribute
6.3.8 The edm:SRID Attribute
6.3.9 The edm:DefaultValue Attribute
6.3.10 The edm:ConcurrencyMode Attribute
7Entity Type Constructs
7.1 The edm:EntityType Element
7.1.1 The edm:Name Attribute
7.1.2 The edm:BaseType Attribute
7.1.3 The edm:Abstract Attribute
7.1.4 The edm:OpenType Attribute
7.1.5 The metadata:HasStream Attribute
7.2 The edm:Key Element
7.3 The edm:PropertyRef Element
7.4 The edm:NavigationProperty Element
7.4.1 The edm:Name Attribute
7.4.2 The edm:Relationship Attribute
7.4.3 The edm:ToRole Attribute
7.4.4 The edm:FromRole Attribute
7.4.5 The edm:ContainsTarget Attribute
8Complex Type Constructs
8.1 The edm:ComplexType Element
8.1.1 The edm:BaseType Attribute
8.1.2 The edm:Abstract Attribute
9Enumeration Type Constructs
9.1 The edm:EnumType Element
9.1.1 The edm:UnderlyingType Attribute
9.1.2 The edm:IsFlags Attribute
9.2 The edm:Member Element
9.2.1 The edm:Name Attribute
9.2.2 The edm:Value Attribute
10Other Type Constructs
10.1 Collection Types
10.1.1 The edm:CollectionType Element
10.2 The edm:TypeRef Element
10.3 Reference Types
10.3.1 The edm:ReferenceType Element
10.4 Row Types
10.4.1 The edm:RowType Element
11Association Constructs
11.1 The edm:Association Element
11.2 The edm:End Element
11.2.1 The edm:Type Attribute
11.2.2 The edm:Role Attribute
11.2.3 The edm:Multiplicity Attribute
11.3 The edm:OnDelete Element
11.4 The edm:ReferentialConstraint Element
11.5 The edm:Principal Element
11.6 The edm:Dependent Element
11.7 The edm:PropertyRef Element
12Model Functions
12.1 The edm:Function Element
12.1.1 The edm:ReturnType Attribute
12.2 The edm:Parameter Element
12.3 The edm:ReturnType Element
13Entity Container Constructs
13.1 The edm:EntityContainer Element
13.2 The edm:EntitySet Element
13.3 The edm:AssociationSet Element
13.3.1 The edm:End Element
13.4 The edm:FunctionImport Element
13.4.1 The edm:ReturnType Attribute
13.4.2 The edm:EntitySet Attribute
13.4.3 The edm:EntitySetPath Attribute
13.4.4 The edm:IsSideEffecting Attribute
13.4.5 The edm:IsBindable Attribute
13.4.6 The edm:IsComposable Attribute
13.5 The edm:ReturnType Element
13.6 The edm:Parameter Element
13.6.1 The edm:Type Attribute
13.6.2 The edm:Mode Attribute
13.6.3 Parameter Facets
14Vocabulary Concepts
15Vocabulary Terms
15.1 edm:EntityType and edm:ComplexType as Type Terms
15.2 The edm:ValueTerm Element
16Vocabulary Annotations
16.1 The edm:Annotations Element
16.2 The edm:TypeAnnotation Element
16.3 The edm:PropertyValue Element
16.4 The edm:ValueAnnotation Element
16.5 The edm:Qualifier Attribute
17Vocabulary Expressions
17.1 Constant Expressions
17.1.1 The edm:Binary Constant Expression
17.1.2 The edm:Bool Constant Expression
17.1.3 The edm:DateTime Constant Expression
17.1.4 The edm:DateTimeOffset Constant Expression
17.1.5 The edm:Decimal Constant Expression
17.1.6 The edm:Float Constant Expression
17.1.7 The edm:Guid Constant Expression
17.1.8 The edm:Int Constant Expression
17.1.9 The edm:String Constant Expression
17.1.10 The edm:Time Constant Expression
17.2 Dynamic Expressions
17.2.1 The edm:Apply Expression
17.2.2 The edm:AssertType Expression
17.2.3 The edm:Collection Expression
17.2.4 The edm:EntitySetReference Expression
17.2.5 The edm:EnumMemberReference Expression
17.2.6 The edm:FunctionReference Expression
17.2.7 The edm:If Expression
17.2.8 The edm:IsType Expression
17.2.9 The edm:LabeledElement Expression
17.2.10 The edm:LabeledElementReference Expression
17.2.11 The edm:Null Expression
17.2.12 The edm:ParameterReference Expression
17.2.13 The edm:Path Expression
17.2.14 The edm:PropertyReference Expression
17.2.15 The edm:Record Expression
17.2.16 The edm:ValueTermReference Expression
18CSDL Examples
18.1 Products and Categories Example
18.2 Annotated Customers and Orders Example
19Informative XSD for CSDL
20Attribute Values
20.1 Namespace
20.2 SimpleIdentifier
20.3 QualifiedName
20.4 AnyTypeName
20.5 AnySingleTypeName
20.6 AnyKeylessTypeName
20.7 SingleEntityTypeName
20.8 SingleComplexTypeName
20.9 Boolean
21Conformance
Appendix A.Acknowledgments
Appendix B.Non-Normative Text
B.1 Subsidiary section
B.1.1 Sub-subsidiary section
Appendix C.Revision History
1Introduction...... 8
1.1 Terminology...... 8
1.2 Normative References...... 8
1.3 Non-Normative References...... 8
2Common 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
2.3 Data Service Metadata Namespace...... 9
3Common 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...... 11
3.5 Primitive Types...... 11
4Entity Model Wrapper Constructs...... 13
4.1 The edmx:Edmx Element...... 13
4.1.1 The Version Attribute...... 13
4.2 The edmx:DataServices Element...... 13
4.2.1 The metadata:DataServiceVersion Attribute...... 13
4.3 The edmx:Reference Element...... 13
4.3.1 The edmx:Url Attribute...... 14
4.4 The edmx:AnnotationsReference Element...... 14
4.4.1 The edmx:Url Attribute...... 14
4.5 The edmx:Include Element...... 14
4.5.1 The edmx:TermNamespace Attribute...... 15
4.5.2 The edmx:Qualifier Attribute...... 15
5Schema Constructs...... 16
5.1 The edm:Schema Element...... 16
5.1.1 The edm:Namespace Attribute...... 16
5.1.2 The edm:Alias Attribute...... 16
5.2 The edm:Using Element...... 16
5.2.1 The edm:Namespace Attribute...... 17
5.2.2 The edm:Alias Attribute...... 17
6Properties...... 18
6.1 The edm:Property Element...... 18
6.1.1 The edm:Name Attribute...... 18
6.2 The edm:Type Attribute...... 18
6.3 Property Facets...... 18
6.3.1 The edm:Nullable Attribute...... 19
6.3.2 The edm:MaxLength Attribute...... 19
6.3.3 The edm:FixedLength Attribute...... 19
6.3.4 The edm:Precision Attribute...... 19
6.3.5 The edm:Scale Attribute...... 19
6.3.6 The edm:Unicode Attribute...... 19
6.3.7 The edm:Collation Attribute...... 19
6.3.8 The edm:SRID Attribute...... 20
6.3.9 The edm:DefaultValue Attribute...... 20
6.3.10 The edm:ConcurrencyMode Attribute...... 20
7Entity Type Constructs...... 21
7.1 The edm:EntityType Element...... 21
7.1.1 The edm:Name Attribute...... 21
7.1.2 The edm:BaseType Attribute...... 22
7.1.3 The edm:Abstract Attribute...... 22
7.1.4 The edm:OpenType Attribute...... 22
7.1.5 The metadata:HasStream Attribute...... 22
7.2 The edm:Key Element...... 22
7.3 The edm:PropertyRef Element...... 23
7.4 The edm:NavigationProperty Element...... 23
7.4.1 The edm:Name Attribute...... 23
7.4.2 The edm:Relationship Attribute...... 23
7.4.3 The edm:ToRole Attribute...... 23
7.4.4 The edm:FromRole Attribute...... 24
7.4.5 The edm:ContainsTarget Attribute...... 24
8Complex Type Constructs...... 25
8.1 The edm:ComplexType Element...... 25
9Enumeration Type Constructs...... 26
9.1 The edm:EnumType Element...... 26
9.1.1 The edm:UnderlyingType Attribute...... 26
9.1.2 The edm:IsFlags Attribute...... 26
9.2 The edm:Member Element...... 26
9.2.1 The edm:Name Attribute...... 26
9.2.2 The edm:Value Attribute...... 27
10Other Type Constructs...... 28
10.1 Collection Types...... 28
10.1.1 The edm:CollectionType Element...... 28
10.2 The edm:TypeRef Element...... 28
10.3 Reference Types...... 28
10.3.1 The edm:ReferenceType Element...... 29
10.4 Row Types...... 29
10.4.1 The edm:RowType Element...... 29
11Association Constructs...... 30
11.1 The edm:Association Element...... 30
11.2 The edm:End Element...... 30
11.2.1 The edm:Type Attribute...... 30
11.2.2 The edm:Role Attribute...... 30
11.2.3 The edm:Multiplicity Attribute...... 30
11.3 The edm:OnDelete Element...... 30
11.4 The edm:ReferentialConstraint Element...... 31
11.5 The edm:Principal Element...... 31
11.6 The edm:Dependent Element...... 31
11.7 The edm:PropertyRef Element...... 31
12Model Functions...... 33
12.1 The edm:Function Element...... 33
12.1.1 The edm:ReturnType Attribute...... 33
12.2 The edm:Parameter Element...... 33
12.3 The edm:ReturnType Element...... 34
13Entity Container Constructs...... 35
13.1 The edm:EntityContainer Element...... 36
13.2 The edm:EntitySet Element...... 36
13.3 The edm:AssociationSet Element...... 36
13.3.1 The edm:End Element...... 36
13.4 The edm:FunctionImport Element...... 36
13.4.1 The edm:ReturnType Attribute...... 37
13.4.2 The edm:EntitySet Attribute...... 37
13.4.3 The edm:EntitySetPath Attribute...... 37
13.4.4 The edm:IsSideEffecting Attribute...... 37
13.4.5 The edm:IsBindable Attribute...... 37
13.4.6 The edm:IsComposable Attribute...... 38
13.5 The edm:ReturnType Element...... 38
13.6 The edm:Parameter Element...... 38
13.6.1 The edm:Type Attribute...... 38
13.6.2 The edm:Mode Attribute...... 38
13.6.3 Parameter Facets...... 38
14Vocabulary Concepts...... 39
15Vocabulary Terms...... 40
15.1 edm:EntityType and edm:ComplexType Terms...... 40
15.2 The edm:ValueTerm Element...... 40
16Vocabulary Annotations...... 41
16.1 The edm:Annotations Element...... 41
16.2 The edm:TypeAnnotation Element...... 41
16.3 The edm:PropertyValue Element...... 42
16.4 The edm:ValueAnnotation Element...... 42
16.5 The edm:Qualifier Attribute...... 42
17Vocabulary Expressions...... 43
17.1 Constant Expressions...... 43
17.1.1 The edm:Binary Constant Expression...... 43
17.1.2 The edm:Bool Constant Expression...... 43
17.1.3 The edm:DateTime Constant Expression...... 44
17.1.4 The edm:DateTimeOffset Constant Expression...... 44
17.1.5 The edm:Decimal Constant Expression...... 44
17.1.6 The edm:Float Constant Expression...... 44
17.1.7 The edm:Guid Constant Expression...... 45
17.1.8 The edm:Int Constant Expression...... 45
17.1.9 The edm:String Constant Expression...... 45
17.1.10 The edm:Time Constant Expression...... 45
17.2 Dynamic Expressions...... 46
17.2.1 The edm:Apply Expression...... 46
17.2.2 The edm:AssertType Expression...... 46
17.2.3 The edm:Collection Expression...... 46
17.2.4 The edm:EntitySetReference Expression...... 47
17.2.5 The edm:EnumMemberReference Expression...... 47
17.2.6 The edm:FunctionReference Expression...... 47
17.2.7 The edm:If Expression...... 47
17.2.8 The edm:IsType Expression...... 48
17.2.9 The edm:LabeledElement Expression...... 48
17.2.10 The edm:LabeledElementReference Expression...... 48
17.2.11 The edm:Null Expression...... 49
17.2.12 The edm:ParameterReference Expression...... 49
17.2.13 The edm:Path Expression...... 49
17.2.14 The edm:PropertyReference Expression...... 50
17.2.15 The edm:Record Expression...... 50
17.2.16 The edm:ValueTermReference Expression...... 50
18CSDL Examples...... 51
18.1 Products and Categories Example...... 51
18.2 Annotated Customers and Orders Example...... 52
19Informative XSD for CSDL...... 54
20Attribute Values...... 74
20.1 Namespace...... 74
20.2 SimpleIdentifier...... 74
20.3 QualifiedName...... 74
20.4 AnyTypeName...... 74
20.5 AnySingleTypeName...... 74
20.6 AnyKeylessTypeName...... 74
20.7 SingleEntityTypeName...... 74
20.8 Boolean...... 74
20.9 NonNegativeIntegral...... 74
20.10 NonNegativeInt32...... 74
20.11 PathString...... 75
20.12 xsBoolean...... 75
20.13 xsDateTime...... 75
20.14 xsDecimal...... 75
20.15 xsDouble...... 75
20.16 xsGuid...... 75
20.17 xsHexBinary...... 75
20.18 xsInteger...... 75
20.19 xsString...... 75
20.20 xsTime...... 75
21Conformance...... 76
Appendix A.Acknowledgments...... 77
Appendix B.Non-Normative Text...... 78
B.1 Subsidiary section...... 78
B.1.1 Sub-subsidiary section...... 78
Appendix C.Revision History...... 79
odata-csdl-v1.0-wd01Working Draft 0103 September 201228 August 2012
Standards Track DraftCopyright © OASIS Open 2012. All Rights Reserved.Page 1 of 1
1Introduction
OData services are described in terms of an Entity Data Model (EDM). The Common Schema Definition Language (CSDL) defines an XMLrepresentation 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].
An OData service SHOULD provide a CSDL description of its entity model when a client requests a description of the entity model by sending a GET request to <serviceRoot>/$metadata. $metadata MUST wrap the CSDL document in an EDMX wrapper.
1.1Terminology
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].
1.2Normative 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-Core]OData Protocol 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.
1.3Non-Normative References
[EntitySQL]
2Common 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.
2.1Entity 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:
ISSUEODATA-19: Is this permissible by OASIS rules, or do we have to introduce a new (alternative) namespace following the OASIS naming conventions?
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.2Entity 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:
- CSDL version 4.0:
ISSUEODATA-17andODATA-19.
In this specification the namespace prefix edm is used to represent the Entity Data Model namespace, however the prefix name is not prescriptive.
2.3Data Service Metadata Namespace
Elements and attributes specific to how the entity model is exposed as an OData Service are qualified with the Data Service Metadata namespace:
ISSUEODATA-19: Is this permissible by OASIS rules, or do we have to introduce a new (alternative) namespace following the OASIS naming conventions?
In this specification the namespace prefix metadata is used to represent the Data Service Metadata namespace, however the prefix name is not prescriptive.
3Common 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.
3.1Nominal Types
A nominal type has a name. The name MUST be aSimpleIdentifier. In combination with a Namespacethisproduces a fully qualified name of the formQualifiedName. The QualifiedNameMUST 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:
<Schema
xmlns=
xmlns:m=
xmlns:d=
Namespace="org.example" Alias="example">
<ComplexType Name="Address">...</ComplexType>
</Schema>
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
3.2Structural 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. Rowtypes 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.3The edm:Documentation Element
The edm:Documentation element allows service authors to provide documentation for most model elements.