2.2.6.3.10 Links

Links represent unidirectional associations or one direction of a bidirectional association between EntityType instances. In the Verbose JSON format, Links are serialized as an array of URIs, each of which identifies a single linked entity.

When represented in Verbose JSON, Links MUST be formatted, as shown in the table in the following listing, ABNF Grammar for Links Represented in Verbose JSON, using one JSON object containing a single "uri" name/value pair per Link. The value of the "uri" name/value pair on each object MUST equal the absolute, canonical URI representing the linked-to EntityType instance.

The syntax of the Verbose JSON representation of a collection of links is defined by the grammar listed in this section. The grammar rule "linkCollVJson" defines the Verbose JSON representation of a collection of links that can be used in all versions of a request payload and OData 1.0 response payloads. The grammar rule "linkCollVJson2" defines the OData 2.0 and OData 3.0 Verbose JSON representations of a collection of links for response payloads only.

 ; Request and OData 1.0 response Verbose JSON representation of a collection of  links 
 linkCollVJson       =  begin-array
                        *linkVJson
                        end-array
  
 ; OData 2.0 and OData 3.0 response Verbose JSON representation of a collection of links
 linkCollVJson2       =  begin-object
                        [countNVP value-seperator]
                        linkCollResultsNVP  
                        [value-seperator nextUriNVP] 
                        end-object                    
  
 linkCollResultsNVP  =  quotation-mark "results" quotation-mark
                        name-seperator
                        begin-array
                        *linkVJson
                        end-array 
  
 countNVP            =  ; see section 2.2.6.3.2
  
 nextUriNVP          =  ; see section 2.2.6.3.2 for ABNF.
                        ; see section 2.2.6.5.5.2 for AtomPub Format.
  
 ;Grammar rules common to OData 1.0, OData 2.0, and OData 3.0
 linkVJson            =  begin-object
                        [linkUriNVP
                         *(value-seperator linkUriNVP) ]
                        end-object
  
 linkUriNVP          =  quotation-mark "uri" quotation-mark
                        name-seperator
                        quotation-mark dataServiceNqo-URI quotation-mark
                        ; see section 2.2.3.1

Listing: ABNF Grammar for Links Represented in Verbose JSON

For example, when using the sample model and instance data, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6), the Links from the Customer with EntityKey "ALFKI" to Order instances is represented as shown in the following Example of Links Formatted by Using OData 1.0 Verbose JSON Representation listing. Each URI in the array identifies a single Order that is associated with the Customer.

 [
   {"uri": "http://host/service.svc/Orders(1)"},
   {"uri": "http://host/service.svc/Orders(2)"}
 ]

Listing: Example of Links Formatted by Using OData 1.0 Verbose JSON Representation