2.2.3.6.1.3 Expand System Query Option ($expand)

  • Article

The presence of the $expand system query option indicates that entities associated with the EntityType instance or EntitySet, identified by the resource path section of the URI, MUST be represented inline instead of as Deferred Content (section 2.2.6.2.6) and Deferred Content (section 2.2.6.3.9).

The server MUST include any actions or functions that are bound to the associated entities that are introduced via an expandClause, unless a select system query option is also included in the request and that $select requests that the actions/functions be omitted (section 2.2.3.6.1.11).

The following rules supplement the grammar below, which represents the syntax of this system query option.

 expandQueryOp = "$expand=" expandClause *("," expandClause)
 expandClause  = [ namespaceQualifiedEnitityType"/"] entityNavProperty *(["/"namespaceQualifiedEnitityType]"/" entityNavProperty)  
                ; section 2.2.3.1
 

The left most entityNavProperty in an expandClause MUST represent a NavigationProperty defined in the EntityType, or a subtype thereof, associated with the resource path section of the URI. A subsequent NavigationProperty in the same expandClause MUST represent a NavigationProperty defined on the EntityType, or a subtype thereof, represented by the prior NavigationProperty in the expandClause.

Redundant expandClause rules on the same data service URI MAY be considered valid, but MUST NOT alter the meaning of the URI.

Examples

 http://host/service.svc/Customers?$expand=Orders

For each customer entity within the Customers EntitySet, the value of all associated Orders are represented inline.

 http://host/service.svc/Orders?$expand=OrderLines/Product,Customer

For each Order within the Orders EntitySet, the following is represented inline:

  • The Order lines associated to the Orders identified by the resource path section of the URI and the products associated to each Order line.

  • The customer associated with each Order returned.

The OData 3.0 protocol supports specifying the namespace-qualified EntityType on which the NavigationProperty is defined as part of the expand statement.

 http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff

For each Customer entity in the Customers EntitySet, the value of all associated InHouseStaff MUST be represented inline if the entity is of type VipCustomer or a subtype of that. For entity instances that are not of type VipCustomer, or any of its subtypes, that entity instance MUST be returned with no inline representation for the expanded NavigationProperty.