search

WebThingsIO / api

Web Thing API Specification
http://iot.mozilla.org/wot/
Other
164 stars 24 forks source link

Replace web thing types with capability schemas #104

Closed benfrancis closed 6 years ago

benfrancis commented 6 years ago

This pull request removes the Web Thing Types section and adds a new Semantic Annotations section to the Web thing Description which explains how to use capability schemas with @context and @type annotations.

A rendered HTML version is viewable at https://benfrancis.github.io/wot/

benfrancis commented 6 years ago

OK, done. I've also updated the example on the schema repository to match.

@hobinjk Any comments before I land this change?

benfrancis commented 6 years ago

@hobinjk I like your 9th grade English teacher already! Thanks for this feedback, will go through in more detail on Monday :)

benfrancis commented 6 years ago

OK @hobinjk, I was thinking about your comment about being able to get from this document to a complete annotated Thing Description which the gateway can make best use of.

I've re-organised the Thing Description part of the specification a bit. It now starts with two (rather than one) initial examples. The first is a very simple Thing Description for an On/Off Switch with a single property. The other is a more complex example with actions, events, links and semantic annotations.

I've then moved the @context and @type members out of their own scary sounding "semantic annotations" section, so they're now just alongside all the other members.

I've also added @context and @type annotations to the Property, Action and Event object examples to show them in action.

I also took the opportunity to re-write a few parts which have become outdated and include some proper references.

Sorry this is a lot to review at once, but hopefully it's now a bit more obvious how to arrive at a complete Thing Description.

Would you mind re-reviewing? Some of the sentences are maybe still a bit complex, but some of these concepts (e.g. "capability type schemas") are a bit hard to explain concisely.

The updated version is viewable at https://benfrancis.github.io/wot

I agree that the schemas web site could also benefit from more examples, but we can do that separately.