2.2.3.6.1.1.1 Expression Construction and Evaluation Rules

Article
03/06/2019

commonExpression: A data service MAY support the commonExpression common expression. If supported, a commonExpression MUST represent any and all supported common expression types.

boolCommonExpression: A data service MAY support the boolCommonExpression common expression. If supported, a boolCommonExpression MUST be a common expression that evaluates to the Entity Data Model (EDM) primitive type Edm.Boolean.

parenExpression: A data service MAY support the enclosing of expressions in parentheses. This expression is represented as a parenExpression common expression in the common expression syntax.

If supported, a parenExpression MUST be evaluated by evaluating the expression with the parentheses, starting with the innermost parenthesized expressions, and proceeding outwards, following proper precedence rules where parentheses override any other operator precedence. The result of the parenExpression MUST be the result of the evaluation of the contained expression.

boolParenExpression: A data service MAY support the enclosing of Boolean expressions in parentheses. This expression is represented as a boolParenExpression common expression in the common expression syntax.

If supported, a boolParenExpression MUST be evaluated by evaluating the expression with the parentheses. The result of the boolParenExpression MUST be the result of the evaluation of the contained expression and MUST be of the EDM primitive type Edm.Boolean.

addExpression: A data service MAY support the binary addition operator. The operation of adding two expressions is represented as an addExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <9> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The addExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM primitive type. The EDM primitive type of the result of evaluating the addExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the addExpression, according to the rules of [IEEE754-2008] for the addition operation. Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

subExpression: A data service MAY support the binary subtraction operator. The operation of subtracting two expressions is represented as a subExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <10> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The subExpression SHOULD NOT be supported for operands of any other EDM primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM primitive type. The EDM primitive type of the result of evaluating the subExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the subExpression, according to the rules of [IEEE754-2008] for the subtraction operation. Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

mulExpression: A data service MAY support the binary multiplication operator. The operation of multiplying two expressions is represented as a mulExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <11> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The mulExpression SHOULD NOT be supported for operands of any other EDM primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM primitive type. The EDM primitive type of the result of evaluating the mulExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the mulExpression, according to the rules of [IEEE754-2008] for the multiplication operation. Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

divExpression: A data service MAY support the binary division operator. The operation of dividing two expressions is represented as a divExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <12> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The divExpression SHOULD NOT be supported for operands of any other EDM primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM primitive type. The EDM primitive type of the result of evaluating the divExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the divExpression, according to the rules of [IEEE754-2008] for the division operation. Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

modExpression: A data service MAY support the binary remainder operator. The operation of computing the remainder of two expressions is represented as a modExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <13> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The modExpression SHOULD NOT be supported for operands of any other EDM primitive type.

If supported, a data service SHOULD follow the binary numeric promotion rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the operands to a common supported EDM primitive type. The EDM primitive type of the result of evaluating the modExpression MUST be the same type as the operands after binary numeric promotion rules have been applied to operands.

If supported, the data service SHOULD evaluate the operation represented by the modExpression, according to the rules of [IEEE754-2008] for the remainder operation. Further, the data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

negateExpression: A data service MAY support the unary negate operator. The operation of negating an expression is represented by the negateExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <14> support some or all of the common expressions as operands of the operation. The operand expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Int16
Edm.Int32
Edm.Int64

The data service SHOULD NOT support operand expressions of any other EDM primitive type for the negateExpression.

If supported, a data service SHOULD follow the unary numeric promotion rules defined in Unary Numeric Promotions (section 2.2.3.6.1.1.3) to implicitly convert the operand to a supported EDM primitive type. The EDM primitive type of the result of evaluating the negateExpression MUST be the same type as the operand after binary numeric promotion rules have been applied to the operand.

If supported, the data service SHOULD evaluate the operation represented by the negateExpression by subtracting the operand value from zero. This result of evaluating the negateExpression SHOULD always be equal to the result of evaluating the subExpression where one operand is the value zero and the other is the value of the operand.

