2.2.6.3.9 Deferred Content

  • Article

The serialized representation of an entity and its related entities, identified by NavigationProperties, can be large. To conserve resources (bandwidth, CPU, and so on), it is generally not a good idea for a data service to return the full graph of entities related to the EntityType instance or set identified in a request URI. For example, a data service ought to defer sending entities represented by any navigation property in a response unless explicitly asked to send those entities via the $expand system query option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3).

In Verbose JSON-formatted EntityType instances (see Entity Type (as a JSON Object) (section 2.2.6.3.3)), NavigationProperties serialized as name/value pairs in which the value is a JSON object containing a single name/value pair with the name "__deferred" and a value that is a JSON object containing a single name/value pair with the name "uri" and a string value, which is a URL that can be used to retrieve the deferred content, signify deferred NavigationProperty content (for example, the entities represented by the NavigationProperty are not serialized inline). For example, using the two EntityTypes Customer and Order, as described in Appendix A: Sample Entity Data Model and CSDL Document (section 6), the default Verbose JSON serialization (with deferred NavigationProperty content) of the Customer instance with EntityKey value of "ALFKI" is shown in Entity Type (as a JSON object) (section 2.2.6.3.3).

In the example, the presence of the "__deferred" name/value pair signifies that the value of the Orders NavigationProperty is not directly represented on the JSON object in this serialization. In order to obtain the deferred value(s), a client would make a separate request directly to the navigation property URI (service.svc/Customers('ALFKI')/Orders) or explicitly ask that the property be serialized inline via the $expand system query option, as described in Expand System Query Option ($expand) (section 2.2.3.6.1.3).