Query Language

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]

¹ 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)

² The JSONPath and xPath results are inconsistent.

Response: Paginated array of selected items

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
}

Limitations

JSONPath

Filtering with recursive descent

The library doesn't support recursive descent for filtering. E.g. to filter all TDs that have href with http scheme. More info

Filtering with date-time

The library doesn't support ISO8601 date-time comparison. There is no common way or operator for ISO8601 date-time comparison in JSONPath.

Unix time comparison is possible with numeric operators.

XPath

Unclear:

• Filtering TDs with date comparison. E.g. TDs with created after 2020-06-26T09:48:49.322866274Z.
• Filtering TDs with attributes that have a namespace. E.g. TDs with v:firmware equal to 0.9.1