OASIS OData Version 1.0 Part 3: CSDL

Working Draft 01

1107February 2013

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

3.6 Built-In Abstract 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 DataServiceVersion Attribute

4.3 The edmx:Reference Element

4.3.1 The Url Attribute

4.4 The edmx:AnnotationsReference Element

4.4.1 The Url Attribute

4.5 The edmx:Include Element

4.5.1 The TermNamespace Attribute

4.5.2 The Qualifier Attribute

5Schema Constructs

5.1 The edm:Schema Element

5.1.1 The Namespace Attribute

5.1.2 The Alias Attribute

5.2 The edm:Using Element

5.2.1 The Namespace Attribute

5.2.2 The Alias Attribute

6Properties

6.1 The edm:Property Element

6.1.1 The Name Attribute

6.1.2 The Type Attribute

6.2 Property Facets

6.2.1 The Nullable Attribute

6.2.2 The MaxLength Attribute

6.2.3 The FixedLength Attribute

6.2.4 The Precision Attribute

6.2.5 The Scale Attribute

6.2.6 The Unicode Attribute

6.2.7 The Collation Attribute

6.2.8 The SRID Attribute

6.2.9 The DefaultValue Attribute

6.2.10 The ConcurrencyMode Attribute

7Entity Type Constructs

7.1 The edm:EntityType Element

7.1.1 The Name Attribute

7.1.2 The BaseType Attribute

7.1.3 The Abstract Attribute

7.1.4 The OpenType Attribute

7.1.5 The HasStream Attribute

7.2 The edm:Key Element

7.2.1 The edm:PropertyRef Element

7.3 The edm:NavigationProperty Element

7.3.1 The Name Attribute

7.3.2 The Type Attribute

7.3.3 The Nullable Attribute

7.3.4 The Partner Attribute

7.3.5 The ContainsTarget Attribute

7.3.6 The edm:ReferentialConstraint Element

7.3.7 The edm:PropertyRef Element

7.3.8 The edm:OnDelete Element

8Complex Type Constructs

8.1 The edm:ComplexType Element

8.1.1 The BaseType Attribute

8.1.2 The Abstract Attribute

9Enumeration Type Constructs

9.1 The edm:EnumType Element

9.1.1 The UnderlyingType Attribute

9.1.2 The IsFlags Attribute

9.2 The edm:Member Element

9.2.1 The Name Attribute

9.2.2 The Value Attribute

10Functions and Actions

10.1 The edm:Function Element

10.1.1 The Name Attribute

10.1.2 The ReturnType Attribute

10.1.3 The IsSideEffecting Attribute

10.1.4 The IsBindable Attribute

10.1.5 The IsAlwaysBindable Attribute

10.1.6 The IsComposable Attribute

10.1.7 The EntitySetPath Attribute

10.2 The edm:ReturnType Element

10.2.1 The Type Attribute

10.3 The edm:Parameter Element

10.3.1 The Name Attribute

10.3.2 The Type Attribute

10.3.3 Parameter Facets

11Other Type Constructs

11.1 Collection Types

11.2 The edm:CollectionType Element

11.2.1 The ElementType Attribute

11.3 The edm:TypeRef Element

11.3.1 The Type Attribute

11.4 Reference Types

11.4.1 The edm:ReferenceType Element

11.4.1.1 The Type Attribute

11.5 The edm:TypeDefinition Element

11.5.1 The Name Attribute

11.5.2 The UnderlyingType Attribute

11.5.3 TypeDefinition Facets

12Entity Container Constructs

12.1 The edm:EntityContainer Element

12.1.1 The Name Attribute

12.1.2 The IsDefaultEntityContainer Attribute

12.1.3 The Extends Attribute

12.2 The edm:EntitySet Element

12.2.1 The Name Attribute

12.2.2 The EntityType Attribute

12.3 The edm:NavigationPropertyBinding Element

12.3.1 The Path Attribute

12.3.2 The EntitySet Attribute

12.4 The edm:Entity Element

12.4.1 The Name Attribute

12.4.2 The Type Attribute

12.5 The edm:FunctionImport Element

12.5.1 The Name Attribute

12.5.2 The Function Attribute

12.5.3 The EntitySet Attribute

13Vocabulary Concepts

14Vocabulary Terms

14.1 The edm:Term Element

14.1.1 The Name Attribute

14.1.2 The Type Attribute

14.1.3 The DefaultValue Attribute

14.1.4 The AppliesTo Attribute

14.1.5 Term Facets

15Vocabulary Annotations

15.1 The edm:Annotations Element

15.1.1 The Target Attribute

15.1.2 The Qualifier Attribute

15.2 The edm:Annotation Element

15.2.1 The Term Attribute

15.2.2 The Qualifier Attribute

16Vocabulary Expressions

16.1 Constant Expressions

16.1.1 The edm:Binary Constant Expression

16.1.2 The edm:Bool Constant Expression

16.1.3 The edm:Date Constant Expression

16.1.4 The edm:DateTimeOffset Constant Expression