The data service MAY support evaluating an operand with a null value following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

andExpression: A data service MAY support the binary logical-and operator. The operation of evaluating whether two expressions both evaluate to the value of true is represented by the andExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <15> support some or all of the boolCommonExpression expressions as operands of the operation. Those operand expressions MUST evaluate to the EDM primitive types of Edm.Boolean. The andExpression SHOULD NOT be supported for operands of any other EDM primitive types.

The EDM primitive type of the result of evaluating the andExpression MUST be Edm.Boolean.

If supported, a data service MUST evaluate the expression to the value of true if the values of the operands are both true after being evaluated. If either operand is false after being evaluated, the expression MUST evaluate to the value of false.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

orExpression: A data service MAY support the binary logical-or operator. The operation of evaluating whether at least one of two expressions evaluate to the value of true is represented by the orExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <16> support some or all of the boolCommonExpression common expressions as operands of the operation. Those operand expressions MUST evaluate to the EDM primitive types of Edm.Boolean. The orExpression SHOULD NOT be supported for operands of any other EDM primitive types.

The EDM primitive type of the result of evaluating the orExpression MUST be Edm.Boolean.

If supported, a data service MUST evaluate the expression to the value of true if at least one of the operands is true after being evaluated. If both operands are false after being evaluated, the expression MUST evaluate to the value of false.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

memberExpression: A data service MAY support the referencing of a navigation, complex, or simple property of an EntityType. This is represented by the memberExpression common expression in the common expression syntax.

If supported, the common expression that is the target of the memberExpression MUST be a known EntityType or ComplexType. If supported, the memberExpression MAY reference an entity NavigationProperty (entityNavProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an entity complex type property (entityComplexProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an entity simple property, as specified in Resource Path: Construction Rules (section 2.2.3.4). For entity NavigationProperties, the target relationship end must have a cardinality of 1 (single entity, mandatory) or 0..1 (single entity, optional).

The type of the result of evaluating the memberExpression MUST be the same type as the property reference in the memberExpression.

The data service MAY support evaluating a memberExpression where instance values of a property are null following the rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4).

firstMemberExpression: A data service MAY support the referencing of a navigation, complex, or simple property of the EntityType or ComplexType represented by the last segment in the navigation portion of the URI. This is represented by the firstMemberExpression common expression in the common expression syntax.

If supported, the firstMemberExpression MAY reference an entity navigation property (entityNavProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an entity complex type property (entityComplexProperty, as specified in Resource Path: Construction Rules (section 2.2.3.4)), or an entity simple property, as specified in Resource Path: Construction Rules (section 2.2.3.4). For entity NavigationProperties, the target relationship end has to have a cardinality of 1 (single entity, mandatory) or 0..1 (single entity, optional).

The type of the result of evaluating the firstMemberExpression MUST be the same type as the property reference in the firstMemberExpression.

The data service MAY support evaluating a firstMemberExpression where instance values of a property are null following the rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4).

When nested inside lambdaPredicateExpression, firstMemberExpression MUST be prefixed with a lambdaPredicatePrefixExpression that identifies to what the firstMemberExpression is bound.

boolPrimitiveMemberExpression: A data service MAY support the referencing of a Boolean simple property of an EntityType or ComplexType. This is represented by the boolPrimitiveMemberExpression common expression in the common expression syntax.

The type of the result of evaluating the boolPrimitiveMemberExpression MUST be EDM primitive type Edm.Boolean.

The data service MAY support evaluating a Boolean memberExpression where the property instance value is null following the rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4).

firstBoolPrimitiveMemberExpression: A data service MAY support the referencing of a Boolean simple property of an EntityType or ComplexType represented by the last segment in the navigation portion of the URI. This is represented by the firstBoolPrimitiveMemberExpression common expression in the common expression syntax.

The type of the result of evaluating the boolPrimitiveMemberExpression MUST be EDM primitive type Edm.Boolean.

The data service MAY support evaluating a Boolean memberExpression where the property instance value is null following the rules defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4).

