A. Get References Instead of Entities

Representing Entity References

Use Cases

A. Get References Instead Of Entities

Just append /$ref to the resource path to return references in the requested format instead of entities.

B. Get Entity For A Reference

Just GET the entity using the URL in the entity reference representation.

Note: this would not be possible if responses would also use the KEY(…) notation.

C. Pass Reference as Binding Parameter

Just append the action or function path segment to the URL in the entity reference representation. No need for also accepting the /$ref segment in the path.

D. Pass Reference as Non-Binding Parameter

Use the URL in the entity reference representation to construct the JSON entity reference representation and URL-encode it. Even pure Atom clients should be able to do that string concatenation.

E. Construct Reference from Entity

If you’ve got the entity URL around, just construct the JSON representation of the entity reference.

With Atom entity: construct reference representation using the self-link or edit-link.

With JSON and odata.metadata=full you also have the odata.editLink, odata.readLink, or odata.id at hand.

With JSON and odata.metadata=minimal you can construct the KEY(…) representation by extracting the entity set name from the odata.metadata URL and using the key properties and their values.

You can also construct the JSON reference representation if you additionally know the URL conventions used by the service. The service root URL can be extracted from the odata.metadata URL.

With JSON and odata.metadata=none you need out-of-band knowledge of the entity set even to construct the KEY(…) representation.

F. Construct Entity from Reference

No chance without asking the server J

Proposal

Always represent references in responses as metadata:entity-ref> or {"odata.entityRef":…}.

Allow passing entity references in {"odata.entityRef":…} and KEY(…) notation instead of entities to function and action parameters.

Remove edm:ReferenceType element and Ref(…)notation from CSDL. We don’t need it anymore for passing parameters, and we want to give the client the choice of appending /$ref if it wants to save bandwidth. Returning only references and requiring additional requests for getting at the representations actually wastes bandwidth.

Keep KEY(…) notation in URL Conventions for use case E.

Related Jira Issues

ODATA-68: Describe representation of ReferenceTypes in responses

ReferenceType elements define a type derived from an entity type that can be used in function import return types.

Describe how they are serialized in Atom and JSON.

Original Proposal

Use the same literal form as in URLs in the body of an <metadata:element> element in Atom and within a double-quoted string in JSON

alternate:

Get rid of ReferenceTypes; for functions that return entities, the client can append /$ref in order to get the odata.entityRef bback instead.