What follows is a proposed Capabilities Vocabulary that aims to provide a way for service authors to describe certain capabilities of an OData Service. We'd love to get your feedback!

-Mike Pizzo

Design Principles

There are many trade-offs that go into defining a vocabulary to describe capabilities of a system at varying levels. The following principles were factored in to the design of this vocabulary.

Keep it as simple as possible

This vocabulary aims to enable expression of most general capabilities without diving into complicated cases. The expectation is that an extension to this vocabulary can be designed to cover more complicated cases.

Reasonable defaults

Annotations are generally extensions to an OData service. Clients consuming an OData service should be able to continue to consume a service regardless of existence of capabilities annotations. However, existence of these annotations enable clients to understand more about the certain capabilities of a service.

There are some capabilities which are strongly recommended for services to support even though they are optional. Support for $top and $skip is a good example as supporting these query options helps with performance of a service and are essential. Such capabilities are assumed to be default capabilities of an OData service even in the case that a capabilities annotation doesn't exist. Capabilities annotations are mainly expected to be used to explicitly specify that a service doesn't support such capabilities. Capabilities annotations can as well be used to declaratively specify the support of such capabilities.

On the other hand, there are some capabilities that may not be appropriate for a given service (such as updatability), that a particular service many not reasonably be capable of supporting, or that a service may only be capable of supporting in varying degrees. $filter and $orderby may be such examples. This vocabulary aims to define terms to specify support or no support for such capabilities.

In the absence of an annotation, a service is assumed to support the following capabilities:

• Countability ($count, $inlinecount)
• Client pageability ($top, $skip)
• Expandability ($expand)
• Indexability by key
• Batch support ($batch)
• Navigability of navigation properties

A service is expected to use the following annotations if any of the relevant restrictions apply:

• Filterability ($filter)
• Sortability ($orderby)
• Queryability of top level entity sets
• Query functions

In the absence of an annotation, the client cannot assume that a service supports the following capabilities.

• Insertability
• Updatability
• Deletability

Assumed defaults notwithstanding, a client should always be prepared for services to fail to support any optional capabilities.

Namespace

The namespace of this version of the vocabulary is Org.OData.Capabilities.V1

Terms

InsertRestrictions

<ValueTerm Name="InsertRestrictions" Type="Self.InsertRestrictionsType" />
<ComplexType Name="InsertRestrictionsType">
<Property Name="Insertable" Type="Edm.Boolean" />
<Property Name="NonInsertableProperties" Type="Collection(Edm.String)" />
<Property Name="NonInsertableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

Used to express whether Insert operations are supported for an applicable target.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on an applicable target, it means that insertability of that target is unknown.

UpdateRestrictions

<ValueTerm Name="UpdateRestrictions" Type="Self.UpdateRestrictionsType" />
<ComplexType Name="UpdateRestrictionsType">
<Property Name="Updatable" Type="Edm.Boolean" />
<Property Name="NonUpdatableProperties" Type="Collection(Edm.String)" />
<Property Name="NonUpdatableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

Used to express whether Update operations are supported for an applicable target.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on applicable target, it means that updatability of that target is unknown.

DeleteRestrictions

<ValueTerm Name="DeleteRestrictions" Type="Self. DeleteRestrictionsType" />
<ComplexType Name="DeleteRestrictionsType">
<Property Name="Deletable" Type="Edm.Boolean" />
<Property Name="NonDeletableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

Used to express whether Delete operations are supported for an applicable target.

Applicable Targets: EntitySet

If the term doesn't exist on applicable target, it means that deletability of that target is unknown.

Countable

<ValueTerm Name="Countable" Type="Edm.Boolean" />

Used to express whether $count and $inlinecount operations are supported for an applicable target.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on applicable target, it means that countability of that target is supported. 

Queryable

<ValueTerm Name="Queryable" Type="Edm.Boolean" /> Used to express whether a set is directly queryable as a top level set. Applicable Targets: EntitySet Default Capability: If the term doesn't exist on an applicable target, it means that the queryability of the target is supported.

ClientPageable

<ValueTerm Name="ClientPageable" Type="Edm.Boolean" />

Used to express whether $top and $skip operations are supported for a navigation property or not.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on an applicable target, it means that $top and $skip operations are supported.

Expandable