eqExpression: A data service MAY support the binary equality operator. The operation of evaluating whether two expressions are equal is represented as an eqExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <17> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of a known EntityType (see [MC-CSDL] for the definition of equality between two EntityType instances) or one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Boolean
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid
Edm.Binary

The eqExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service MUST return a value of true if the values of the operands are equal and false if they are not equal. If the type of the operands is a known EntityType, then a value of true MUST be returned if the operand expressions, once evaluated, represent the same entity instance. Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

neExpression: A data service MAY support the binary non-equality operator. The operation of evaluating whether two expressions are not equal is represented as an neExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <18> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of a known EntityType or one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.Boolean
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid
Edm.Binary

The neExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service MUST return a value of true if the values of the operands are not equal and false if they are equal. If the type of the operands is a known EntityType, then a value of true MUST be returned if the operand expressions once evaluated do not represent the same entity instance. Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

ltExpression: A data service MAY support the binary less than operator. The operation of evaluating whether one expression is less than the other expression is represented as an ltExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <19> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid

The ltExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service MUST return a value of true if the value of the first operand is less than the value of the second operand and false if not. Actual ordering and comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

leExpression: A data service MAY support the binary less than or equal to the operator. The operation of evaluating whether one expression is less than or equal to the other expression is represented as an leExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <20> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid

The leExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service MUST return a value of true if the value of the first operand is less than or equal the value of the second operand, and false if not. Actual ordering and comparison of values is data service specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

gtExpression: A data service MAY support the binary greater than operator. The operation of evaluating whether one expression is greater than the other expression is represented as a gtExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <21> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid

The gtExpression SHOULD NOT be supported for any other EDM primitive types.

If supported, a data service MUST return a value of true if the value of the first operand is greater than or equal to the value of the second operand, and false if not. Actual ordering and comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when ordering and comparing values.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

geExpression: A data service MAY support the binary greater than or equal operator. The operation of evaluating whether one expression is greater than or equal to the other expression is represented as a geExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <22> support some or all of the common expressions as operands of the operation. Those operand expressions MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double
Edm.Single
Edm.DateTimeOffset
Edm.Time
Edm.Byte
Edm.SByte
Edm.Int16
Edm.Int32
Edm.Int64
Edm.String
Edm.DateTime
Edm.Guid

The geExpression SHOULD NOT be supported for any other EDM primitive types.

The data service MAY support evaluating operands with null values following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

notExpression: A data service MAY support the unary logical negation operator. The operation of logically negating an expression is represented by the notExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <23> support some or all of the common expressions as operand values of the operation as long as the operand expression evaluates to a value of the EDM primitive type Edm.Boolean. The data service SHOULD NOT support operand expressions of any other EDM primitive type for the notExpression.

The EDM primitive type of the result of evaluating the notExpression MUST be Edm.Boolean.

If supported, the data service MUST evaluate the logical negation operation by returning false if the operand value is true and returning true if the operand value is false.

The data service MAY support evaluating an operand with a null value following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

isofExpression: A data service MAY support the isof operation. The operation of checking whether an instance is compatible with a given type is represented by the isofExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <24> support some or all of the common expressions as the first operand value. In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the isof operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI. The second operand MUST be a stringUriLiteral that represents the name of a known entity or EDM primitive type.

The EDM primitive type of the result of evaluating the isofExpression MUST be Edm.Boolean.

If supported, the data service MUST evaluate the isofExpression to return a value of true if the targeted instance MAY be converted to the specified type. If the conversion is not allowed, the expression MUST be evaluated to false.

The data service MAY support evaluating an operand with a null value following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

castExpression: A data service MAY support the cast expression. The operation of converting an expression to a given type is represented by the castExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <25> support some or all of the common expressions as the first operand value. In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the cast operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI. The second operand MUST be a stringUriLiteral that represents the name of a known entity or EDM primitive type to convert the first operand to.

