Define requirements and add section for validation

[mmccool]

How much validation does a directory need to do?

1. If it only supports syntactic queries, is JSONSchema validation sufficient? Do we also use SHACL?
2. If we support SPARQL, do we need to do more to make sure the ontologies used are correct?
3. Is there a subset of TD assertions we should check?

[mmccool]

Maybe there should be an "official" validation process in the TD spec and we should just refer to that.

[egekorkan]

This seems to be an overarching problem across different TFs. There this issue in scripting as well: w3c/wot-scripting-api#238 . You can see my latest comment (w3c/wot-scripting-api#238 (comment)) to see what happens in the playground in addition to the JSON Schema validation

[relu91]

Maybe there should be an "official" validation process in the TD spec and we should just refer to that.

+1 from my side. The only fear that I have is that Scripting API might want to have slightly different requirements when talking about TD validation. For example, a particular affordance might use a not defined SecuritySchema, but other forms are just fine. Should the runtime fails when the TD is consumed? or only if that particular affordance is used?

Probably, it is better to design a modular validation algorithm so that we can refer to it as a whole or we could use only some bits of it.

[mmccool]

For now, perhaps we should replace all references to validation in the text with references to a single section in the Discovery spec, and then from there we can refer to the appropriate way to do it (either our own process, or a reference to the TD spec). Going to update the issue name to include this goal...

[mmccool]

So I added an issue (w3c/wot-thing-description#1043) to the TD repo so this gets discussed in future TD meeting.

[AndreaCimminoArriaga]

Regarding the semantic validation, we need to consider it not because we are using SPARQL but because TDs are JSON-LD framed documents that simplify a JSON-LD document, which is RDF. Since we are using RDF under the hood, the syntactic validation may fall short. Also, if an ontology is built correctly (linking the TD ontology with other ontologies, like SAREF) the SHACL shapes will consider the inherit restrictions that both ontologies define.

[farshidtz]

For SHACL validation, see #143.

[mmccool]

So I'm working on a PR to add appropriate definitions on the TD side, however to fully resolve this issue (and issue #143) we would also have to reference the appropriate level of validation (I define three) for different directory use cases (e.g. with and without semantic processing capabilities) from the WoT Discovery document, which will require another PR on this repo. For the TD PR see w3c/wot-thing-description#1085. The PR still needs a lot of work, but let's consolidate discussion there and try to nail this down. I made a detailed to-do list...

[farshidtz]

With respect to recent additions to TD spec, this section of the spec should be updated: https://w3c.github.io/wot-discovery/#validation

[mmccool]

So https://w3c.github.io/wot-discovery/#validation probably still needs some fixes:

1. First "RECOMMENDED" assertion should state the TDD service is what is doing the validation.
2. We should add an assertion that a TDD "MAY" reject TDs that fail validation. This is implied by the assertion about the error reporting but is not explictly stated (and IMO it needs to be).

[farshidtz]

Another requirement coming from #255 is to allow stateful validation. For example, a TD that has a semver may need to be validated to have a correct version during creation and valid increments during updates.

[mmccool]

Please add extension JSON schema to an appendix so we can reference it, then with the "Minimal validation" comment suggested in issue 371. @farshidtz will create a PR, and with that and the extra sentence to the intro (@farshidtz please include in the same PR) and we can consider that as closing this.

[danielpeintner]

@mmccool has been mentioning in the main call that the JSON schema should be added do the document in the appendix.
FYI: The TD task forces has gone the other way around and removing the schema from the document and just added a link to the actual file (see https://w3c.github.io/wot-thing-description/#json-schema-for-validation).

[egekorkan]

I agree with @danielpeintner and would suggest to not paste the schema into the HTML but simply reference to github (or W3C server) from the appendix.

[farshidtz]

I think he meant including it such that it appears in the rendered spec. As we do with the TM:

wot-discovery/index.html

Lines 2404 to 2406 in eb657af

	<pre class="advisement json">
	<div data-include='directory.tm.json'></div>
	</pre>

Copying the actual JSON inline isn't convenient as you mentioned, especially not in the editor's draft.

Edit: If we give a link to the file on Github, we should at least make sure it will be a versioned permanent link for the releases.