Skip to content

Java API for Thing Descriptions of the Web of Things

License

Notifications You must be signed in to change notification settings

oeg-upm/wot-jtd

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

70 Commits
 
 
 
 
 
 
 
 

Repository files navigation

Java API for Thing Descriptions of WoT (JDTs)

Version] Maven Central License GitHub stars

The JDT is an ORM implementation of the current Thing Description model standardised by the W3C Web of Things group. The current features are:

  • Serialise:
    • Serialise any Thing Description as a Java Object, i.e., a JDT
    • Serialise a JDT from a JSON-LD framed document
    • Serialise a JDT from a set of RDF triples
  • Round trip-translation:
    • Translate from a JSON-LD framed document into a set of equivalent RDF triples
    • Translate a set of RDF triples into its equivalent JSON-LD framed document
  • Validation

If you have any feedback or feature suggestion, please let us know posting an issue with the label feedback

Table of contents

  • Installation
  • Model
  • Usage:
    • Serialisation of JTDs:
      • From JSON-LD framed document
      • From RDF triples
    • Deserialisation of JTDs:
      • To JSON-LD framed
      • To RDF triples
    • JDT validation:
      • Using SHACL shapes
      • Using JSON schema (coming soon)
      • Using restrictions in the model (coming soon)

Installation:

Import the JDTs library as a maven dependency, be sure to specify the latest version:

<dependency>
  <groupId>es.upm.fi.oeg</groupId>
  <artifactId>wot-jtd</artifactId>
  <version>0.2.2</version>
</dependency>

Alternatively, the dependency can be installed manually. First, download the latest jar from the releases section, and then install the dependency as follows (be sure to specify the latest version):

mvn install:install-file -Dfile=wot-jtd.jar -DgroupId=es.upm.fi.oeg -DartifactId=wot-jtd -Dversion=0.2.2 -Dpackaging=jar

Check our Maven Central Repository page to discover other installation options like Gradle Groovy or Kotlin, Scala, and others.

Model

The JDT library implement as Java objects the whole model, and its restrictions, defined in the Thing Description standard. The overview of the model is the following:

Thing Description model

Usage

Serialisation of JTDs:

For the next examples, let's assume the following java variables containing the same Thing description:

String strJsonTD = "{ \"@context\": \"https://www.w3.org/2019/wot/td/v1\",\n" +
" \"id\": \"urn:dev:ops:32473-WoTLamp-1234\",\n" +
" \"title\": \"MyLampThing\",\n" +
" \"securityDefinitions\": { \"nosec_sc\": { \"scheme\": \"nosec\" }},\n" +
" \"security\": \"nosec_sc\",\n" +
" \"properties\": {\n" +
"     \"status\": {\n" +
"         \"type\": \"string\",\n" +
"         \"forms\": [{\"href\": \"https://mylamp.example.com/status\"}]\n" +
"     }\n" +
" }\n" +
"}";
Model modelTD = ModelFactory.createDefaultModel();
String strRdfTD = "@prefix dc: <http://purl.org/dc/terms/> .\n" +
"@prefix td: <https://www.w3.org/2019/wot/td#> .\n" +
"@prefix jsonschema: <https://www.w3.org/2019/wot/json-schema#> .\n" +
"@prefix hctl: <https://www.w3.org/2019/wot/hypermedia#> .\n" +
"\n" +
"<urn:dev:ops:32473-WoTLamp-1234>\n" +
"  dc:title \"MyLampThing\" ;\n" +
"  td:hasPropertyAffordance [\n" +
"      a <https://www.w3.org/2019/wot/json-schema#StringSchema> ;\n" +
"      jsonschema:propertyName \"status\" ;\n" +
"      td:hasForm [ hctl:hasTarget <https://mylamp.example.com/status> ]\n" +
"  ] ;\n" +
"  td:hasSecurityConfiguration <https://json-ld.org/playground/nosec_sc> ;\n" +
"  td:securityDefinitions [ td:scheme \"nosec\" ] .";

##### Read the string variable into the jena model
modelTD.read(new ByteArrayInputStream(strRdfTD.getBytes()), null, "Turtle");

The following serialisation operations consists of building a JTD object Thing from either a JSON-LD framed representation or a set of RDF triples.

From JSON-LD framed document
JsonObject jsonTD = JTD.parseJson(strJsonTD);
Thing thing = Thing.fromJson(jsonTD);
thing = (Thing) JTD.instantiateFromJson(jsonTD, Thing.class); # Alternativelly

Notice that using the method JTD.instantiateFromJson(jsonTD, Thing.class) any other class from the model can be serialised.

From RDF triples

In order to build a JTD object from a set of RDF triples there are two main methods:

A) Build a list of JTDs in case that the triples contain more than one Thing resource.
List<Thing> things = fromRDF(modelTD)
B) Build a unique JTDs providing the RDF resource URI.
Thing thing = fromRDF(modelTD, "urn:dev:ops:32473-WoTLamp-1234")

Deserialisation of JTDs:

To JSON-LD framed
JsonObject jsonTD = thing.toJson()
jsonTD = JTD.toJson(thing) # Alternativelly

Notice that using the method JTD.toJson(thing) any other class from the model can be deserialised.

To RDF triples
Model modelTD = JTD.toRDF(thing)
 # Alternativelly
JsonObject jsonTD = thing.toJson()
modelTD = JTD.toRDF(jsonTD)

Notice that using the method alternative JTD.toRDF(jsonTD) there is actually no need to serialise the JSON-LD framed jsonTD as a Java object, it can be directly translated into RDF.

JDT validation

Using SHACL shapes

Currently, the Web of Things provides an official SHACL shape document for validating Thing Descriptions. This shape, or any other, can be used to validate a JTD Thing as follows:

String shapesURI = "https://raw.githubusercontent.com/w3c/wot-thing-description/main/validation/td-validation.ttl"
Model shapesGraph = RDFDataMgr.loadModel(shapesURI, Lang.TURTLE);
ValidationReport shapeReport = JTD.validateWithShape(thing, shapesGraph);
Using JSON schema (comming soon)
Using restrictions in the model (comming soon)

Support or Contact

WoT-JTD was created by Andrea Cimmino ([email protected]) and Raúl García Castro ([email protected]) at the Universidad Politécnica de Madrid in the research group Ontology Engineering Group.