<ValueTerm Name="Expandable" Type="Edm.Boolean" />

Used to express whether $expand operation is supported for a navigation property or not.

Applicable Targets: Navigation Property

Default Capability: If the term doesn't exist on an applicable target, it means that $expand is supported.

Navigable

<ValueTerm Name="Navigable" Type="Edm.Boolean" />

Used to express whether a navigation property can be part of the resource path in a query expression.

Applicable Targets: Navigation Property

Default Capability: If the term doesn't exist on an applicable target, it means that the navigation property is navigable in a query expression.

IndexableByKey

<ValueTerm Name="IndexableByKey" Type="Edm.Boolean" />

Used to express whether entities within an entity set can be indexed by key value(s) according to OData URL convention.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on an applicable target, it means that indexing by key is supported.

SupportsBatch

<ValueTerm Name="SupportsBatch" Type="Edm.Boolean" />

Used to express whether an EntityContainer supports batch operations.

Applicable Targets: EntityContainer

Default Capability: If the term doesn't exist on an applicable target, it means that $batch is supported.

QueryFunctions

<ValueTerm Name="QueryFunctions" Type="Collection(Edm.String)" />

Used to express the list of supported query function names.

Applicable Targets: EntityContainer

Default Capability: If the term doesn't exist on the applicable target, functions that the service supports are unknown.

If a certain function name is listed in the annotation, it is expected that any property of the type that is filterable on an entity set can be used as the function's parameter.

FilterRestrictions

<ValueTerm Name="FilterRestrictions" Type="Self.FilterRestrictionsType" />
<ComplexType Name="FilterRestrictionsType">
<Property Name="Filterable" Type="Edm.Boolean" />
<Property Name="RequiredProperties" Type="Collection(Edm.String)" />
<Property Name="NonFilterableProperties" Type="Collection(Edm.String)" />
</ComplexType>

Used to express restrictions on $filter support of a service.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on an EntitySet, it means that $filter is supported on that EntitySet.

It is possible to specify various capabilities by annotating with this term and picking values for the parameters. The table below shows some examples.

<ValueAnnotation Term="C.FilterRestrictions">
<Record>
<PropertyValue Name="Filterable" Boolean="False" />
</Record>
</ValueAnnotation>

<ValueAnnotation Term="C.FilterRestrictions">
<Record>

<PropertyValue Name="Filterable" Boolean="True" />
</Record>

</ValueAnnotation>

<ValueAnnotation Term="C.FilterRestrictions">
<Record>
<PropertyValue Name="RequiredProperties">
<Collection>
<String>Prop1</String>
<String>Prop2</String>
</Collection>

</PropertyValue>

</Record>

</ValueAnnotation>

<ValueAnnotation Term="C.FilterRestrictions">
<Record>
<PropertyValue Name="NonFilterableProperties">
<Collection>
<String>Prop3</String>
<String>Prop4</String>
<String>NavProp5/Prop6</String>
<String>NavProp7</String>
</Collection>
</PropertyValue>
</Record>
</ValueAnnotation>

<ValueAnnotation Term="C.FilterRestrictions">
<Record>
<PropertyValue Name="RequiredProperties">
<Collection>
<String>Prop1</String>
<String>Prop2</String>
</Collection>
</PropertyValue>

<PropertyValue Name="NonFilterableProperties">
<Collection>
<String>Prop3</String>
<String>Prop4</String>
</Collection>
</PropertyValue>
</Record>
</ValueAnnotation>

SortRestrictions

<ValueTerm Name="SortRestrictions" Type="Self.SortRestrictionsType" />
<ComplexType Name="SortRestrictionsType">
<Property Name="Sortable" Type="Edm.Boolean" />
<Property Name="AscendingOnlyProperties" Type="Collection(Edm.String)" />
<Property Name="DescendingOnlyProperties" Type="Collection(Edm.String)" />
<Property Name="UnsortableProperties" Type="Collection(Edm.String)" />
</ComplexType>

Used to express restrictions on sortability of an EntitySet.

Applicable Targets: EntitySet

Default Capability: If the term doesn't exist on an EntitySet, it means that EntitySet is sortable in both directions on all properties.

Various restrictions can be specified using the combination of term's properties similar to FilterRestrictions.

Formal CSDL Definition

