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.