-
Notifications
You must be signed in to change notification settings - Fork 0
Instructions
The content formats used are application/link-format+json, application/senml+json (draft-01) and application/collection+senml+json.
link-format+json is used for link operations and senml+json is used for data items and form items. collection+senl+json is for constructing or inspecting items and links together as a collection.
An index has only links but allows adding links with POST and modifying links with PATCH according to CoRE Resource Directory
If you want to follow along, any REST client should be suitable. I use a chrome plugin called "Advanced REST Client".
For example, you can do: GET http://104.131.134.13:8000/index?rt=thing (accept: application/link-format+json) and get a link to a thing:
[
{
"rt": [
"light",
"thing"
],
"href": "/light/"
}
]
Then you can use the relative reference returned to construct the URL for the next step"
GET http://104.131.134.13:8000/light/ (accept: application/link-format+json) and get links to its (subresource) capabilities:
[
{
"href": "",
"rel": [
"self"
]
},
{
"rt": [
"capability",
"onoff"
],
"href": "onOff",
"rel": "sub"
},
{
"rt": [
"capability",
"colorhs"
],
"href": "colorHS",
"rel": "sub"
},
{
"rt": [
"capability",
"brightness"
],
"href": "brightness",
"rel": "sub"
}
]
Then we can GET http://104.131.134.13:8000/light/onOff/ (accept: application/link-format+json) and receive the following representation which contains links to property subresources and a link which points to a form. The link describes it as a ["form" "item"] that can do a ["change" "action"] on the context resource which is type onoff (self link should have the rt=onoff attrval)
[
{
"href": "",
"rel": [
"self"
]
},
{
"rt": [
"action",
"change"
],
"href": "change",
"rel": [
"form",
"item"
]
},
{
"rt": [
"property",
"currentstate"
],
"href": "currentState",
"rel": "sub"
},
{
"rt": [
"property",
"targetstate"
],
"href": "targetState",
"rel": "sub"
},
{
"rt": [
"property",
"delaytime"
],
"href": "delayTime",
"rel": "sub"
}
]
If you use the schema, you might know ahead of time that you are looking for a "change" ;-) so you could just ask for it: GET http://104.131.134.13:8000/light/onOff/?rt=change and get the link you are seeking:
[
{
"rt": [
"action",
"change"
],
"href": "change",
"rel": [
"form",
"item"
]
}
]
So then you GET the form (in SenML draft core-01 content format for now...): GET http://104.131.134.13:8000/light/onOff/change (accept: application/senml+json)
{
"bn": "/light/onOff/",
"e": [
{
"fv": {
"rel": "action",
"href": "actuation",
"template": [
],
"type": [
"change",
"action"
],
"method": "POST",
"ct": "application/collection+senml+json"
},
"n": "change"
}
]
}
The form item retrieved describes how to change onoff; which is by performing a method=POST to the resource at href=actuation constructed according to a template (TBD) using the content format ct=application/collection+senml+json
Here is the entire "onOff" resource representation with links and items in collection format.
{
"bn": "/light/onOff/",
"e": [
{
"fv": {
"rel": "action",
"href": "actuation",
"template": [
],
"type": [
"change",
"action"
],
"method": "POST",
"ct": "application/collection+senml+json"
},
"n": "change"
}
],
"l": [
{
"href": "",
"rel": [
"self"
]
},
{
"rt": [
"action",
"change"
],
"href": "change",
"rel": [
"form",
"item"
]
},
{
"rt": [
"property",
"currentstate"
],
"href": "currentState",
"rel": "sub"
},
{
"rt": [
"property",
"targetstate"
],
"href": "targetState",
"rel": "sub"
},
{
"rt": [
"property",
"delaytime"
],
"href": "delayTime",
"rel": "sub"
}
]
}
There is a meta-catalog example at thingschema.org that has an entry pointing to this index to bootstrap the discovery:
{
"href": "http://104.131.134.13:8000/index",
"rt": "index",
"ct": ["application/link-format+json", "application/collection+senml+json"]
"comment": "hypermedia demonstrator discovery"
}
The toolkit is written in python and is Apache 2 licenced. It can be downloaded from the github repository at:
[Machine Hypermedia Toolkit source repository and installation instructions] (https://github.com/connectIOT/MachineHypermediaToolkit)
There is a public resource for hosting the schema and JSON-LD context files. thingschema.org
The content of thingschema.org is stored at a github repository: thingschema-content
thingschema.org serves a standard JSON-LD context file that can be used by including "@context": "http://thingschema.org" in your JSON-LD file
In addition there is a WoT interaction model schema and a domain-specific schema for lighting.
In the examples directory there is a model for an instance of a light, and a meta-catalog file with pointers to other resources like IETF Resource Directories, W3C WoT Thingdescriptions, hypercats, or other discovery resources.
Context file: http://thingschema.org/context.jsonld
W3C Interaction Model : http://thingschema.org/wot.jsonld
Lighting domain model: http://thingschema.org/light.jsonld
Meta-catalog: http://thingschema.org/examples/catalogs.jsonld
Example light model: http://thingschema.org/examples/lightmodel.jsonld
Example IPSO Smart Object constructor: http://thingschema.org/examples/IPSO-rm.json
The JSON-LD Playground resource can be used to evaluate semantic graphs produced by these schemas and models. For example, to view a triples representation of the lighting model example, paste the URL for the light model example json file: http://thingschema.org/examples/lightmodel.jsonld into the URL box on the JSON-LD Playground page at: http://json-ld.org/playground/ and click the tab for N-Quads and the model is displayed. Note that this is the model for the live example above:
_:b0 <http://www.w3.org/2000/01/rdf-schema#Resource> _:b1 .
_:b0 <http://www.w3.org/2000/01/rdf-schema#Resource> _:b18 .
_:b0 <http://www.w3.org/2000/01/rdf-schema#label> "light" .
_:b1 <http://thingschema.org/name> "light" .
_:b1 <http://thingschema.org/schema#hasCapability> _:b2 .
_:b1 <http://thingschema.org/schema#hasCapability> _:b7 .
_:b1 <http://thingschema.org/schema#hasCapability> _:b9 .
_:b1 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://thingschema.org/light> .
_:b10 <http://thingschema.org/name> "change" .
_:b10 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://thingschema.org/change> .
_:b11 <http://thingschema.org/name> "move" .
(...)
_:b9 <http://thingschema.org/schema#hasProperty> _:b15 .
_:b9 <http://thingschema.org/schema#hasProperty> _:b16 .
_:b9 <http://thingschema.org/schema#hasProperty> _:b17 .
_:b9 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://thingschema.org/brightness> .