The type of the result of evaluating the castExpression MUST be the same type as represented by the string literal value from the second operand. A data service MAY support any cast operations where there exists an explicit conversion from the targeted instance (first operand) to the type represented by second operand. In all other cases, the data service SHOULD NOT support the specified cast operation.

The data service MAY support evaluating an operand with a null value following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

boolCastExpression: A data service MAY support the Boolean cast expression. The operation of converting an expression to a Boolean value is represented by the boolCastExpression common expression in the common expression syntax. If this operation is supported, the data service MAY <26> support some or all of the common expressions as the first operand value. In addition, the data service MAY support the first operand as being optional. In the case where it is not included, then the cast operation is interpreted to apply to the entity instance specified by the navigation portion of the request URI. The second operand MUST be the stringUriLiteral "Edm.Boolean".

The type of the result of evaluating the boolCastExpression MUST be EDM primitive type Edm.Boolean. A data service MAY support any cast operations where there exists an explicit conversion from the targeted instance (first operand) to the EDM primitive type Edm.Boolean. In all other cases, the data service SHOULD NOT support the specified cast operation.

The data service MAY support evaluating an operand with a null value following the rules defined in Lifted Operators (section 2.2.3.6.1.1.5).

boolLiteralExpression: A data service MAY support expressions that are literals representing a Boolean value. These expressions are represented by the boolLiteralExpression common expression in the common expression syntax.

If supported, the type of the boolLiteralExpression MUST always be the EDM primitive type Edm.Boolean.

literalExpression: A data service MAY support expressions that are literals. These expressions are represented by the literalExpression common expression in the common expression syntax.

If supported, the type of the literalExpression MUST be the EDM primitive type for the lexical representation of the literal, as specified in Abstract Type System (section 2.2.2).

methodCallExpression: A data service MAY support the methodCallExpression common expression. If supported, a methodCallExpression MUST represent a method call in the common expression syntax.

boolMethodCallExpression: A data service MAY support the boolMethodCallExpression common expression. If supported, a boolMethodCallExpression MUST be a method call expression that evaluates to the EDM primitive type Edm.Boolean.

endsWithMethodCallExpression: A data service MAY support the EndsWith method. This method call is represented as an endsWithMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <27> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The endsWithMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the endsWithMethodCallExpression SHOULD be a value of the EDM primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the endsWithMethodCallExpression by returning a Boolean value indicating whether the end of the first parameter value matches the second parameter value. Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

indexOfMethodCallExpression: A data service MAY support the IndexOf method. This method call is represented as an indexOfMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <28> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The indexOfMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the indexOfMethodCallExpression SHOULD be a value of the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the indexOfMethodCallExpression by returning an integer value indicating the index of the first occurrence of the second parameter value in the first parameter value. If no index is found, a value of -1 SHOULD be returned. Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

replaceMethodCallExpression: A data service MAY support the replace method. This method call is represented as a replaceMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <29> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The replaceMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the replaceMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the replaceMethodCallExpression by returning a string value with all occurrences of the second parameter value replaced by the third parameter value in the first parameter value. Actual comparison of values is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when comparing values.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, as defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4), to implicitly convert the parameters to a supported EDM primitive type.

startsWithMethodCallExpression: A data service MAY support the startswith method. This method call is represented as a startsWithMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <30> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The startsWithMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the startsWithMethodCallExpression SHOULD be a value of the EDM primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the startsWithMethodCallExpression by returning a Boolean value indicating whether the beginning of the first parameter values matches the second parameter value. Actual comparison of values is data service-specific and no semantics for doing so are mandated, however a data service MUST always use consistent semantics when comparing values.

toLowerMethodCallExpression: A data service MAY support the tolower method. This method call is represented as a toLowerMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <31> support some or all of the common expressions as the parameter of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The toLowerMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the toLowerMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the toLowerMethodCallExpression by returning a string value with the contents of the parameter value converted to lower case. Actual definition of lower case is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when converting to lower case.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters, defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4), to implicitly convert the parameters to a supported EDM primitive type.

