· 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

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