Query Language

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

Text	JSONPath	XPath* (Not Implemented)
IDs of all TDs	$..id	//id
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')]
id of TDs with title ending with Temperature Sensor and created after 2020-03-10	$[?(@.title=~/.*Temperature Sensor/ && @.created=~/2020-03-10/)].id	//*[ends-with(title, 'Temperature Sensor') and starts-with(created, '2020-03-10')]
href of all TDs	$..href	//href
id and properties of TDs with title Terrace Temperature Sensor	$[?(@.title=='Terrace Temperature Sensor')].[id,properties]	//*[title='Terrace Temperature Sensor']/id | //*[title='Terrace Temperature Sensor']/properties

Note for XPath: The sample expressions assume {"items": [TD]} as input in contrast to [TD] for JSONPath. This may be improved with XPath 3.1 which should support array as root element.

JSONPath Result Examples

GET /td?fetch=$[?(@.title=='Terrace Temperature Sensor')]

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
}

GET /td?fetch=$[?(@.title=~/.*Temperature Sensor/)]

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
}

GET /td?fetch=$[?(@.title=~/.*Temperature Sensor/ && @.created=~/2020-03-10/)].id

Query id of TDs with title ending with Temperature Sensor and created after 2020-03-10.

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

GET /td?fetch=$..href

Query href of all TDs.

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

GET /td?fetch=$[?(@.title=='Terrace Temperature Sensor')].[id,properties]

Query id and properties of TDs with title Terrace Temperature Sensor.
Note: The structure of the results may not be 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
}