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

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