[ODATA-276] Fix issues with entity references and rationalize with $links - OASIS Technical Committees Issue Tracker

Details

Type: Improvement
Status: Closed
Priority: Major
Resolution: Fixed
Affects Version/s: V4.0_WD01
Fix Version/s: V4.0_WD01
Component/s: ABNF, ATOM Format, JSON Format, Protocol, URL Conventions
Labels:
None
Environment:

[Proposed]

Proposal:

Hide

1) Remove navigations from entityref
2) Move $ref to path. entity/$ref returns the reference to the entity; entityCollection/$ref returns the references to members of the collection.
Examples:
Customer(1)/$ref <=get the entityRef for Customer 1
Customers/$ref <=get references for customers
Customers?$expand=Orders/$ref <=get customers and the refs for their orders
Customers?$expand=Orders($filter=Amount>100)/$ref <=get customers and the ref for orders over $100
Employees/Managers?$expand=DirectReports/ns.Manager <=get managers and their directs that are managers (this should work, right? Not affected by proposal)
Employees/Managers?$expand=DirectReports/ns.Manager($filter=startswith(LastName,'Bak'))/$ref <=get managers and the entity references for directs that are managers and whose last name starts with 'Bak'

3) Replace uri (in atom) and url (in JSON) with odata.entityRef
4) $links becomes $ref:
POST Customers(1)/$links/Orders
{"uri":"Orders(1043)"}
=> POST Customers(1)/Orders/$ref
{"odata.entityRef":"Orders(1043)"}
POST Customers(1)/$links/Orders
{"uri":"Orders(1043)"}
=> POST Customers(1)/Orders/$ref <m:entityRef>Orders(1043)</m:entityRef>
PUT Orders(1043)/$links/Customer
{"uri":"Customers(1)"}
=> PUT Orders(1043)/Customer/$ref
{"odata.entityRef":"Customers(1)"}
PUT Orders(1043)/$links/Customer
{"uri":"Customers(1)"}
=> PUT Orders(1043)/Customer/$ref <m:entityRef>Customers(1)</m:entityRef>
DELETE Customers(1)/$links/Orders(1043) => DELETE Customers(1)/Orders(1043)/$ref
DELETE Orders(1043)/$links/Customers(1) => DELETE Orders(1043)/Customer/$ref

Accepted: https://www.oasis-open.org/committees/download.php/48481/odata-meeting-28_on-20130307-minutes.html#odata-276

Show
1) Remove navigations from entityref 2) Move $ref to path. entity/$ref returns the reference to the entity; entityCollection/$ref returns the references to members of the collection. Examples: Customer(1)/$ref <=get the entityRef for Customer 1 Customers/$ref <=get references for customers Customers?$expand=Orders/$ref <=get customers and the refs for their orders Customers?$expand=Orders($filter=Amount>100)/$ref <=get customers and the ref for orders over $100 Employees/Managers?$expand=DirectReports/ns.Manager <=get managers and their directs that are managers (this should work, right? Not affected by proposal) Employees/Managers?$expand=DirectReports/ns.Manager($filter=startswith(LastName,'Bak'))/$ref <=get managers and the entity references for directs that are managers and whose last name starts with 'Bak' 3) Replace uri (in atom) and url (in JSON) with odata.entityRef 4) $links becomes $ref: POST Customers(1)/$links/Orders {"uri":"Orders(1043)"} => POST Customers(1)/Orders/$ref {"odata.entityRef":"Orders(1043)"} POST Customers(1)/$links/Orders {"uri":"Orders(1043)"} => POST Customers(1)/Orders/$ref <m:entityRef>Orders(1043)</m:entityRef> PUT Orders(1043)/$links/Customer {"uri":"Customers(1)"} => PUT Orders(1043)/Customer/$ref {"odata.entityRef":"Customers(1)"} PUT Orders(1043)/$links/Customer {"uri":"Customers(1)"} => PUT Orders(1043)/Customer/$ref <m:entityRef>Customers(1)</m:entityRef> DELETE Customers(1)/$links/Orders(1043) => DELETE Customers(1)/Orders(1043)/$ref DELETE Orders(1043)/$links/Customers(1) => DELETE Orders(1043)/Customer/$ref Accepted: https://www.oasis-open.org/committees/download.php/48481/odata-meeting-28_on-20130307-minutes.html#odata-276
Resolution:

Hide

https://www.oasis-open.org/committees/download.php/48526/odata-core-v4.0-wd01-part1-protocol-2013-03-12.doc

https://www.oasis-open.org/committees/download.php/48527/odata-core-v4.0-wd01-part2-url-conventions-2013-03-12.doc
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-construction-rules-v4.0-wd01.txt?rev=211
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-testcases.xml?rev=211

https://www.oasis-open.org/committees/download.php/48524/odata-atom-format-v4.0-wd01-2013-12-05-RH.doc
https://www.oasis-open.org/committees/download.php/48588/odata-atom-format-v4.0-wd01-2013-03-19.doc
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/metadata.xsd?rev=208
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/metadata.xsd?rev=219

https://www.oasis-open.org/committees/download.php/48525/odata-json-format-v4.0-wd01-2013-03-12-RH.doc

Accepted: https://www.oasis-open.org/committees/download.php/49026/odata-meeting-34_on-20130425_26-F2F-minutes.html#odata-276

Show
https://www.oasis-open.org/committees/download.php/48526/odata-core-v4.0-wd01-part1-protocol-2013-03-12.doc https://www.oasis-open.org/committees/download.php/48527/odata-core-v4.0-wd01-part2-url-conventions-2013-03-12.doc https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-construction-rules-v4.0-wd01.txt?rev=211 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/ABNF/odata-abnf-testcases.xml?rev=211 https://www.oasis-open.org/committees/download.php/48524/odata-atom-format-v4.0-wd01-2013-12-05-RH.doc https://www.oasis-open.org/committees/download.php/48588/odata-atom-format-v4.0-wd01-2013-03-19.doc https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/metadata.xsd?rev=208 https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/metadata.xsd?rev=219 https://www.oasis-open.org/committees/download.php/48525/odata-json-format-v4.0-wd01-2013-03-12-RH.doc Accepted: https://www.oasis-open.org/committees/download.php/49026/odata-meeting-34_on-20130425_26-F2F-minutes.html#odata-276

Description

In adding Entity References in OData-199, we introduced a few issues.

First, we said that clients could return just references, in place of the actual entity, by putting $ref in the select clause. We then said it wasn't valid to include navigation properties with $ref in the select, but not other non-navigation properties. This is a bit arbitrary; the only data that needs to be returned an object is its references to other object(s); if links from those related objects are also of interest, they can be requested and retrieved as related links of those objects. Also, it's a bit strange to use $select for something that changes the type of object returned, from an entity to an entity reference; a path expression would be more suitable for this.

Second, adding a path representation for relationships gives us a way to rationalize/generalize the special semantics around $links that we have today. We can use the $ref path expression to refer to the links that are added/deleted/enumerated, and provide a consistent representation of an entity reference in the payload (rather than have entity references for referring to entities in one case, and a separate URI construct for referring to entities in another case).

Fix issues with entity references and rationalize with $links

Details

Description

Attachments

Activity

People

Dates