toUpperMethodCallExpression: A data service MAY support the toupper method. This method call is represented as a toUpperMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <32> support some or all of the common expressions as the parameter of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The toUpperMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the toUpperMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the toUpperMethodCallExpression by returning a string value with the contents of the parameter value converted to upper case. Actual definition of upper case is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when converting to upper case.

trimMethodCallExpression: A data service MAY support the trim method. This method call is represented as a trimMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <33> support some or all of the common expressions as the parameter of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The trimMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the trimMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the trimMethodCallExpression by returning a string value with the contents of the parameter value with all leading and trailing white-space characters removed. Actual definition of white space is data service-specific and no semantics are mandated; however, a data service MUST always use consistent semantics when identifying white space.

substringMethodCallExpression: A data service MAY support the substring method. This method call is represented as a substringMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <34> support some or all of the common expressions as the parameters of this method. The first parameter expression MUST evaluate to a value of the EDM primitive type Edm.String. The second and third parameter expressions MUST evaluate to a value of the EDM primitive type Edm.Int32.

The substringMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the substringMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the substringMethodCallExpression by returning the string value starting at the character index specified by the second parameter value in the first parameter string value. If the optional third parameter is specified, the resulting string is the length (in characters) of the third parameter value. Otherwise, the entire string from the specified starting index is returned.

subStringOfMethodCallExpression: A data service MAY support the substringof method. This method call is represented as a substringOfMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <35> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The substringOfMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the substringOfMethodCallExpression SHOULD be a value of the EDM primitive type Edm.Boolean.

If supported, the data service SHOULD evaluate the method call represented by the substringOfMethodCallExpression by returning a Boolean value indicating whether the first parameter string value occurs in the second parameter string value. Actual comparison of values is data service-specific and no semantics for doing so is mandated; however, a data service MUST always use consistent semantics when comparing values.

concatMethodCallExpression: A data service MAY support the concat method. This method call is represented as a concatMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <36> support some or all of the common expressions as the parameters of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The concatMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the concatMethodCallExpression SHOULD be a value of the EDM primitive type Edm.String.

If supported, the data service SHOULD evaluate the method call represented by the concatMethodCallExpression by returning a string value that is the first and second parameter values merged together with the first parameter value coming first in the result.

lengthMethodCallExpression: A data service MAY support the length method. This method call is represented as a lengthMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <37> support some or all of the common expressions as the parameter of this method. The parameter expressions MUST evaluate to a value of the EDM primitive type Edm.String.

The lengthMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types. If supported, the EDM primitive type of the result of evaluating the lengthMethodCallExpression SHOULD be a value of the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the lengthMethodCallExpression by returning the number of characters in the specified parameter value. Actual definition of how to calculate string length is data service-specific and no semantics for doing so are mandated; however, a data service MUST always use consistent semantics when calculating the length.

getTotalOffsetMinutesMethodCallExpression: A data service MAY support the getTotalOffsetMinutes method. This method call is represented as a getTotalOffsetMinutesMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <38> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of the EDM primitive type Edm.DateTimeOffset.

The getTotalOffsetMinutesMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the getTotalOffsetMinutesMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the getTotalOffsetMinutesMethodCallExpression by returning the signed number of minutes in the time zone offset part of the DateTimeOffset parameter value, evaluated in the time zone of the DateTimeOffset parameter value.

yearMethodCallExpression: A data service MAY support the year method. This method call is represented as a yearMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <39> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of either the EDM primitive type Edm.DateTime or the EDM primitive type Edm.DateTimeOffset.

The yearMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the yearMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the yearMethodCallExpression by returning the year component value of the parameter value.

monthMethodCallExpression: A data service MAY support the month method. This method call is represented as a monthMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <40> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of either the EDM primitive type Edm.DateTime or the EDM primitive type Edm.DateTimeOffset.

The monthMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the monthMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the monthMethodCallExpression by returning the month component value of the parameter value.

dayMethodCallExpression: A data service MAY support the day method. This method call is represented as a dayMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <41> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of either the EDM primitive type Edm.DateTime or the EDM primitive type Edm.DateTimeOffset.

The dayMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the dayMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the dayMethodCallExpression by returning the day component value of the parameter value.

hourMethodCallExpression: A data service MAY support the hour method. This method call is represented as an hourMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <42> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of EDM primitive type Edm.DateTime, Edm.DateTimeOffset, or Edm.Time.

The hourMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the hourMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the hourMethodCallExpression by returning the hour component value of the parameter value using a 24-hour range to cover an entire day without an AM/PM indicator and by starting at 0.

minuteMethodCallExpression: A data service MAY support the minute method. This method call is represented as a minuteMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <43> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of EDM primitive type Edm.DateTime, Edm.DateTimeOffset, or Edm.Time.

The minuteMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the minuteMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the minuteMethodCallExpression by returning the minute component value of the parameter value.

secondMethodCallExpression: A data service MAY support the second method. This method call is represented as a secondMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <44> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of EDM primitive type Edm.DateTime, Edm.DateTimeOffset, or Edm.Time.

The secondMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, the EDM primitive type of the result of evaluating the secondMethodCallExpression SHOULD be the EDM primitive type Edm.Int32.

If supported, the data service SHOULD evaluate the method call represented by the secondMethodCallExpression by returning the second component value of the parameter value.

roundMethodCallExpression: A data service MAY support the round method. This method call is represented as a roundMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <45> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double

The roundMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the parameters to a supported EDM primitive type. The EDM primitive type of the result of evaluating the roundMethodCallExpression MUST be the same type as the parameter.

If supported, the data service SHOULD evaluate the method call represented by the roundMethodCallExpression by returning the nearest integral value to the parameter value, following the rules defined in [IEEE754-2008] for the rounding operation.

floorMethodCallExpression: A data service MAY support the floor method. This method call is represented as a floorMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <46> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double

The floorMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the parameters to a supported EDM primitive type. The EDM primitive type of the result of evaluating the floorMethodCallExpression MUST be the same type as the parameter after the promotion rules have been applied.

If supported, the data service SHOULD evaluate the method call represented by the floorMethodCallExpression by returning the largest integral value less than or equal to the parameter value, following the rules defined in [IEEE754-2008] for the floor operation.

ceilingMethodCallExpression: A data service MAY support the ceiling method. This method call is represented as a ceilingMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY <47> support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.Decimal
Edm.Double

The ceilingMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types.

If supported, a data service SHOULD follow the numeric promotion rules for method call parameters defined in Binary Numeric Promotions (section 2.2.3.6.1.1.4) to implicitly convert the parameters to a supported EDM primitive type. The EDM primitive type of the result of evaluating the floorMethodCallExpression MUST be the same type as the parameter after the promotion rules have been applied.

If supported, the data service SHOULD evaluate the method call represented by the ceilingMethodCallExpression by returning the smallest integral value greater than or equal to the parameter value, following the rules defined in [IEEE754-2008] for the ceiling operation.

distanceMethodCallExpression: A data service MAY support the geo.distance method. This method call is represented as a distanceMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.GeographyPoint
Edm.GeometryPoint

The distanceMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types, except in compliance with Geospatial Extension Methods (section 2.2.3.6.1.1.8).

If supported, a data service MAY perform coordinate transformations, as specified in Geospatial Coordinate Transformations (section 2.2.3.6.1.1.7) to implicitly convert the parameters to the same EDM primitive type, with the same system reference identifier (SRID). For further details about SRID, see [MC-CSDL] Edm.GeographyPoint SRID (section 2.2.1.18.1.1) and Edm.GeometryPoint SRID (section 2.2.1.26.1.1). If the system does not support coordinate transformations, it MUST require that the two arguments be of the same type and in the same SRID. The EDM primitive type of the result of evaluating the distanceMethodCallExpression MUST be Edm.Double.

