oasis

OData Vocabularies Version 4.0

Committee Specification Draft 01 /
Public Review Draft 01

08 December 2016

Specification URIs

This version:

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.docx (Authoritative)

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.html

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.pdf

Previous version:

N/A

Latest version:

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.docx (Authoritative)

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html

http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.pdf

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Ralf Handl (ralf.handl@sap.com), SAP SE

Ram Jeyaraman (Ram.Jeyaraman@microsoft.com), Microsoft

Editors:

Michael Pizzo (mikep@microsoft.com), Microsoft

Ralf Handl (ralf.handl@sap.com), SAP SE

Ram Jeyaraman (Ram.Jeyaraman@microsoft.com), Microsoft

Related work:

This specification is related to:

·         OData vocabulary components:

o    OData Core Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.xml.

o    OData Measures Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Measures.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Measures.V1.xml.

o    OData Capabilities Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Capabilities.V1.xml.

o    OData Validation Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Validation.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Validation.V1.xml.

o    OData Aggregation Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Aggregation.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Aggregation.V1.xml.

o    OData Authorization Vocabulary. Description: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Authorization.V1.md. XML schema: https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Authorization.V1.xml.

·         OData Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. A multi-part Work Product which includes:

o    OData Version 4.01. Part 1: Protocol. Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html.

o    OData Version 4.01. Part 2: URL Conventions. Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html.

o    OData Version 4.01. Part 3: Common Schema Definition Language (CSDL). Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part3-csdl.html.

·         OData Common Schema Definition Language (CSDL) XML Representation Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest version: http://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html.

·         OData JSON Format Version 4.01. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. Latest version: http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html.

·         OData Extension for Data Aggregation Version 4.0. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, and Martin Zurmuehl. Latest version: http://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html.

Abstract:

This prose specification describes a set of OData vocabularies maintained by the OASIS OData Technical Committee. These vocabulary components are continuously evolved. The latest work-in-progress revisions are available at the odata-vocabularies OASIS TC GitHub repository: https://github.com/oasis-tcs/odata-vocabularies.

Status:

This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical.)

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/odata/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/odata/ipr.php).

Citation format:

When referencing this specification the following citation format should be used:

[OData-Vocabularies-v4.0]

OData Vocabularies Version 4.0. Edited by Ralf Handl, Michael Pizzo, and Ram Jeyaraman. 08 December 2016. OASIS Committee Specification Draft 01 / Public Review Draft 01. http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/csprd01/odata-vocabularies-v4.0-csprd01.html. Latest version: http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html.

Notices

Copyright © OASIS Open 2016. 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.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1        Introduction. 6

1.1 Terminology. 6

1.2 Normative References. 6

1.3 Non-Normative References. 6

2        Core Vocabulary. 7

3        Capabilities Vocabulary. 9

4        Measures Vocabulary. 11

5        Validation Vocabulary. 12

6        Aggregation Vocabulary. 13

7        Authorization Vocabulary. 14

8        Conformance. 15

Appendix A. Acknowledgments. 16

Appendix B. Revision History. 17

 


1      Introduction

OData provides the ability to decorate model elements of a schema and instances of data with descriptive elements called annotations. Annotations can be used to specify additional facts about an element, such as whether it is read-only, or to define a common concept, such as a person or a movie. Annotations consist of a term (the namespace-qualified name of the annotation being applied), a target (the element to which the term is applied), and a value. A set of related annotation terms with a common namespace comprises a Vocabulary. Shared vocabularies provide a powerful extensibility point for OData. Refer to the [OData-Protocol] and [OData-CSDLXML] specifications for more information on the use of vocabularies.

This prose specification describes a set of OData vocabularies maintained by the OASIS OData Technical Committee. It is one component of a Work Product that also includes the various vocabulary components. These vocabulary components are continuously evolved, the latest work-in-progress revisions are available at [OData-Vocabs].

Other OData vocabularies may be created, shared, and maintained outside of this work product.

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

1.2 Normative References

[RFC2119]                Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.

[OData-CorVoc]        OData Vocabularies Version 4.0: Core Vocabulary.
See link in “Related work” section on cover page.

[OData-CapVoc]       OData Vocabularies Version 4.0: Capabilities Vocabulary.
See link in “Related work” section on cover page.

[OData-MeaVoc]       OData Vocabularies Version 4.0: Measures Vocabulary.
See link in “Related work” section on cover page.

[OData-ValVoc]        OData Vocabularies Version 4.0: Validation Vocabulary.
See link in “Related work” section on cover page.

