2.2.3.4 Resource Path: Construction Rules

  • Article

This section further defines grammar rules noted in the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1) which map directly to constructs defined in an Entity Data Model (EDM).

actionFQName: The name of an action (Actions (section 2.2.1.3)) that is defined as a FunctionImport in the EDM that is associated with the data service. It is possible to have multiple actions with the same name and same parameter types in different EntityContainers. To disambiguate between these actions, the name of the action MUST be prefixed with the name of the entityContainer that defines the action.

actionCall: A call to an action (section 2.2.1.3) that MUST be made with a POST request, and that MUST be the last segment of the resource path.

The first (or binding) parameter MAY be specified by the URI path to which the actionCall has been appended or it MAY be specified in the POST body (Action Parameters (section 2.2.3.6.5)) with all other parameters if the actionCall is made by directly appending the action segment to the URI that represents the data service.

In order to apply an actionCall to a URI path, the first (or binding) parameter of the corresponding FunctionImport MUST match (or be coercible to) the type that the URI path would return if retrieved directly.

functionFQName: The name of a function (section 2.2.1.4) defined as a FunctionImport in the EDM that is associated with the data service. It is possible to have multiple functions with the same name and parameter types in different EntityContainers. To disambiguate between these functions, the name of the function MAY be prefixed with the name of the entityContainer that defines the function.

functionCall: A call to a function (Functions (section 2.2.1.4)) by appending the function segment directly to the root of the service. Parameters can be provided in the query in the same way as parameters are provided to a serviceOperation, or parameters can be provided inside the paren of the functionCall in the URI path, or parameters can be provided via query parameters in the query part of the URI that are referenced by aliases that are declared inside the paren of the functionCall. If any parameters are specified inside the paren (either inline or via aliases), all parameters MUST be provided inline.

functionCall-partiallyBound: A call to a function (Functions (section 2.2.1.4)) where the first (or binding) parameter is specified by the URI path to which the functionCall-partiallyBound has been appended. Subsequent parameters can be provided in three ways: inside the paren of the functionCall in the URI path, via query parameters in the query part of the URI that are referenced by aliases declared inside the paren of the functionCall or, if this is the last functionCall-partiallyBound in the URI path, via query parameters with the same name as the parameters of the function as declared in the corresponding FunctionImport.

In order to apply a functionCall-partiallyBound to a URI path, the first (or binding) parameter of the corresponding FunctionImport MUST match (or be coercible to) the type that the URI path would return if it were retrieved directly.

entityContainer: The name of an EntityContainer in the EDM that is associated with the data service.

entitySet: The name of an EntitySet in the EDM that is associated with the data service.  EntitySet names MAY<2> be directly followed by open and close parentheses (for example, Customers() ). However, not appending the parenthesis is also valid and considered the canonical form of an EntitySet name.

If an EntitySet is not in the default EntityContainer, the URI MUST qualify the EntitySet name with the EntityContainer name as follows: 

 http://<Any iauthority [RFC3987] and optional URI path segments>/<Entity Container name>.<Entity Set name>

entityType: The name of an EntityType in the EDM associated with the data service. The EntityType identified MAY be an OpenEntityType ([MC-CSDL] section 2.2.8).

namespaceQualifiedEntityType: The name of an EntityType in the EDM that is associated with the data service qualified with the namespace of the schema that is used in the EDM. The EntityType identified MAY be an OpenEntityType.

entityProperty: The name of a declared property or dynamic property, of type EDMSimpleType ([MC-CSDL] section 2.2.1) on an EntityType or a declared property of type EDMSimpleType defined on a ComplexType in the EDM that is associated with the data service.

If the prior URI path segment identifies an EntityType instance in EntitySet ES1, this value MUST be the name of a declared property or dynamic property, of type EDMSimpleType, on the base EntityType of set ES1.

If the prior URI path segment represents an instance of ComplexType CT1, this value MUST be the name of a declared property defined on ComplexType CT1.