16.1.5 The edm:Decimal Constant Expression

16.1.6 The edm:Duration Constant Expression

16.1.7 The edm:EnumMember Constant Expression

16.1.8 The edm:Float Constant Expression

16.1.9 The edm:Guid Constant Expression

16.1.10 The edm:Int Constant Expression

16.1.11 The edm:String Constant Expression

16.1.12 The edm:TimeOfDay Constant Expression

16.2 Dynamic Expressions

16.2.1 The edm:Apply Expression

16.2.1.1 The odata.concat Client-Side Function

16.2.2 The edm:AssertType Expression

16.2.3 The edm:Collection Expression

16.2.4 The edm:If Expression

16.2.5 The edm:IsType Expression

16.2.6 The edm:LabeledElementReference Expression

16.2.7 The edm:Null Expression

16.2.8 The edm:LabeledElement Expression

16.2.9 The edm:NavigationPropertyPath Expression

16.2.10 The edm:Path Expression

16.2.11 The edm:PropertyPath Expression

16.2.12 The edm:Record Expression

16.2.12.1 The Type Attribute

16.2.13 The edm:PropertyValue Element

17CSDL Examples

17.1 Products and Categories Example

17.2 Annotated Customers and Orders Example

18Informative XSD for CSDL

19Attribute Values

19.1 Namespace

19.2 SimpleIdentifier

19.3 QualifiedName

19.4 AnyTypeName

19.5 AnySingleTypeName

19.6 AnyKeylessTypeName

19.7 SingleEntityTypeName

19.8 SingleComplexTypeName

19.9 Boolean

20Conformance

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 011107 February 2013

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.

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

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. An XML document using these namespaces and having an edmx:Edmx root element will be called a CSDL document.

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:

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

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:Annotation
  • edm:Annotations
  • edm:Apply
  • edm:AssertType
  • edm:Collection
  • edm:ComplexType
  • edm:Entity
  • edm:EntityContainer
  • edm:EntitySet
  • edm:EntityType
  • edm:EnumType
  • edm:Function
  • edm:FunctionImport
  • edm:If
  • edm:IsType
  • edm:LabeledElement
  • edm:Member
  • edm:NavigationProperty
  • edm:Null
  • edm:OnDelete
  • edm:Parameter
  • edm:Property
  • edm:PropertyValue
  • edm:Record
  • edm:ReferenceType
  • edm:ReferentialConstraint
  • edm:Schema
  • edm:Term
  • Edm:TypeDefinition
  • edm:TypeRef
  • edm:Using

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:Annotation element.

A model element MUST NOT specify more than one annotation for a given value combination of the Termand 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:

Type / Meaning
Edm.Binary / Fixed- or variable- length binary data
Edm.Boolean / Binary-valued logic
Edm.Byte / Unsigned 8-bit integer
Edm.Date / Date 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.Duration / Signed duration in days, hours, minutes, and (sub)seconds
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.TimeOfDay / Clock time 0-23:59:59.999999999999
Edm.Geography / Abstract base type for all Geography types
Edm.GeographyPoint / A point in a round-earth coordinate system
Edm.GeographyLineString / Linestring 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 linestrings 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 / Linestring 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 linestrings 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.2.

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.

3.6Built-In Abstract Types

Models may use the following built-in abstract types:

  • Edm.PrimitiveType
  • Edm.ComplexType
  • Edm.EntityType

Conceptually, these are the abstract base types for primitive types, complex types, and entity types, respectively, and can be used anywhere a corresponding concrete type can be used, except:

  • Edm.EntityTypecan’t be used as the type of a named entity in an entity container because it doesn’t define a structure, which defeats the purpose of a named entity.
  • Edm.EntityTypecan’t be used as the type of an entity set because all entities in an entityset must have the same key fields to uniquely identifythem within the set.
  • Edm.EntityType and Edm.ComplexType cannot be the base type of an entity type or complex type.
  • Edm.PrimitiveType can’t be used as the type of a key property of an entity type.
  • Edm.PrimitiveType can’t be used as the underlying type of a type definition.
  • Collection(Edm.PrimitiveType) can’t be used as the type of a property.

Examples of where these abstract base types can be used:

  • As the type of a navigation property (Edm.EntityType or Collection(Edm.EntityType))
  • As the type of a property (Edm.ComplexType, Edm.PrimitiveType, Collection(Edm.ComplexType))
  • As a parameter type
  • As a function returntype
  • As the type of a vocabulary term[MJP1]

Note that this list of examples is incomplete.

Note that you can cast the results of a function, for example, to a particular type in order to access its properties (i.e. in a $filter, $expand, or $orderby). For example:

~/NameSpace.FunctionReturningAnyEntityType()/Model.Customer?$filter=FirstName eq 'Ralf'

This filters the results to only those that match the specified type and casts the results to that type.

Vocabulary terms may in addition use

  • Edm.Property
  • Edm.NavigationProperty

as the type of a primitive term, or the type of a property of a complex type that is exclusively used as the type of a term.