Skip to content

Query Language

Jump to bottom
Farshid Tavakolizadeh edited this page Sep 3, 2020 · 23 revisions

The Thing Directory API currently supports querying Thing Descriptions using JSONPath and XPath expressions with the help of jsonslice and xpath libraries respectively. The syntax is limited to those implementations.

Filtering

Text JSONPath XPath 3.0
TDs with title Terrace Temperature Sensor $[?(@.title=='Terrace Temperature Sensor')] *[title='Terrace Temperature Sensor']
TDs with title ending with Temperature Sensor $[?(@.title=~/.*Temperature Sensor/) *[ends-with(title, 'Temperature Sensor')]
TDs with title ending with Temperature Sensor and created in March 2020 $[?(@.title=~/.*Temperature Sensor/ && @.created=~/2020-03-10/)]1 *[ends-with(title, 'Temperature Sensor') and starts-with(created, '2020-03-10')]
TDs with form href values starting with http not supported by the library *[*/*/forms/*[starts-with(href, 'http')]]
TDs with version.v:hardware (namespace: v) equal to "1.0" $[?(@.version.'v:hardware'=='1.0') ??
Second to fourth TD $[2:4] *[position()>=2 and position()<4]

1 Because of the & character, the query must be encoded.

Response: Paginated array of TDs

Selection

Text JSONPath XPath 3.0
all id of TDs $[:].id */id
all properties.status objects of TDs $.[:].properties.status */properties/status
all href values $..href //href

Response: Paginated array of selected items

Filtering with selection

Text JSONPath XPath 3.0
id of TDs with title Terrace Temperature Sensor $[?(@.title=='Terrace Temperature Sensor')].id *[title='Terrace Temperature Sensor']/id
id and properties of TDs with title Terrace Temperature Sensor2 $[?(@.title=='Terrace Temperature Sensor')].[id,properties] *[title='Terrace Temperature Sensor']/(id,properties)

Response: Paginated array of selected items

2The JSONPath and xPath results are inconsistent.

Example Results

Query TDs with title Terrace Temperature Sensor 

{
    "items": [
        {
            "@context": "https://www.w3.org/2019/wot/td/v1",
            "created": "2020-03-10T16:21:10.08904288Z",
            "id": "urn:example:terrace/temperature",
            "modified": "2020-03-10T16:21:10.08904288Z",
            "properties": {
                "history": {
                    "forms": [
                        {
                            "contentType": "application/senml+json",
                            "href": "https://example.com/data/terrace/temperature",
                            "op": [
                                "readproperty"
                            ]
                        }
                    ],
                    "type": "number"
                }
            },
            "security": [
                "basic_sc"
            ],
            "securityDefinitions": {
                "basic_sc": {
                    "in": "header",
                    "scheme": "basic"
                }
            },
            "title": "Terrace Temperature Sensor"
        }
    ],
    "page": 1,
    "perPage": 100,
    "total": 1
}

Query TDs with title ending with Temperature Sensor 

{
    "items": [
        {
            "@context": "https://www.w3.org/2019/wot/td/v1",
            "created": "2020-03-09T12:10:06.08402103Z",
            "id": "urn:example:kitchen/temperature",
            "modified": "2020-03-09T12:10:06.08402103Z",
            "properties": {
                "history": {
                    "forms": [
                        {
                            "contentType": "application/senml+json",
                            "href": "https://example.com/data/kitcken/temperature",
                            "op": [
                                "readproperty"
                            ]
                        }
                    ],
                    "type": "number"
                }
            },
            "security": [
                "basic_sc"
            ],
            "securityDefinitions": {
                "basic_sc": {
                    "in": "header",
                    "scheme": "basic"
                }
            },
            "title": "Kitchen Temperature Sensor"
        },
        {
            "@context": "https://www.w3.org/2019/wot/td/v1",
            "created": "2020-03-10T16:21:10.08904288Z",
            "id": "urn:example:terrace/temperature",
            "modified": "2020-03-10T16:21:10.08904288Z",
            "properties": {
                "history": {
                    "forms": [
                        {
                            "contentType": "application/senml+json",
                            "href": "https://example.storage-service.com/data/terrace/temperature",
                            "op": [
                                "readproperty"
                            ]
                        }
                    ],
                    "type": "number"
                }
            },
            "security": [
                "basic_sc"
            ],
            "securityDefinitions": {
                "basic_sc": {
                    "in": "header",
                    "scheme": "basic"
                }
            },
            "title": "Terrace Temperature Sensor"
        }
    ],
    "page": 1,
    "perPage": 100,
    "total": 2
}

Query id of TDs with title ending with Temperature Sensor and created after March 2020

{
    "items": [
        "urn:example:terrace/temperature"
    ],
    "page": 1,
    "perPage": 100,
    "total": 1
}

Query href of all TDs.

{
    "items": [
        "https://example.com/data/kitchen/lamp",
        "https://example.com/data/terrace/temperature"
    ],
    "page": 1,
    "perPage": 100,
    "total": 2
}

Query id and properties of TDs with title Terrace Temperature Sensor

Note: The structure of the results may not be as desired and difficult to consume when there are more than one TD matching the query.

{
    "items": [
        "urn:example:terrace/temperature",
        {
            "history": {
                "forms": [
                    {
                        "contentType": "application/senml+json",
                        "href": "https://example.com/data/terrace/temperature",
                        "op": [
                            "readproperty"
                        ]
                    }
                ],
                "type": "number"
            }
        }
    ],
    "page": 1,
    "perPage": 100,
    "total": 2
}
Clone this wiki locally