Query Language

The Thing Directory API currently supports querying Thing Descriptions using JSONPath expressions.

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/)]	*[ends-with(title, 'Temperature Sensor') and starts-with(created, '2020-03-10')]
TDs with href values starting with http	not supported	*[starts-with(*//href, 'http')]
TDs with href values (inside the 1st element of properties.status.forms) starting with http	$[?(@.properties.status.forms[0].href=~/^http/)]	??
Second to fourth TD	$[2:4]	*[position()>=2 and position()<4]

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 Sensor*	$[?(@.title=='Terrace Temperature Sensor')].[id,properties]	*[title='Terrace Temperature Sensor']/(id,properties)

Response: Paginated array of selected items

*The 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
}