[OData-AggVoc]       OData Vocabularies Version 4.0: Aggregation Vocabulary.
See link in “Related work” section on cover page.

[OData-AuthVoc]      OData Vocabularies Version 4.0: Authorization Vocabulary.
See link in “Related work” section on cover page.

[OData-Protocol]      OData Version 4.01 Part 1: Protocol.
See link in “Related work” section on cover page.

[OData-CSDLXML]   OData Common Schema Definition Language (CSDL) XML Representation Version 4.01. See link in "Related work" section on cover page

1.3 Non-Normative References

[OData-Vocabs]      odata-vocabularies OASIS TC GitHub repository
https://github.com/oasis-tcs/odata-vocabularies.

2      Core Vocabulary

The Core vocabulary [OData-CorVoc] contains a set of basic annotation terms describing behavioral aspects along with annotation terms that can be used to define other vocabularies.

Vocabulary Namespace: Org.OData.Core.V1

Term Name

Term Description

AcceptableMediaTypes

Lists the MIME types acceptable for the annotated entity type marked with HasStream="true" or the annotated stream property

AdditionalProperties

Instances of this type may contain properties in addition to those declared in $metadata

If specified as false clients can assume that instances will not contain dynamic properties, irrespective of the value of the OpenType attribute.

AlternateKeys

Communicates available alternate keys

AutoExpand

The service will automatically expand this navigation property even if not requested with $expand

AutoExpandReferences

The service will automatically expand this navigation property as entity references even if not requested with $expand=.../$ref

Computed

A value for this property is generated on both insert and update

ContentID

A unique identifier for nested entities within a request.

ConventionalIDs

Entity-ids follow OData URL conventions

DefaultNamespace

Functions, actions and types in this namespace can be referenced in URLs with or without namespace- or alias- qualification.

Data Modelers should ensure uniqueness of schema children across all default namespaces, and should avoid naming bound functions, actions, or derived types with the same name as a structural or navigational property of the type.

DereferenceableIDs

Entity-ids are URLs that locate the identified entity

Description

A brief description of a model element

Immutable

A value for this non-key property can be provided on insert and remains unchanged on update

IsLanguageDependent

Properties and terms annotated with this term are language-dependent

IsMediaType

Properties and terms annotated with this term MUST contain a valid MIME type

IsURL

Properties and terms annotated with this term MUST contain a valid URL

LongDescription

A lengthy description of a model element

MayImplement

A collection of qualified type names outside of the type hierarchy that instances of this type might be addressable as by using a type segment.

MediaType

The media type of a binary resource

Messages

Instance annotation for warning and info messages

NumericValueException

Used in place of a property value to annotate a property whose value is not representable according to its numeric type.

ODataVersions

A space-separated list of supported versions of the OData Protocol. Note that 4.0 is implied by 4.01 and does not need to be separately listed.

OptimisticConcurrency

Data modification requires the use of ETags. A non-empty collection contains the set of properties that are used to compute the ETag.

Ordered

Collection has a stable order. Ordered collections of primitive or complex types can be indexed by ordinal.

Permissions

Permissions for accessing a resource

PositionalInsert

Items can be inserted at a given ordinal index.

RequiresType

Terms annotated with this term can only be applied to elements that have a type that is identical to or derived from the given type name

ResourcePath

Resource path for entity container child, can be relative to xml:base and the request URL

SchemaVersion

Service-defined value representing the version of the schema. Services MAY use semantic versioning, but clients MUST NOT assume this is the case.

 

3      Capabilities Vocabulary

The Capabilities vocabulary [OData-CapVoc] provides a way for service authors to describe certain capabilities of an OData Service. There are some capabilities that are strongly recommended for services to support even though they are optional. For example, support for $top and $skip. Supporting these query options helps with performance of a service and are essential. Such capabilities are assumed default capabilities of an OData service even in the case that a capabilities annotation does not exist. Services can use the capabilities annotations to specify lack of support for such assumed features, as well as to explicitly specify such features are supported.

Vocabulary Namespace: Org.OData.Capabilities.V1

Term Name

Term Description

AcceptableEncodings

List of acceptable compression methods for ($batch) requests, e.g. gzip

AsynchronousRequestsSupported

Service supports the asynchronous request preference

BatchContinueOnErrorSupported

Service supports the continue on error preference. Supports $batch requests. Services that apply the BatchContinueOnErrorSupported term should also specify the ContinueOnErrorSupported property from the BatchSupport term.

