search

w3c / wot-scripting-api

Web of Things (WoT) Scripting API
http://w3c.github.io/wot-scripting-api/
Other
42 stars 28 forks source link

Link the API specification to the Thing Description version #225

Open relu91 opened 4 years ago

relu91 commented 4 years ago

The API document is closely related to the Thing Description document:

In conclusion, the WoT WG decided to explore the third option that closely follows the [WOT-TD] specification.

However, in the document, it is not clearly stated to which Thing Description version the API spec is referring to.

Other related issues:

224

relu91 commented 3 years ago

I think we discussed this issue during one of our calls. If I recall correctly the agreement was that linking to the TD document should sufficient to guide the reader to the right version TD version. However, since TD document and TD versions might differ (i.e., TD document is a URL, TD version is a semantic versioning number). I'd propose to state somewhere in the document (may next to the sentence quoted in the first comment) that we are following Thing Description version 1.1. Later we can update it so that in each published document we track the right TD version.

@zolkis @danielpeintner opinions?

zolkis commented 3 years ago

On the last TPAC in a different group the argument was that people always check the latest. So we need to do our best to keep them in sync.

I don't oppose a formal bound that compel us to follow up on TD versions and URL.

In the same paragraph, we should outline what exactly the dependencies are, and we should agree/follow up on them with the TD task force.

The generic concepts (interactions/prop/act/event, consumed, exposed, discovery) are not TD related. Some TD parts like security concern the runtime and not Scripting. When consuming, the runtime encapsulates the details and exposes interactions. Details that might creep up to applications are about data format (DataSchema or contentType stream). In general, TD validation algorithms are the biggest dependency, but they should be owned by the TD spec.

danielpeintner commented 3 years ago

In general, TD validation algorithms are the biggest dependency, but they should be owned by the TD spec.

Yes, that would be ideal

JKRhb commented 10 months ago

Do you think this issue could be resolved by stating that the Scripting API should be compatible with all TD versions? Or could it even be closed?

zolkis commented 10 months ago

No, the API won't be compatible with an evolving TD spec all the time. No one can guarantee (and test) that. It should be in a release note for every API version.

danielpeintner commented 7 months ago

In the versioning call we worked on https://github.com/w3c/wot-thing-description/pull/1969.

We, as the Scripting task force, should decide and work on the scheme for our specification. see the placeholder here https://github.com/w3c/wot-thing-description/pull/1969/files#diff-5a1e620a21f1c28a342f17f7b625150e976e6d75bc4bc1ba8c24dad36d9249b8R84

FYI: the proposed versioning for JSON schema is as follows. Note: The part after the + sign is just metadata and indicates the TD dependency

  • json-schema-td-2.0.0+td-2.0.0 -> First publication after REC
  • json-schema-td-2.0.1+td-2.0.0 -> Fixed a typo in JSON Schema
  • json-schema-td-2.1.0+td-2.0.0 -> Added a new feature to JSON Schema
  • json-schema-td-2.0.2+td-2.0.1 -> Published an errata in TD spec
  • json-schema-td-3.0.1+td-2.0.1 -> We decided to move to a different version of JSON

In a similar spirit we could do the following for our 3/4 items that need versioning:

1. wot-thing-model-types (TypeScript definition for the WoT Thing Model)

Note: auto-generated based on JSON Schema. From a users point of view the TD dependency would be nice to see as well.

2. wot-thing-description-types (TypeScript definition for the WoT Thing Description)

3. wot-typescript-definitions (Scripting API)

Note: Personally I think the name "wot-typescript-definitions" is not clear/correct anymore. Do we want to change/adapt it?

4. Question: Do we want to have/need an own version for the spec itself.

e.g., a spec text change only which does not affect the others parts above. My take is we need a version there as well.

Many questions and thoughts we might want to discuss in next weeks call.