A thing description (TD) can be added to the SDT on creation, or added/updated after (PUT /sdts/{uuid}/td).
The only required field is title.
See bellow a sample of a full TD:
{
"title": "Thingin TD example 1",
"description": "TD to access IFC Site",
"id": "http://stephanie/test/ifc/20230317_2/ifc-0ug5o$fuT5wAcMsNHZcJQd",
"@type": [
"https://w3id.org/bot#Site"
],
"securityDefinitions": {
"bearer_sc": {
"scheme": "bearer",
"in": "header",
"format": "jwt"
}
},
"security": "bearer_sc",
"actions": {
"GetBlobs": {
"forms": [
{
"href": "https://coreapi.di.thinginthefuture.com/avatars/d6c989a1-bb93-574d-9983-e6f4d1e7b6c8/blobs",
"htv:methodName": "GET",
"op": "invokeaction"
}
],
"description": "Get blobs"
}
},
"properties": {},
"events": {}
}
In the TD, actions must be defined in an actions property. The actions defined here can be executed with a dedicated endpoint.
The action must have a form (forms property) which contains an href property. If the htv:methodName property is not declared in the form, POST method will be used
Currently, no specific access control is made: if a user can read the SDT info, he can execute a command on the SDT
Endpoint: POST /sdts/{uuid}/executeCommand
payload
{
"command_name": <Action_name>,
"parameters": {...}
}
<Action_name> is the name of the action defined in the actions section of the TD
Several types of actions are available: actions withut parameters, actions with url parameters and actions with parameters in a body. These actions are describes below
The command result is something like that:
{
"command_name": <Action_name>,
"status": "executed",
"command_result": ...
}
The command result is the result of the command execution (can be string, json object ...).
If the mime-type of the execution of the command is not application/json, the result will be directly the result from the command execution with the corresponding mime-type
Example of an extract from the TD:
"GetBlobs": {
"forms": [
{
"href": "https://coreapi.thinginthefuture.com/avatars/d6c989a1-bb93-574d-9983-e6f4d1e7b6c8/blobs",
"htv:methodName": "GET",
"op": "invokeaction"
}
],
"description": "Get blobs"
}
to execute this action, only the command_name property is required
{
"command_name": "GetBlobs"
}
To define actions that have URL parameters, uriVariables field from the TD is used
Example of an extract from the TD:
"GetInfosOnZipcode": {
"uriVariables": {
"country": {
"type": "string",
"description": "Country code"
},
"postal-code": {
"type": "string",
"description": "Postal code"
}
},
"forms": [
{
"href": "https://api.zippopotam.us/{country}/{postal-code}",
"htv:methodName": "GET",
"op": "invokeaction"
}
],
"description": "Get infos on a zip code for a country"
}
to execute this action, parameters must be filled with values for the definied url variables
Ex:
{
"command_name": "GetInfosOnZipcode",
"parameters": {
"country": "FR",
"postal-code": 44470
}
}
Optional variables can be specified prefixed by a & or a ? (see rfc6570). Ex:
"href": "https://myurl/update?param1={param1}{¶m2}
"href": "https://myurl/update{?param2}
Here param1 is mandatory (first sample) while param2 is optional and will be expanded as ¶m2=<value> or ?param2=<value> if present
additional variables can be used in href: {platform_base_url} which is the bas_url defined on the platform level and {id_on_platform} which is the id of the SDT on the platform defined on the SDT level. The user can override them in the parameter map
To define actions that have a body parameter, input field from the TD is used. The payload to send must be a json object. But the result can have another mime-type.
Example 1 : payload with only 1 field, another mime-type returned
"CreateSvgGraphvizDiagram": {
"forms": [
{
"href": "https://kroki.io/graphviz/svg",
"op": "invokeaction",
"response": {
"contentType": "image/svg+xml"
}
}
],
"input": {
"properties": {
"diagram_source": {
"description": "textual representation of GraphViz diagram",
"type": "string"
}
},
"required": [
"diagram_source"
],
"type": "object"
},
"description": "Generate a svg for this graphViz diagram"
}
Example to call this action
{
"command_name": "CreateSvgGraphvizDiagram",
"parameters": {
"diagram_source": "digraph G {Hello->World}"
}
}
Example 2 : payload with optional fields (update can be done on 2 differnt properties)
"UpdateInfos": {
"forms": [
{
"href": "https://coreapi.di.thinginthefuture.com/avatars/update/set/d6c989a1-bb93-574d-9983-e6f4d1e7b6c8",
"htv:methodName": "PUT",
"op": "invokeaction"
}
],
"input": {
"properties": {
"http://www.opengis.net/gml/pos": {
"properties": {
"coordinates" : {
"type": "array",
"description":"2D coordinates long and lat",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
"type": {
"const": "Point",
"type": "string"
}
},
"required": [
"type",
"coordinates"
],
"type": "object"
},
"http://www.w3.org/2006/vcard/ns#given-name": {
"description": "Name of the avatar",
"type": "string"
}
},
"type": "object"
},
"description": "Update infos (name and/or coordinates)"
}
Example to call this action (only pos will be updated)
{
"command_name": "UpdateInfos",
"parameters": {
"coordinates": [
2.3,
48.86
],
"http://www.opengis.net/gml/pos": true
}
}
For object types, the properties will be inspect recursively. A limitation is that a variable can only appear once in the payload description.
Only the required properties must be defined in the user parameters, if the property is not required, it will be included only if it appears in user parameters. As a consequence, to include an object, the name of the object must be present in the user parameters to be included (but the value will be ignored.
A property that have a fixed value must have a const property wich contains the fixed value.
If the input has a type object but without defined properties, the entire payload is taken from the parameters and its name must be payload.
No check is done on the basic type from TD (example: a number param can be given as string).
If the security defined in the TD is "nosec", no authentification header will be passed, for all other configurations, the auth defined in the platform will be used