OASIS OData Common Schema Definition Language (CSDL) Version 1.0. Part 3: CSDL

Working Draft 01

092October 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:
  • 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:

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

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 edmx: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 edm: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 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

odata-core-v1.0-wd01-part3-csdlWorking Draft 0109 October 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].

If a client requests a description of the entity model by sending a GET request to <serviceRoot>/$metadata, an OData service SHOULD provide a CSDL description of its entity model and in this case MUST place that CSDL document inside an EDMX wrapper[R1].

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:

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:

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.

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.

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:Association
  • edm:AssociationSet
  • edm:Collection
  • edm:ComplexType
  • edm:End (Association)
  • edm:End (AssociationSet)
  • edm:EntityContainer
  • edm:EntitySet
  • edm:EntityType
  • edm:EnumType
  • edm:Function
  • 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:

<EntityType Name="Product">
<Documentation>
<Summary>Product names, suppliers, prices, and units in stock.</Summary>
<LongDescription>...</LongDescription>
</Documentation>
...
</EntityType>

3.4Vocabulary 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.

3.5Primitive Types

Structural types are composed of other structural types and primitive types. CSDL defines the following fully qualified primitive types:

  • Edm.Binary
  • Edm.Boolean
  • Edm.Byte
  • Edm.DateTime
  • Edm.Decimal
  • Edm.Double
  • Edm.Single
  • Edm.Guid
  • Edm.Int16
  • Edm.Int32
  • Edm.Int64
  • Edm.SByte
  • Edm.String
  • Edm.Time
  • Edm.DateTimeOffset
  • Edm.Geography
  • Edm.GeographyPoint
  • Edm.GeographyLineString
  • Edm.GeographyPolygon
  • Edm.GeographyMultiPoint
  • Edm.GeographyMultiLineString
  • Edm.GeographyMultiPolygon
  • Edm.GeographyCollection
  • Edm.Geometry
  • Edm.GeometryPoint
  • Edm.GeometryLineString
  • Edm.GeometryPolygon
  • Edm.GeometryMultiPoint
  • Edm.GeometryMultiLineString
  • Edm.GeometryMultiPolygon
  • Edm.GeometryCollection
  • Edm.Stream

ISSUE ODATA-52: Define meaning of these primitive types: allowed values, allowed facets, …

4Entity 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 <serviceRoot>/$metadata[R2]Entity Model Wrapper serves as the aggregation root for the schemas that describe the entity model exposed by the OData Service.

4.1The edmx:Edmx Element

An OData service exposes a single entity model. A CSDL description of the entity model can be requested from $metadata.[R3]

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 element and the edmx:DataServices element:

<edmx:Edmx xmlns:edmx="

Version="1.0">
<edmx:DataServicesDataServiceVersion="4.0">
<Schema ... />
</edmx:DataServices>
</edmx:Edmx>

4.1.1The 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 <majorversion>.<minorversion>. This version of the specification defines version 1.0 of the EDMX Wrapper.

4.2The edmx:DataServices Element

The edmx:DataServices element contains zero or more edm:Schema elements which define the schema(s) exposed by the OData service.

4.2.1The edmx:DataServiceVersionAttribute

The edmx:DataServiceVersion attribute describes the version of OData protocol required to consume the service. This version of the specification defines the data service version value4.0. The values1.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.

4.3The 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:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<edmx:Edmx xmlns:edmx="
Version="1.0">
<edmx:Reference Url=" />
<edmx:Reference Url=" />
<edmx:DataServices ...>
</edmx:Edmx>

4.3.1The edmx:Url Attribute

The edmx:Reference element MUST specify an edmx: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.4The 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.