Version Support and Limitations

Offline OData supports OData versions 2.0, 4.0, and 4.01 with some limitations.

OData Version 2.0 Support and Limitations

Offline OData supports a mix of OData Version 2.0 and 4.0 metadata annotations for defining additional characteristics or capabilities of a metadata element, such as a service, entity type, property, function, action, or parameter. For example, you can define a valid range of values for a particular property.

There is no support for the following OData concepts:

• ETags when using the if-match/if-none-match headers when performing local reads.
• Modifying properties or complex type properties by addressing them in the URL.

Offline OData has the following limitations:

• The maximum length (MaxLength) of Edm.String key properties is 10922 characters and MaxLength must be present in the metadata.
• The maximum length (MaxLength) of Edm.Binary key properties is 32768 bytes and MaxLength must be present in the metadata.
• If the back end cannot respond with child entities in the same order as the request, then the navigation property used for deep insert must refer to at most one entity.
• Media resources can't be read in a batch request.
• The mobile service does not provide the capability to use No Rewriting mode to support external back ends for offline usage.
• Requests to read OData service metadata cannot include query options.

• Relationships may not be reflected on the client until after a download.

  If the offline application uses only a referential constraint property to create or modify a relationship, the new or updated relationship is not reflected locally until the modification request is uploaded, and then the result is downloaded.

  Note

  There are several methods available to see the relationships locally. For example, have the gateway back end ignore a bind operation (another operation in OData creating or modifying relationships that can be reflected locally), and locally use both a bind operation and update a referential constraint property. When doing this, the relationship is reflected locally using the bind, but the relationship is created/modified in the back end using the referential constraint property. This workaround may be necessary when a back end does not support bind operations or $links. If it supports either, updating the relationships using referential constraint properties is unnecessary.

• Metadata annotations are not populated in the metadata object.

Keep in mind the following points about custom query options:

• For modification requests, custom query options are not passed to the back end. However, if the offline application requires custom behavior, the developer can set custom headers and custom cookies per request that are sent to the back end.
• For defining queries, the custom query options are sent to the back end. In this case, the exact URL that the offline application gives, or the associated delta link provided by the back end, is sent. On the other hand, currently, custom query options are not sent when retrieving the metadata or service document.

Limitations with Deep Inserts

A deep insert is an OData POST request to create an entity that also contains inline related entities.

When a deep insert is processed, the top-level entity and all its related entities are created and linked together as a single operation. Offline OData supports deep inserts and, by default, expects the back end to respond with the child entities, which should be returned in the same order as they appear in the request.

If the back end cannot respond with the child entities, or if the child entities are not in the same order as the request:

• Use deep insert only to the one end: The navigation property used for the deep insert must refer to at most one entity. The inline entity must be added using a navigation property where the ToRole refers to an association end with cardinality 0..1 or 1. Inline entities cannot be added using a navigation property where the ToRole refers to an association end with cardinality *. A navigation property that refers to a set of entities cannot be used for deep inserts.
• Enable offline configuration fetch_and_map_entities_for_deep_insert_to_the_many_end.

Note

Deep insert is only one way to create relationships; there are others.

OData Version 4.0 Support and Limitations

Offline OData supports two OData Version 4.0 lambda operators, any and all.

• Support OData version 4.0 with the following new features：

  • Enum type
  • Stream property
  • Collection property
  • Bound/Unbound action and function with simple, complex, and entity type parameters
  • Exponential decimal
  • OnDelete action for navigation property
  • Key properties reference to the complex properties
  • Basic OData aggregation functionality, including sum, min, max, average, count, countdistinct aggregation, and groupby, top, bottom, concat, and filter transformations

• Support OData version 4.0 with the following limitations：

  • OData Atom (xml) is not supported
  • Content-ID referencing in body and Content-ID referencing across change sets are not supported
  • Binds for a collection of value navigation properties in a PATCH request are not supported
  • Modification operations in batches outside of change sets are not supported
  • Deep update is not supported
  • Bound/Unbound action and function with collection type parameters are not supported
  • Bound/Unbound action and function with singleton parameters are not supported
  • Derived entities are not supported
  • $filter operations on date (such as add and sub) are not supported
  • $filter and $orderby operations on spatial types are not supported
  • Default value of spatial types is not supported
  • Key properties of spatial types are not supported
  • System query options $search and $index are not supported
  • Built-in functions or literals: geo.distance, geo.intersects, geo.length, case, $level, $all, $each, $it, and $root are not supported
  • Upserting an entity other than a singleton is not supported
  • Upserting a singleton with containment navigation properties is not supported
  • Data aggregation is not supported on stream properties and dynamic properties
  • Nested aggregation queries and advanced aggregations, such as roll-up, compute, hierarchical transformations, and others, are not implemented

Limited Support for OData Version 4.01

Currently only the following OData version 4.01 new features are supported：

• OData 4.0.1 new JSON format:

  • Control information without prefix odata.
  • Improved exponential notation for decimals

• Key properties of a directly related entity type

• The in operator has the following limitations:

  • If the right operand is a list, the list elements must be primitive literals and cannot include any other types of expressions.
  • If the right operand is a collection, it must be a collection of properties and cannot include any other types of expressions.
  • Does not support the type Edm.Geo.
  • Does not support nested or continuous in operations.
  • Does not support arrays of arrays.

---

Last update: February 17, 2025