<Schema Namespace="Org.OData.Capabilities.V1" xmlns="http://schemas.microsoft.com/ado/2009/11/edm" Alias="Self">

<ValueTerm Name="InsertRestrictions" Type="Self.InsertRestrictionsType" />

<ValueTerm Name="UpdateRestrictions" Type="Self.UpdateRestrictionsType" />

<ValueTerm Name="DeleteRestrictions" Type="Self.DeleteRestrictionsType" />

<ValueTerm Name="Countable" Type="Edm.Boolean" />

<ValueTerm Name="Queryable" Type="Edm.Boolean" />

<ValueTerm Name="ClientPageable" Type="Edm.Boolean" />

<ValueTerm Name="Expandable" Type="Edm.Boolean" />

<ValueTerm Name="Navigable" Type="Edm.Boolean" />

<ValueTerm Name="IndexableByKey" Type="Edm.Boolean" />

<ValueTerm Name="SupportsBatch" Type="Edm.Boolean" />

<ValueTerm Name="QueryFunctions" Type="Collection(Edm.String)" />

<ValueTerm Name="FilterRestrictions" Type="Self.FilterRestrictionsType" />

<ValueTerm Name="SortRestrictions" Type="Self.SortRestrictionsType" />

<ComplexType Name="InsertRestrictionsType">
<Property Name="Insertable" Type="Edm.Boolean" />
<Property Name="NonInsertableProperties" Type="Collection(Edm.String)" />
<Property Name="NonInsertableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

<ComplexType Name="UpdateRestrictionsType">
<Property Name="Updatable" Type="Edm.Boolean" />
<Property Name="NonUpdatableProperties" Type="Collection(Edm.String)" />
<Property Name="NonUpdatableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

<ComplexType Name="DeleteRestrictionsType">
<Property Name="Deletable" Type="Edm.Boolean" />
<Property Name="NonDeletableNavigationProperties" Type="Collection(Edm.String)" />
</ComplexType>

<ComplexType Name="FilterRestrictionsType">
<Property Name="Filterable" Type="Edm.Boolean" />
<Property Name="RequiredProperties" Type="Collection(Edm.String)" />
<Property Name="NonFilterableProperties" Type="Collection(Edm.String)" />
</ComplexType>

<ComplexType Name="SortRestrictionsType">
<Property Name="Sortable" Type="Edm.Boolean" />
<Property Name="AscendingOnlyProperties" Type="Collection(Edm.String)" />
<Property Name="DescendingOnlyProperties" Type="Collection(Edm.String)" />
<Property Name="UnsortableProperties" Type="Collection(Edm.String)" />
</ComplexType>
</Schema>

In addition to the core OData version 3.0 protocol found here, the Technical Committee will be defining some key extensions in the first version of the OASIS Standard:

OData Extensions for Data Aggregation - Business Intelligence provides the ability to get the right set of aggregated results from large data warehouses. OData Extensions for Analytics enable OData to support Business Intelligence by allowing services to model data analytic "cubes" (dimensions, hierarchies, measures) and consumers to query aggregated data.

OData Extensions for Temporal Data – Temporal databases support querying data as of a particular time or time range. OData Extensions for Temporal data define temporal annotations, functions and semantics for describing and working with temporal data.

Working with XML and JSON Data in OData – Databases often store XML or JSON documents as streams. Extensions for XML and JSON Data define custom functions and annotations to enable those documents to be represented and queried using functions appropriate to each domain (for example, custom XQuery functions for XML).

Retrieving Changes (Deltas) in OData – Data often changes relatively little over a period of time. In such cases, for example when maintaining a local copy, clients are interested only in retrieving what data has changed, not in re-retrieving the entire set of results. Deltas provide a hypermedia-driven mechanism for clients to request changes (inserts, deletes, updates) to a set of results.

In each of these areas the TC will be balancing the simplicity of OData with the need to do a little more, leveraging built-in OData extensibility mechanisms where possible.

Come join the OASIS Technical Committee and bring your scenarios, requirements, and ideas to help shape these exciting extensions to OData.

-Michael Pizzo

With the introduction of data and metadata annotations to OData version 3.0, developers can now define common vocabularies for things like Sales (with Customers, SalesOrder, Product, etc.), Movies (with Title, Actor, Director, ....), Calendars (with Event, Venue, …), etc. Of course, such vocabularies are only useful to the extent that they are shared across a broad range of clients and services.

