General information about the Web of Things can be found athttps://www.w3.org/WoT/.
A Thing Description describes the metadata and interfaces of Things, where a Thing is an abstraction of a physical or virtual entity that provides interactions to and participates in the Web of Things. Thing Descriptions provide a set of interactions based on a small vocabulary that makes it possible both to integrate diverse devices and to allow diverse applications to interoperate. Thing Descriptions, by default, are encoded in a JSON format that also allows JSON-LD processing.
- Call information: We use the W3C Calendar. You can find the next WoT TD/Binding Templates calls athttps://www.w3.org/groups/wg/wot/calendar.
- Wiki (contains agenda):https://www.w3.org/WoT/IG/wiki/WG_WoT_Thing_Description_WebConf
- Contribution rules
- Latest Editor's Draft(syncs to this repository's main branch)
- Recommendations:
- Other deliverables:
If you have followed theContribution rulesand want to contribute, please follow the instructions below.
Part of the document is automatically rendered using theSTTL.jsRDF template engine and Node.js.
Any change to the document must be performed on the main HTML templateindex.template.html
,and not onindex.html
.
To renderindex.html
,along with SVG figures, run:
npm install
to install all the dependenciesnpm run render
to render all the files
You can also invoke the rendering script directly:
./render.sh
Requirements: Node.js 16,GraphViz.
The script will first download and install some dependencies (triple store, Node.js dependencies) and then execute the JS scriptrender.js
.
The latter should always be executed withinrender.sh
since it requires some env variables to be set first.
For Windows users, the script should be run in aCygwin shell.The Git package from Cygwin distribution should not be used. Alternative Git client distribution such asGit for Windowsworks better when you encounter an issue building the document using Cygwin.
The repository is equipped with git hooks that automate the rendering process. To enable them, runnpm install
in the root folder. The hooks will render the documents automatically at every commit.
If you run the rending process manually or you do not want to execute the automatic process add the--no-verify
option to your commit command.
We use Prettier to automatically format the files, such that we have small git diffs in Pull Requests.
Make sure to runnpm run format
before committing your files.
If not, a GitHub action will format them by overwriting your last commit.
To generate the implementation report, including a list of normative assertions, issue the following command:
npm run assertions
A draft implementation report will be generated and output to
testing/report.html
which will use relative links back up toindex.html.
The input to this process isindex.html
(notindex.html.template
) so make sure to executenpm run render
first.
For this to work, the assertions need to be marked up as in the following examples and follow RFC2119 conventions:
<spanclass= "rfc2119-assertion"id= "additional-vocabularies">
A JSON TD MAY contain additional optional vocabularies that are not in the Thing Description core model.
</span>
<spanclass= "rfc2119-assertion"id= "additional-vocabularies-prefix">
Terms from additional optional vocabularies used in a JSON-TD MUST carry a prefix for identification within the key
name (e.g.,<tt>"http:header"</tt>).
</span>
The assertions must be marked up as follows:
- Enclose each assertion in a span.
- Mark the span with a unique id. It is recommended that the section id be followed by a short unique name for the specific assertion.
- Mark the span with a 'class' attribute set to
rfc2119-assertion
. - Include one (and only one) instance of the RFC2119 keywords (MUST, MAY, etc.) in capitals. This markup does not change the rendering; it just clearly indicates and uniquely names the assertion.
It is strongly recommended to make assertions independent of context. In particular, avoid using pronouns or relational expressions referring to previous statements not included in the assertion. Such references can always be replaced with their antecedent ( "dereferenced" ) without changing the meaning, and this is less ambiguous anyway. For example, instead of using "this serialization", use "a JSON-TD serialization".
Also, assertions should ideally only constrain one item. Multiple constraints should be stated in separate sentences.
Note that the above rendering process also assigns each table entry a unique ID and these are also listed in the table included in the implementation report.
Other data, e.g., data from test results, test specifications, and implementation descriptions, are also needed to complete the implementation report. Seetesting/README.md for details.
The generation of the implementation report also generates a CSS file
testing/atrisk.css
that highlights at-risk items in the generatedindex.html
.The at-risk
items are listed intesting/inputs/atrisk.csv
.If at-risk items are
updated, to update the at-risk highlighting the implementation report
needs to be generated first, and then the rendering.
The W3C WoT collects known implementations athttps://www.w3.org/WoT/developers/.Implementations of the Thing Description are found under all categories
We use the GitHub labels found athttps://github.com/w3c/wot-thing-description/labels.Please try to reuse the labels before creating new ones.
In addition to the TD specification, the Working Group maintains additional resources that are relevant for implementers. These are categorized below, and their use cases are explained.
The present specification introduces the TD Information Model as a set of constraints over different vocabularies. The current list of vocabularies is found underthe namespaces section.
By default, if a user agent does not perform any content negotiation, human-readable HTML documentation is returned instead of the RDF document.
To perform content negotiation, clients must include the HTTP headerAccept: text/turtle
in their request.
The working documents are in theontologyfolder.
We provide a JSON-LD context file to reference the TD ontology within JSON-LD documents, including TDs.
The working document can be found atcontext/td-context-1.1.jsonld,and the version-specific context file can be retrieved from the@context
value of a TD 1.0 or TD 1.1 instance.
Notethatcontext/td-context-1.1.jsonldis the result of the rendering process and should not be edited manually.
In practice, the rendering process mergescontext/td-context.jsonld,context/json-schema-context.jsonld,context/wot-security-context.jsonld,context/hypermedia-context.jsonld.
You can find more information on using the context atthe Appendix of the TD specification.
We provide JSON Schema for TD and TM instances. The working documents are found under thevalidationfolder, and specific versions are linked to the Thing Description specification. These can be used for the purposes below among others:
- TD and TM validation
- Type generation for programming languages
Notethat TM Schema is generated from the TD schema using thetmSchemaGenerator.js
script.
Each commit here will sync to the master, which will expose the content tohttp://w3c.github.io/wot-thing-description/.
To make contributions, please provide pull requests to the appropriate files,
keeping in mind that some files, most notablyindex.html
andtesting/report.html
,
as well as most files undervisualization
,are
autogenerated and should not be modified directly.
See GitHubhelpfor
information on how to create a pull request.
Some documents of this repository are not required to be kept in the upstream branch (main branch). They are deleted but are recorded below with a link pointing to a tagged branch:
- Review of the main document for TAG:https://github.com/w3c/wot-thing-description/blob/CR-request/tag-review.html