From aeb1649337590f72cef9f8b4d272c7a927a3967f Mon Sep 17 00:00:00 2001 From: ashimura Date: Tue, 28 May 2024 13:00:34 +0900 Subject: [PATCH] add VOCABULARY-CREATION-GUIDE.md --- .../note4/VOCABULARY-CREATION-GUIDE.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 publication/note4/VOCABULARY-CREATION-GUIDE.md diff --git a/publication/note4/VOCABULARY-CREATION-GUIDE.md b/publication/note4/VOCABULARY-CREATION-GUIDE.md new file mode 100644 index 0000000..d9dab64 --- /dev/null +++ b/publication/note4/VOCABULARY-CREATION-GUIDE.md @@ -0,0 +1,62 @@ +# Vocabulary Creation Guide + +Thing Description Forms can be extended with annotations that further describe how to activate affordances. +These annotations are typically reused from existing protocol vocabularies that need to exist separately from the binding template document. +This document gives guidance on how such vocabularies can be created and how they should be used together with the templates and tools provided. + +## Components of a Binding Template + +Besides the actual binding template document that is to be used by implementors +(the `index.html` file), there are several additional companion documents which +enable the binding to be used in practice. +To enable TD consumers to understand the reused vocabularies, the definition of a +JSON-LD context file (`context.jsonld`) is necessary. +This file maps the TD-specific vocabulary defined in the binding template to an +OWL ontology (`ontology.ttl`), enabling the use of Semantic Web technologies. +Finally, a JSON schema file (`example-protocol.schema.json`) should be provided +to enable automatic syntactic validation of forms using the binding template. + +## Creating a New Vocabulary + +In order to create a new Binding Template, you need to first conceptualize +how the different parameters that can be set for a protocol interaction can +be mapped to the different types of Interaction Affordances (Properties, +Actions, and Events). +For instance, an HTTP vocabulary for the Web of Things can define vocabulary +terms for the different kinds of methods (e.g., GET, POST, or PUT) that are +usable in requests. +Vocabulary terms can also be more specific to a certain type of Interaction +Affordance or operation type, e.g., Event Affordances or observable Properties. + +The mapping then needs to be described as vocabulary terms based on the Web +Ontology Language (OWL) and – more generally – the Resource Description +Framework (RDF). +This mapping can reuse existing, more general vocabularies and integrate them +into the Web of Things. +However, in cases where there is no pre-existing vocabulary for a protocol, +creating one that is only WoT-specific is also a valid option. + + + +## Document Rendering Workflow + +Building upon the set of documents mentioned above, an automated rendering +process of the binding template document from the ontology can be established. +To do so, a `template.sparql` file needs to be created based on +[STTL](https://ns.inria.fr/sparql-template/), which defines rules for +transforming a source RDF graph into a result text. +The rules are applied to an `index.template.html` file which contains +placeholders (`%s`) where a formatted version of the vocabulary terms +(e.g., a table) can be inserted. +To be able to create a formatted version, the ontology vocabulary needs to be brought +into the right form using a mapping (in `mapping.ttl`) based on SHACL +(Shapes Constraint Language). + +Once the files are in place, they need to be inserted into the top-level +`render.js` file, which can not only create a rendered binding template +(`index.html`) file but also a human-readable ontology file (`ontology.html`) +which can be used as an alternative representation based on content negotiation. + +Examples of existing binding template files can be found in the `bindings` +directory. +