OData 4.1 URL Syntax Simplification Proposal

Introduction:

The existing OData URL conventions were designed such that a URL could be unambiguously parsed for any valid model. Unfortunately, being unambiguous leads to strict rules on namespace qualification of types and operations, as well as key syntax, that run counter to common REST practices. Indeed, in many (most?) scenarios the strict rules are unnecessary when the service has some control over the model and/or the data. For such services, the inability to present the desired URLs has become an adoption blocker in many instances.

A collection of Jira issues were opened in order to attempt to enable a service to expose simpler URL conventions in cases where theoretical ambiguities were impossible (or highly unlikely). For example, when unqualified action/function names are known not to conflict with property names, or when key values can't conflict with action/function/type names.

This proposal seeks to address those issues as a whole by attempting to provide an expanded set of conventions and precedence rules that a service can follow in order to allow a more relaxed set of URL patterns.

Proposal:

Note: OData already requires that all children of a schema (entity/complex/enum types, typedefs, terms, actions, functions) must be unique.

Proposal Part I:

Define the concept of “Default Namespaces”. A new Boolean annotation, “Core.DefaultNamespace”, can be applied to the <Schema> element to specify that that namespace is a default namespace as well as to the <Include> element to specify that the included namespace is a default namespace. The semantics of the default namespaces are as follows:

1) Data modelers should ensure uniqueness of schema children across all default namespaces

2) Data modelers should avoid naming bound actions and functions the same as a property on the bound type

3) Data modelers should avoid naming derived types the same as a property defined on a base type

4) Undefined what happens if there is a conflict across schemas. Client should handle by always qualifying

5) Services may disallow dynamic properties whose names conflict with a bound action, bound function, or derived type in a default namespace

6) Services may disallow key values whose names conflict with a bound action, bound function, or derived types in a default namespace

Proposal Part II:

1) Types, functions, actions, and enums defined within default namespaces can be referenced in a URL without namespace/alias qualification.

2) URLs segments are resolved according to the following precedence rules:

a. Following an entity collection segment:

i. Does it match an OData segment (starting with “$”)

ii. Does it match an alias-qualified bound action name, bound function overload, or type name?

iii. Does it match a namespace-qualified bound action name, bound function overload, or type name?

iv. Does it match an unqualified bound action name, bound function overload, or type name in a default namespace?

1. This addresses ODATA-812, which proposes to make the namespace optional for bound actions and functions.

2. It also makes the namespace optional for cast segments, although that scenario was not called out in the Jira issue.

v. Treat as a key

1. This addresses ODATA-799, enable key-as-segment, by defining precedence rules for evaluating unmatched segments as keys.

2. For maximum interoperability, services SHOULD also support parens format, to avoid ambiguity, and to support multi-part keys

3. The syntax of ContextUrl always uses parens syntax

4. If services didn't support unqualified bound action/function/type names following a collection segment then it would be much more common for services to unambiguously support key-as-segment syntax by restricting the key from containing "." If we continue to require functions to be suffixed with parenthesis-enclosed parameters we help avoid conflicts with keys as long as the key value doesn't contain open/close parens, which means in most cases we only have to worry about conflicts with unqualified bound action and type names.

b. Following a single entity segment:

i. Does it match an OData segment (starting with “$”)

ii. Does it match a declared property?

iii. Does it match an alias-qualified bound action name, bound function overload, or type name?

iv. Does it match a namespace-qualified bound action name, bound function overload, or type name?

v. Does it match a bound action, bound function overload, or type in a default namespace? ((ODATA-812)

vi. Treat as open property

c. Following a scalar value segment:

i. Does it match an OData segment (starting with “$”)

ii. Does it match an alias-qualified bound action name, bound function overload, or type name?

iii. Does it match a namespace-qualified bound action name, bound function overload, or type name?

iv. Does it match a bound action, bound function overload, or type in a default namespace? (ODATA-812)

Proposal Part III:

Services support Implicit cast from string to enum in URL (ODATA-834). This allows the use of the string value of the enum in place of the full value, as in:

$filter=Color eq 'Yellow' in addition to the existing $filter=Color eq ns.Color'Yellow'.

Proposal Part IV:

A service may support invoking a function as the last segment in a path by omitting the parens and supplying the named parameters as query options prefixed with the "@" sign (ODATA-763)

odata message