What’s New in OData 4.0?
The fourth version of OData, the Microsoft-backed standard for querying data using REST conventions, has been accepted by the OASIS committee. The public review period will run thru June 2 and Microsoft expects OASIS to adopt the standard later this year.
1) Data Model Changes. There were a few changes to how the data model is expressed in CSDL, particularly:
a) Significant change/simplification to how relationships are expressed. Relationship definitions are now expressed as part of the navigation property, rather than specifying a separate association and association set. Among other things, this enables support for one-way relationships and true containment.
b) Top-Level "Named Entities" let you have a singleton entity exposed on your entity container.
c) Functions/Actions are now defined in schema (like entity/complex types) and MAY be exposed from your entity container through Function/Action imports.
d) Service documents can now include top-level "named entities" as well as parameterless function imports.
e) We added versioning to metadata through etags.
f) We fleshed out distributed data models by refining the definition of the <references> element, for schemas to reference other schemas, and making sure that instances could always point back to their metadata in JSON and ATOM.
g) We started to define how a service would expose metadata as a service. This was put in fairly recently and we'd love to get feedback on the data model, etc.
h) We relaxed some constraints on properties of complex types; key properties for an entity can now be on a contained complex type, as can navigation properties and referential constraints. We also defined inheritance semantics for complex types.
i) We allow abstract entity types to be defined without keys; the first non-abstract derived type must specify a key if not already specified.
j) We made some changes around annotations. In particular, we merged TypeAnnotations with ValueAnnotations, added default values and applies to, and started to define a core vocabulary to capture some of the behavioral aspects of the model (like server-generated properties for identity, computed fields, etc.)
2) Data Type Changes. We tuned the set of primitive types (especially the set of date/time data types). In particular:
a) We removed Edm.Float (synonym for Edm.Single) and Edm.DateTime (use Edm.DateTimeOffset), deprecated Edm.Time in favor of Edm.Duration and Edm.TimeOfDay.
b) We added the relevant canonical functions for the new data types, as well as functions for now(), mindatetime(), maxdatetime().
c) We defined the literal syntax and serialization formats for enumerations
d) We defined abstract "Edm.EntityType", "Edm.ComplexType", "Edm.PrimitiveType", and collections of each, which can be used in a data model where the type of entity/complex/primitive type is not known. The actual type is specified in the payload.
e) We added the concept of an entity reference, which can be used/returned instead of an entity in many places.
f) We added the concept of a "TypeDefinition" for naming a primitive type and a fixed set of facets.
3) URL Changes
a) We changed how expands are expressed. $expand now takes expand options, including $filter (for filtered expands), $orderby, etc., as well as $expand and $select as expand options which are used for nested expand/projections instead of expressing a path through navigation properties in the top-level $expand/$select. We also added $levels for recursive expand.
b) We added a $search system query option for doing full-text search across a resource.
c) $count replaces $inlinecount and can be applied to collections or to-many navigation properties to filter and can be used to return the count of related entities instead of the entities themselves.
4) Semantics. We refined some of the semantics around how requests are processed. Specifically:
a) We added a conformance section describing different levels of conformance. This is another area we'd really love feedback on. As you say, the spec is large and we want to be sure implementers know that it's not necessary to implement the entire spec in order to be conformant.
b) We fleshed out more behavior around $batch, including how it behaves with async results and preferences for continue/fail on error
c) We strongly encourage use of PATCH over PUT for updating entities/complex types, and clarified the behavior of PATCH with complex types (should update just the specified properties).
d) We aligned the Prefer header with the latest IETF draft and added a number of preferences for the client to hint to the service desired behavior.
e) We support UPSERT by doing a PUT/PATCH to a URL for a non-existent resource.
5) New Service areas. We added new (optional) support for services:
a) Asynchronous Execution is now defined through a return-async request header, following the latest thinking from IETF.
b) Change Tracking (Delta) Support is now defined as part of the specification for returning just the differences to a previously retrieved result. Semantics are defined around tracking changes to a set of related entities, and details for representing deleted entities, as well as added/deleted links, are documented for each format.
a) We deprecated the old "JSON Verbose" format in favor of the new, cleaner, JSON format
b) We don't require services to support ATOM; a service MUST implement either ATOM or JSON; we suggest JSON and require it at the highest conformance levels.
c) ATOM now includes a metadata url for the response, and may include a metadata url for navigation properties if the type information cannot be derived from the metadata url of the response.
Feedback on the proposed standard should be submitted to the OData mailing list.