Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add additional explanations to vocabulary creation guide #298

Merged
merged 10 commits into from
Dec 6, 2023
63 changes: 60 additions & 3 deletions VOCABULARY-CREATION-GUIDE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,62 @@
# Vocabulary Creation Guide

Thing Description Forms can be extended with annotations on how to activate affordances.
These annotations are typically from protocol vocabularies that need to exist separately from the binding template document.
This document gives guidance how such vocabularies can be created and how they should be used together with the templates and tools provided.
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.

<!-- TODO: Add examples -->

## 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).
egekorkan marked this conversation as resolved.
Show resolved Hide resolved

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.
<!-- TODO: Expand template for binding templates -->