If supported, the data service SHOULD evaluate the method call that is represented by the distanceMethodCallExpression by computing the geospatial distance between the two points in the coordinate reference system signified by the two points' SRIDs, according to an algorithm that is correct for the datum of that coordinate reference system. For Edm.GeometryPoint, the algorithm is minimum-distance, as defined in [OGC-SFOLECOM]. Multiple reasonable algorithms exist for Edm.GeographyPoint, such as minimum-distance or length of great elliptical arc. The implementation SHOULD choose some reasonable algorithm.

If the implementation supports both geoLengthMethodCallExpression and distanceMethodCallExpression, it MUST use compatible algorithms for these two operations. In particular, for any two positions A and B, geo.distance (Point(A), Point(B)) MUST equal geo.Length (LineString(A, B)).

geoLengthMethodCallExpression: A data service MAY support the geo.length method. This method call is represented as a geoLengthMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value of one of the following EDM primitive types:

Edm.GeographyLineString
Edm.GeometryLineString

The distanceMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types, except in compliance with Geospatial Extension Methods (section 2.2.3.6.1.1.8).

The EDM primitive type of the result of evaluating the distanceMethodCallExpression MUST be Edm.Double.

If supported, the data service SHOULD evaluate the method call represented by the geoLengthMethodCallExpression by computing the path length of the LineString in the coordinate reference system signified by its SRID, according to an algorithm that is correct for the datum of that coordinate reference system. For Edm.GeometryLineString, the algorithm is sum of minimum-distance, as defined in [OGC-SFOLECOM]. Multiple reasonable algorithms exist for Edm.GeographyLineString, such as sum of minimum-distance or sum of length of great elliptical arc. The implementation SHOULD choose some reasonable algorithm.

If the implementation supports both geoLengthMethodCallExpression and distanceMethodCallExpression, it MUST use compatible algorithms for these two operations. In particular, for any two positions A & B, geo.distance(Point(A), Point(B)) MUST equal geo.Length(LineString(A, B)).

intersectsMethodCallExpression: A data service MAY support the geo.intersects method. This method call is represented as an intersectsMethodCallExpression common expression in the common expression syntax. If this method is supported, the data service MAY support some or all of the common expressions as the parameter of this method. The parameter expression MUST evaluate to a value such that the arguments are one of the following sets of EDM primitive types:

Edm.GeographyPoint and Edm.GeographyPolygon, in either order
Edm.GeometryPoint and Edm.GeometryPolygon, in either order

The intersectsMethodCallExpression SHOULD NOT be supported for parameters of any other EDM primitive types, except in compliance with Geospatial Extension Methods (section 2.2.3.6.1.1.8).

If supported, a data service MAY perform coordinate transformations, as specified in Geospatial Coordinate Transformations (section 2.2.3.6.1.1.7) to implicitly convert the parameters to a supported set of EDM primitive types, with the same SRID. If the system does not support coordinate transformations, it MUST require that the two arguments be of a supported set of types and in the same SRID. The EDM primitive type of the result of the evaluation of the distanceMethodCallExpression MUST be Boolean.

If supported, the data service SHOULD evaluate the method call that is represented by the intersectsMethodCallExpression by computing whether the point lies within the interior or the boundary of the polygon, as defined in [OGC-SFOLECOM].

implicitVariableExpression: Within a lambdaPredicateExpression a data service SHOULD support an implicitVariableExpression ($it) to unambiguously refer to a variable that represents the members of the collection that are being filtered by the filterQueryOption.

lambdaVariableExpression: To allow a lambdaPredicateExpression to refer to the members of the collection that a lambdaMethodCallExpression call is bound to, a lambdaVariableExpression MUST be specified.

A variable name is specified by using a lambdaVariableExpression common expression in the common expression syntax. This variable name can then be used in a lambdaPredicateExpression to specify a filter over the corresponding collection.

inscopeVariableExpression: When firstMemberExpression expressions are inside a lambdaPredicateExpression, variable names MUST be used to avoid ambiguity. Referring to variables that are currently available (in scope) is represented by using an inscopeVariableExpression common expression in the common expression syntax.