Over the past  year, schema.org has been defining common schemas to make it easier for search engines to find and understand data on the web. Whenever we talk about shared Vocabularies in OData we inevitably get asked about the relationship of common ontologies expressed through OData Vocabularies to the work going on in schema.org.

I am happy to share that, through ongoing discussions with the members of schema.org, we have agreed that defining common OData Vocabulary encodings of the schema.org schemas is a benefit to both technologies. Sharing a common vocabulary even across different encodings like OData, RDFa 1.1, and Microdata, facilitates a common understanding and even possible transformation of data across those encodings. Toward that end we have jointly posted a discussion paper on the Web Schemas wiki on the use of schema.org schemas within OData.

From Dan Brickley's blog post on new developments around schema.org:

"We are also pleased to announce today a discussion paper on the use of OData and Schema.org, posted in the Web Schemas wiki. OData defines a RESTful interface for working with data on the Web. The newest version of OData allows service developers and third parties to annotate data or metadata exposed by an OData Service. Defining common OData Vocabulary encodings of the schema.org schemas facilitates the understanding and even transformation of data across these different encodings."

Feel free to add comments to Dan's post, or send us feedback on the odata.org mailing list.

Exciting times for OData!

-Mike

I’m happy to announce that Citrix, IBM, Microsoft, Progress Software, SAP and WSO2 are jointly submitting a proposal for the standardization of OData to OASIS.

While the OASIS OData Technical Committee will standardize OData, the great collaboration will continue in the odata.org community to grow the library of producers and consumers and, share implementation and Interop experiences, etc.

The starting point for the proposal is the current OData v3 specification plus a number of proposed extensions that use the protocol extensibility points to add functionality without having to increase the footprint of the core specification.

We often have discussions within the team, with developers out there and the community about what OData can and cannot do and whether we should add this or that feature. In that context we always come back to the same few principles that guide the design of OData: the main value of this technology is not any particular design choice but the fact that enough people agree to the same pattern, thus removing friction from sharing data across independent producers and consumers. For that to work the protocol must remain simple for simple cases, cover more sophisticated cases reasonably well and avoid inventing stuff as much as possible.

With interoperability front and center in OData we saw more and more technology stacks that started to work with it. Now there are a number of companies that use OData in their products to ensure the data they manage is easily accessible beyond the boundaries of their applications. Many of these companies regularly collaborate on the ongoing design effort for OData. While so far we’ve run the OData design process as transparently as we could (sharing designs, taking feedback through the odata.org blog and distribution list, etc.), we are at a point where the level of adoption and the scale at which organizations are betting on OData require a more formal commitment to shared ownership of the design of this protocol.

We have a good amount of work ahead of us in the OASIS TC, but this is the first step. We’ll keep posting to this blog with updates as things progress.

We encourage others to get involved to learn more about the protocol and design decisions that were made in developing the protocol. Go to odata.org, check out the OData blog and join the OData mailing list (the instructions are on odata.org).  Join the OASIS OData TC and help us standardize the protocol!

We’re happy to see OData take this important step on the journey towards standardization. Thanks to all the folks out there that helped get OData this far.

-pablo

In April we shipped the OData version 3 along with the 5.0 release of WCF Data Services. To make it easier for you discover the new features and for us to show you some of them, we’re now making available the OData demo services which use the OData V3 protocol.

The new services are hosted side by side with old demo services which we didn’t change. The new demo services are using the WCF Data Services 5.0.1-rc release currently, and we will update them to the newer version once it becomes available.

There are 3 demo services:

The read-only Demo service, which has an updated model to use some V3 features as described below, is hosted here:

http://services.odata.org/V3/OData/OData.svc/

The read-write Demo service, which is the exact same model as the read-only Demo service including new V3 features, is hosted here:

http://services.odata.org/V3/(S(readwrite))/OData/OData.svc/

The read-only Northwind service, which is the exact same model as the existing Northwind service, is hosted here:

http://services.odata.org/V3/Northwind/Northwind.svc/

Here are the V3 features we’ve enabled so far.

Actions

The Product type has a Discount action on it which takes a single parameter discountPercentage of type Edm.Int32. The action takes the Price of the product it’s applied to and decreases it by the percentage specified by the parameter. For example:

  GET http://services.odata.org/V3/(S(plcxuejnllfvrrecpvqbehxz))/OData/OData.svc/Products(1)