BatchSupport

Batch Support for the service

BatchSupported

Supports $batch requests. Services that apply the BatchSupported term should also apply the more comprehensive BatchSupport term.

CallbackSupported

Supports callbacks for the specified protocols

ChangeTracking

Change tracking capabilities of this service or entity set

ConformanceLevel

The conformance level achieved by this service

CountRestrictions

Restrictions on /$count path suffix and $count=true system query option

CrossJoinSupported

Supports cross joins for the entity sets in this container

DeepInsertSupport

Deep Insert Support for the service

DeleteRestrictions

Restrictions on delete operations

ExpandRestrictions

Restrictions on $expand expressions

FilterFunctions

List of functions and operators supported in $filter

FilterRestrictions

Restrictions on $filter expressions

IndexableByKey

Supports key values according to OData URL conventions

InsertRestrictions

Restrictions on insert operations

IsolationSupported

Supported odata.isolation levels

NavigationRestrictions

Restrictions on navigating properties according to OData URL conventions

SearchRestrictions

Restrictions on $search expressions

SkipSupported

Supports $skip

SortRestrictions

Restrictions on $orderby expressions

SupportedFormats

Media types of supported formats, including format parameters

SupportedMetadataFormats

Media types of supported formats for $metadata, including format parameters

TopSupported

Supports $top

UpdateRestrictions

Restrictions on update operations

 

4      Measures Vocabulary

The Measures vocabulary [OData-MeaVoc] provides a set of terms describing monetary amounts and measured quantities.

Vocabulary Namespace: Org.OData.Measures.V1

Term Name

Term Description

ISOCurrency

The currency for this monetary amount as an ISO 4217 currency code

Scale

The number of significant decimal places in the scale part (less than or equal to the number declared in the Scale facet)

Unit

The unit of measure for this measured quantity, e.g. cm for centimeters or % for percentages

 

5      Validation Vocabulary

The Validation vocabulary [OData-ValVoc] provides a set of terms describing validation rules.

Vocabulary Namespace: Org.OData.Validation.V1

Term Name

Term Description

AllowedValues

A collection of valid values for the annotated property, parameter, or type definition

Exclusive

Tags a Minimum or Maximum as exclusive, i.e. an open interval boundary.

Maximum

Maximum value that a property, parameter, or term can have.

Minimum

Minimum value that a property, parameter, or term can have.

MultipleOf

The value of the annotated property, parameter, or term must be an integer multiple of this positive value. For temporal types, the value is measured in seconds.

Pattern

The pattern that a string property, parameter, or term must match. This SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect.

 

6      Aggregation Vocabulary

The Aggregation vocabulary [OData-AggVoc] provides a set of terms describing which data in a given entity model can be aggregated, and how.

Vocabulary Namespace: Org.OData.Aggregation.V1

Term Name

Term Description

Aggregatable

This property can be used in the aggregate transformation

ApplySupported

This structured type or entity container supports the $apply system query option

AvailableOnAggregates

This action or function is available on aggregated entities if the RequiredProperties are still defined

ContextDefiningProperties

The annotated property or custom aggregate is only well-defined in the context of these properties

The context-defining properties need either be part of the result entities, or be restricted to a single value by a pre-filter operation. Examples are postal codes within a country, or monetary amounts whose context is the unit of currency.

CustomAggregate

Dynamic property that can be used in the aggregate transformation

This term MUST be applied with a Qualifier, the Qualifier value is the name of the dynamic property. The value of the annotation MUST be the qualified name of a primitive type. The aggregated values will be of that type.

Groupable

This property can be used in the groupby transformation

LeveledHierarchy

Defines a leveled hierarchy by defining an ordered list of properties in the hierarchy

RecursiveHierarchy

Defines a recursive hierarchy.

 

7      Authorization Vocabulary

The Authorization vocabulary [OData-AuthVoc] provides a set of terms describing a web authorization flow.

Vocabulary Namespace: Org.OData.Authorization.V1

Term Name

Term Description

Authorizations

Lists the methods available to authorize access to the annotated resource

 

8      Conformance

The syntax of the OData vocabularies MUST conform to the [OData-CSDLXML] format.

Appendix A. Acknowledgments

The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol], are gratefully acknowledged.

Appendix B. Revision History

Revision

Date

Editor

Changes Made

Working Draft 01

2016-02-25

Ram Jeyaraman

Initial version

Committee Specification Draft 01

2016-12-08

Ralf Handl

Documentation automatically extracted from XML source files