entityComplexProperty: The name of a declared property, of type ComplexType, on an EntityType in the EDM associated with the data service.

If the prior URI path segment identifies an instance of an EntityType ET1, this value MUST be the name of a declared property or dynamic property on type ET1 which represents a ComplexType instance.

If the prior URI path segment identifies an instance of a ComplexType CT1, this value MUST be the name of a declared property on CT1 which represents a ComplexType instance.

entityCollectionProperty: The name of a declared property, of type Collection, on an EntityType in the EDM that is associated with the data service.

If the prior URI path segment identifies an instance of an EntityType ET1, the entityCollectionProperty MUST be the name of a declared property on type ET1 that represents a Collection instance.

There MUST NOT be any subsequent path segments in the URI after the entityCollectionProperty.

entityNavProperty: Identifies the name of a NavigationProperty on an EntityType.

If the prior URI path segment identifies an instance of an EntityType ET1, this value MUST be the name of a NavigationProperty on type ET1.

If the URI path segment preceding an entityNavProperty segment is "$links", there MUST NOT be any subsequent path segments in the URI after the entityNavProperty. If additional segments exist, the URI MUST be treated as invalid. For example, no path segment can follow the Orders segment in the URI:

 http://host/service.svc/Customers('ALFKI')/$links/Orders.

entityNavProperty-es: This rule is the same as entityNavProperty, but with the added constraint that the NavigationProperty MUST point to an endpoint of an association with a cardinality of "many" (for example, such that traversing the association yields a set).

entityNavProperty-et: This rule is the same as entityNavProperty, but with the added constraint that the NavigationProperty MUST identify an EntityType instance.

entityNamedStream: Identifies the name of a property on an EntityType that is of type Edm.Stream.

The prior URI path segment MUST identify an instance of an EntityType.

If the EntityType identified by the prior segment is ET1, this value MUST be the name of a property of type Edm.Stream defined on either ET1 or on a base type of ET1.

keyPredicate: Specifies the property values of an EntityKey. When the keyPredicate is used in conjunction with an entityNavProperty-es that identifies a navigation property that, via the backing AssociationType, has a referential integrity constraint, then the key property values that are known to be shared between source and target entities MAY be omitted from the keyPredicate, but the renaming unknown key properties MUST be specified. In all other cases, all property values of the EntityKey MUST be specified.

keyPredicate-single: Identifies the EntityKey value of an EntityType whose EntityKey is comprised of only one property.

The EDM defines that each such key value is non-nullable, immutable, and an EDMSimpleType. The representation of an EDMSimpleType value in a data service URI has to follow the syntax rules defined in Abstract Type System (section 2.2.2).

An EntityKey consisting of a single EntityType property MAY<3> be represented by using the "<Entity Type property name> = <Entity Type property value>" syntax, as seen in the keyPredicate-cmplx grammar rule of the Augmented BNF for URI Construction listing in URI Syntax (section 2.2.3.1). However, the representation, which only specifies the value of the property, is the canonical representation for single property EntityKeys.

keyPredicate-cmplx: Identifies an EntityKey consisting of more than one property of the EntityType. The order in which the properties of a compound EntityKey appear in the URI MUST NOT be significant.

serviceOperation: Identifies a FunctionImport in an EDM, as seen in [MC-CSDL], which returns any of the following:

  • Primitive type

  • Collection of primitive types.

  • single ComplexType instance.

  • Collection of ComplexType instances.

  • Single EntityType instance.

  • Collection of EntityType instances.

  • Nothing or void.

For additional details on the type system (primitive type, ComplexType, and so on) used by data services, see Message Syntax (section 2.2).

serviceOperation-collEt: Identifies a FunctionImport ([MC-CSDL] section 2.1.15) in an EDM, as specified in [MC-CSDL], that returns a collection of entities where each entity is in the same EntitySet. A service operation of this type acts as a pseudo EntitySet in that additional resource path (section 2.2.3.3) segments can follow that identify entities or relationships on entities within the collection that is identified by the service operation.