From a3cf10d4de476a2c16cbbccf54d2a9ac4c4ea66d Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Tue, 26 Sep 2023 08:54:16 +0200 Subject: [PATCH 01/10] Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index a8f7c22d..7f9fd275 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -2,4 +2,33 @@ 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. \ No newline at end of file +This document gives guidance 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 work with the added vocabulary, 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 validation of forms using the binding template. + +Building upon this set of documents, 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 which can insert rendered +tables into placeholders (`%s`) within an `index.template.index` file. +To be able to create these tables, 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-readble ontology file (`ontology.html`) +which can be used as a alternative representation based on content negotiation. + +Examples of existing binding template files can be found in the `bindings` +directory. + From 5e9f40a167be1a633b0dcfc124aafddd1355d0c1 Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Wed, 22 Nov 2023 16:14:28 +0100 Subject: [PATCH 02/10] fixup! Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 7f9fd275..e889db84 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -1,7 +1,7 @@ # 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. +Thing Description Forms can be extended with annotations that further describe how to access affordances. +These annotations are typically reused from existing 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. ## Components of a Binding Template @@ -9,7 +9,7 @@ This document gives guidance how such vocabularies can be created and how they s 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 work with the added vocabulary, the definition of a +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. From 2f4788fd8ef97a7d9d19660e0b5a7c87d2b167f3 Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Tue, 28 Nov 2023 02:11:06 +0100 Subject: [PATCH 03/10] fixup! Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index e889db84..162a3f5b 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -16,6 +16,8 @@ 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 validation of forms using the binding template. +## Document Rendering Workflow + Building upon this set of documents, 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 which can insert rendered From 73bbd63508bd3049cbbe401383deb86e6ed2c59f Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Tue, 28 Nov 2023 02:12:53 +0100 Subject: [PATCH 04/10] fixup! Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 162a3f5b..7f041f1f 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -16,12 +16,19 @@ 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 validation of forms using the binding template. +## Creating a New Vocabulary + +TODO + ## Document Rendering Workflow -Building upon this set of documents, 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 which can insert rendered -tables into placeholders (`%s`) within an `index.template.index` file. +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 the resulting tables are inserted. To be able to create these tables, the ontology vocabulary needs to be brought into the right form using a mapping (in `mapping.ttl`) based on SHACL (Shapes Constraint Language). From 2dbb28281679fc48a65d3ba87ac49d436c21862f Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Wed, 29 Nov 2023 08:30:08 +0100 Subject: [PATCH 05/10] fixup! Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 7f041f1f..855ae2fa 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -2,7 +2,7 @@ Thing Description Forms can be extended with annotations that further describe how to access affordances. These annotations are typically reused from existing 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. +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 @@ -18,7 +18,25 @@ to enable automatic validation of forms using the binding template. ## Creating a New Vocabulary -TODO +In order to create a new Binding Template, you need to first conceptualize +how the different parameters that can be set for a procotocol 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 cast into 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 From c82ef14e5d03fb2124202e007f9e77f758ecbe49 Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Thu, 30 Nov 2023 08:24:28 +0100 Subject: [PATCH 06/10] fixup! Expand vocabulary creation guide --- VOCABULARY-CREATION-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 855ae2fa..1bf1843e 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -1,6 +1,6 @@ # Vocabulary Creation Guide -Thing Description Forms can be extended with annotations that further describe how to access affordances. +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. From c8c8a7dd041a9ce1a44697de42d4f1f064254f40 Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Thu, 30 Nov 2023 11:48:51 +0100 Subject: [PATCH 07/10] fixup! Expand vocabulary creation guide Co-authored-by: danielpeintner --- VOCABULARY-CREATION-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 1bf1843e..3c258948 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -19,7 +19,7 @@ to enable automatic 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 procotocol interaction can +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 From ae20140dfef5ec8ea07209a83fd371007b7eb24b Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Thu, 30 Nov 2023 11:49:10 +0100 Subject: [PATCH 08/10] fixup! Expand vocabulary creation guide Co-authored-by: danielpeintner --- VOCABULARY-CREATION-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 3c258948..80a17b43 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -53,7 +53,7 @@ into the right form using a mapping (in `mapping.ttl`) based on SHACL 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-readble ontology file (`ontology.html`) +(`index.html`) file but also a human-readable ontology file (`ontology.html`) which can be used as a alternative representation based on content negotiation. Examples of existing binding template files can be found in the `bindings` From f7d58dcb5cd1e4bce87d95321c6a9c7d9a6b3fe2 Mon Sep 17 00:00:00 2001 From: Jan Romann Date: Thu, 30 Nov 2023 11:49:22 +0100 Subject: [PATCH 09/10] fixup! Expand vocabulary creation guide Co-authored-by: danielpeintner --- VOCABULARY-CREATION-GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index 80a17b43..acb37729 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -54,7 +54,7 @@ into the right form using a mapping (in `mapping.ttl`) based on SHACL 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 a alternative representation based on content negotiation. +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. From 0244830368ff5afaf2a0bf73f6200ae9c65882ee Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Wed, 6 Dec 2023 16:52:01 +0100 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Cristiano Aguzzi Co-authored-by: Jan Romann --- VOCABULARY-CREATION-GUIDE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/VOCABULARY-CREATION-GUIDE.md b/VOCABULARY-CREATION-GUIDE.md index acb37729..d9dab642 100644 --- a/VOCABULARY-CREATION-GUIDE.md +++ b/VOCABULARY-CREATION-GUIDE.md @@ -14,7 +14,7 @@ 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 validation of forms using the binding template. +to enable automatic syntactic validation of forms using the binding template. ## Creating a New Vocabulary @@ -28,7 +28,7 @@ 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 cast into vocabulary terms based on the Web +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 @@ -46,8 +46,9 @@ 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 the resulting tables are inserted. -To be able to create these tables, the ontology vocabulary needs to be brought +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).