Inside a lambdaPredicateExpression there are at least two collection variables that can be referred to, namely $it (implicitVariableExpression) and whatever explicit names have been introduced by lambdaVariableExpression.

lambdaMethodCallExpression expressions can be nested inside an inscopeVariableExpression, which would mean that three or more variables can be in scope.

lambdaPredicateExpression: A data service MAY support use of nested filters with lambdaMethodCallExpression expressions. The nested filter is applied to the members of the collection to which the lambdaMethodCallExpression is bound. This nested filter is represented as a lambdaPredicateExpression common expression in the common expression syntax.

A lambdaPredicateExpression follows the same rules as a boolCommonExpression, with the additional restriction that any nested firstMemberExpression expressions MUST be disambiguated using a lambdaPredicatePrefixExpression.

lambdaPredicatePrefixExpression: This is a prefix based on an inscopeVariableExpression that MUST be prepended to all firstMemberExpression expressions that are found inside lambdaPredicateExpression expressions.

collectionPathExpression: lambdaMethodCallExpression expressions MUST be bound to either an entityCollectionProperty or an entityNavProperty-es. This is specified by using collectionPathExpression common expression in common expression syntax.

If the collectionPathExpression is nested inside a lambdaPredicateExpression, an inscopeVariableExpression MUST be used to identify the variable that the expression is bound to.

singlePathExpression: Sometimes the entityCollectionProperty or entityNavProperty-es that ought to be bound to lambdaMethodCallExpression is not directly available; in this case, clients might need to first go through an entityNavProperty-et or an entityComplexProperty. A data service MAY choose to support accessing nested collections by using a singlePathExpression common expression in common expression syntax.

If the singlePathExpression is nested inside a lambdaPredicateExpression, an inscopeVariableExpression MUST be used to identify what variable to bind the expression to.

lambdaMethodCallExpression: A lambdaMethodCallExpression is either an anyMethodCallExpression or an allMethodCallExpression.

anyMethodCallExpression: A data service MAY support the any method. This method MUST be bound to a collection, either an entityNavProperty-es or an entityCollectionProperty, via a collectionPathExpression.

If there is no lambdaVariableExpression or lambdaPredicateExpression, the data service MUST return false if the bound collection is empty or otherwise true.

If a lambdaVariableExpression is specified, a lambdaPredicateExpression MUST also be specified.

The data service method MUST return true if any members of the collection satisfy the filter that is specified in the lambdaPredicateExpression or otherwise false.

lambdaMethodCallExpression expressions can be nested inside an anyMethodCallExpression.

allMethodCallExpression: A data service MAY support the all method. This method call is represented as an allMethodCallExpression common expression in the common expression syntax.

The data service method MUST return true if there are no members in the bound collection.

The data service MUST return true if all members of the bound collection satisfy the filter that is specified by the lambdaVariableExpression or otherwise false.

lambdaMethodCallExpression expressions can be nested inside an allMethodCallExpression.

functionCallExpression: A data service MAY support functionCallExpression. Non-binding parameters to functionCallExpression MUST be provided inline.

Binding parameters to functionCallExpression expressions MUST be provided either inline, or via the optional memberExpression or firstMemberExpression that starts the functionCallExpression.

boolFunctionCallExpression: A data service MAY support boolFunctionCallExpression, which is a functionCallExpression with the added restriction that the ReturnType of the corresponding function MUST be a Boolean value.

functionParametersExpression: A data service MAY support passing one or more parameters in a functionCallExpression by using the functionParametersExpression.

functionParameterExpression: A parameter within a functionParametersExpression is represented by using a functionParameterExpression that contains the name and value of the parameter. The data service MAY <48> support some or all of the allowable expressions for the value of the parameter.

structuralValue: A data service MAY support passing a complex type, multi-value, entity, or collection of entities as the value in a functionParameterExpression by using a structuralValue.

entityReference: A data service MAY support passing an entity or collection of entities by reference as the value in a functionParameterExpression by using an entityReference.

2.2.3.6.1.1.1 Expression Construction and Evaluation Rules

Additional resources