Skip to content

Latest commit

 

History

History
178 lines (133 loc) · 8.95 KB

Org.OData.JSON.V1.md

File metadata and controls

178 lines (133 loc) · 8.95 KB

JSON Vocabulary

Namespace: Org.OData.JSON.V1

Terms, types, and functions for JSON data

OData stream properties allow embedding data of arbitrary media types, and the OData JSON format allows direct embedding of JSON data in request and response payloads.

This vocabulary defines a convenience type for JSON data as well as a term for referencing a JSON Schema describing the structure of the JSON data.

In addition it defines two functions for querying JSON data and using a primitive value extracted from JSON data in common expressions, for example in $filter, $orderby, or $compute.

Example

The Employees entity set has a JSON data property resume (see CSDL JSON or CSDL XML).

One of its entities has a resume value of

{ 
  "ssn": "1234", 
  "lastname": "Doe", 
  "address": {
    "zipcode": "10022", 
    "street": "ABC st"
  },
  "experience": "excellent"
}

This allows to filter and sort by values in that resume, and extract parts of the resume as a dynamic JSON data property

GET http://www.example.com/mycompany/Employees
      ?$filter=resume/JSON.value(path='$.lastname') eq 'Doe'
      &$orderby=resume/JSON.valueNumber(path='$.experience')
      &$compute=resume/JSON.query(path='$.address') as address
      &$expand=address

receiving

{ 
  "@odata.context": "$metadata#Employees", 
  "value": [ 
    {
      "empid": 4711,
      "address": {
        "zipcode": "10022", 
        "street": "ABC st"
      }
    },
    ...
  ]
}

Terms

Term Type Description
Schema JSON The JSON Schema for JSON values of the annotated media entity type, property, parameter, return type, term, or type definition
The schema can be a reference, i.e. {"$ref":"url/of/schemafile#/path/to/schema/within/schemafile"}

Functions

query

Query a stream value of media type application/json, returning a stream value of media type application/json

Extracts a JSON value, such as an array, object, or a JSON scalar value (string, number, boolean, or null) from the input JSON value:

  • If path only consists of the root identifier followed by name and index selectors, it returns the identified single node within input, or null if no node is identified.
  • If path potentially identifies multiple nodes within input (by using descendant, wildcard, union, array subset, or filter selectors), it returns an array containing the identified nodes, or an empty array if no node is identified.
  • If input is not a valid JSON value, the function returns null.
  • If path is null, not a valid JSONPath expression, or does not match the structure of input (for example applying an index selector to a scalar value), the function returns null.
Parameter Type Description
input JSON? Binding parameter: JSON input
path Path? JSONPath expression to be applied to value of expr
→ JSON? JSON value resulting from applying path to input

value

Query a stream value of media type application/json, returning a string

Extracts a single OData primitive value from the input JSON value and casts it to a string:

  • If path only consists of the root identifier followed by name and index selectors and identifies a single scalar JSON value (string, number, boolean, or null) within input, it returns the identified single value, cast to a string.
  • If path identifies multiple nodes within input (by using descendant, wildcard, union, array subset, or filter selectors), identifies an object or array, or does not identify any node, the function returns null.
  • If input is not a valid JSON value, the function returns null.
  • If path is null, not a valid JSONPath expression, or does not match the structure of input (for example applying an index selector to a scalar value), the function returns null.
Parameter Type Description
input JSON? Binding parameter: JSON input
path Path? JSONPath expression to be applied to value of expr
→ String? String value resulting from applying path to input

valueNumber

Query a stream value of media type application/json, returning a number

Like value, but casts the extracted value to an Edm.Decimal with unspecified precision and floating scale. Returns null if that cast fails.

Parameter Type Description
input JSON? Binding parameter: JSON input
path Path? JSONPath expression to be applied to value of expr
→ Decimal? Numeric value resulting from applying path to input

valueBoolean

Query a stream value of media type application/json, returning a Boolean

Like value, but casts the extracted value to an Edm.Boolean. Returns null if that cast fails.

Parameter Type Description
input JSON? Binding parameter: JSON input
path Path? JSONPath expression to be applied to value of expr
→ Boolean? Boolean value resulting from applying path to input

JSON

Type: Stream

Textual data of media type application/json

Path

Type: String

JSONPath expression

Implementations MUST support at least the following subset of JSONPath:

Syntax Element Description Examples
$ root identifier $
[<selector>] child segment selects one child of a node; contains one name selector (single- or double-quoted string using JSON escaping rules) or index selector (non-negative decimal integer) $['foo'], $.foo["bar"], $.bar[0], $.bar[42]
.name shorthand for ['name'] $.foo, $.foo.bar, $.bar[42].baz

Implementations MAY in addition support other JSONPath constructs, for example:

Syntax Element Description Examples
[<selector>] index selector with negative integer array index (counts from the end of the array) $.bar[-1]
[<selectors>] non-empty, comma-separated sequence of selectors $.foo['bar','baz'], $.bar[0,1,2,3,5,7,11]
..[<selectors>] descendant segment: selects zero or more descendants of a node $.foo..["bar"]
..name shorthand for ..['name'] $.foo..bar
* wildcard selector: selects all children of a node $.foo[*], $[*]
.* shorthand for [*] $.foo.*, $.*
..* shorthand for ..[*] $.foo..*, $..*
[start:end] array subset by range of indices (including the item at start and excluding the item at end $.bar[2:5], same as $.bar[2,3,4]
[start:] array subset from start to end of array $.bar[2:]
[:n] the first n array items $.bar[:4]
[-n:] the last n array items $.bar[-3:]
[start:end:step] array slice selector
[?<logical-expr>] filter selector: selects particular children using a logical expression
@ current node identifier (valid only within filter selectors) $.bar[[email protected]==42]

References for JSONPath