Will return a product with Price: 3.5

  POST http://services.odata.org/V3/(S(plcxuejnllfvrrecpvqbehxz))/OData/OData.svc/Products(1)/Discount HTTP/1.1
Content-Type: application/json;odata=verbose

{ "discountPercentage": 25 }

The response should be 204 No Content.

And now again

  GET http://services.odata.org/V3/(S(plcxuejnllfvrrecpvqbehxz))/OData/OData.svc/Products(1)

Returns a product with Price: 2.625

Spatial

The Supplier type has a property Location which is of type Edm.GeographyPoint. You can see it here:

http://services.odata.org/V3/OData/OData.svc/Suppliers(0)

Any and All

The service now supports any and all operators. For example:

http://services.odata.org/V3/OData/OData.svc/Categories?$filter=Products/any(p: p/Rating ge 4)

Inheritance support

You can now address properties on derived types. The demo service doesn’t have a sample property like that yet, but you can try the new URL syntax with type cast anyway:

http://services.odata.org/V3/OData/OData.svc/Products/ODataDemo.Product

Patch support

You can send PATCH requests instead of MERGE. The behavior is identical otherwise.

Prefer header support

You can specify a Prefer header in create or update requests and ask the server to either omit or include the payload. For example:

  PATCH http://services.odata.org/V3/(S(plcxuejnllfvrrecpvqbehxz))/OData/OData.svc/Products(1) HTTP/1.1
Accept: application/json;odata=verbose
Content-Type: application/json;odata=verbose
Prefer: return-content
DataServiceVersion: 3.0;

  { "Price": "3.5" }

Responds with (trimmed for readability):

  HTTP/1.1 200 OK
Content-Type: application/json;odata=verbose;charset=utf-8
Preference-Applied: return-content
DataServiceVersion: 3.0;

{"d":{
"__metadata":{…},
…
"ID":1,
"Name":"Milk",
"Description":"Low fat milk",
"ReleaseDate":"1995-10-01T00:00:00",
"DiscontinuedDate":null,
"Rating":3,
"Price":"3.5"
}}

Association links

Each navigation link can now also specify an association link which is the URL to manipulate the association with. For example this is a part of the ATOM payload for ~/Product(1):

<link
rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Category"
type="application/atom+xml;type=entry"
title="Category"
href="Products(1)/Category" />
<link
rel="http://schemas.microsoft.com/ado/2007/08/dataservices/relatedlinks/Category"
type="application/xml"
title="Category"
href="Products(1)/$links/Category" />

We are working on adding more V3 features to the Demo service and we’ll be updating the service as we have them available.

Vitek Karas
Sr. Software Development Engineer, OData, Microsoft.

We recently put together a document that contains some of our thinking about JSON light as well as a whole slew of sample payloads. We would love to hear any feedback you have on the format; you can comment in the accompanying OneNote.

We will be accepting public feedback on JSON light until May 4, 2012. We will also provide a preview release of the JSON light bits via NuGet for interested parties.

JSON light at-a-glance: https://skydrive.live.com/redir.aspx?cid=0d23ed2816deea7b&resid=D23ED2816DEEA7B!966&parid=D23ED2816DEEA7B!106&authkey=!AAYCE2RUJccjhHk
Discussion: https://skydrive.live.com/redir.aspx?cid=0d23ed2816deea7b&page=view&resid=D23ED2816DEEA7B!967&parid=D23ED2816DEEA7B!106&authkey=!ABdrv3heWfQFY4Y

OData Service Validation Tool  was updated with 5 new rules and the ground work for supporting OData v3 services:

• 4 new common rules
• 1 new entry rule
• Added version annotation to rules to differentiate rules by version
• Modified the rule selection engine to support rule version.
• Change rule engine API to support rule versions
• Changed database schema to log request and response headers
• Added a V3 checkbox for online and offline validation scenarios

This update brings the total number of rules in the validation tool to 152. You can see the list of the active rules here and the list of rules that are under development here.

Moreover, with this update the validation tool is positioned to support rules for v3 services for OData V3 payload validation.

Keep on  validating and let us know what you think either on the mailing list or on the discussions page on the Codeplex site.