TD: Ensure security metadata can be parsed as plain JSON

[benfrancis]

The current text of the charter says:

Refactor security schemes to use Protocol Binding ontologies for protocol-specific security schemes

My understanding is that this would be done via TD context extensions, by referencing a protocol binding template ontology in the @context member.

Is there a way to achieve this whilst still allowing Consumers to parse security metadata as plain JSON and not require RDF processing or JSON-LD prefix expansion?

I think this has been achieved in the past by hard-coding prefixes (e.g. htv) inside the top level Thing Description context, but I'm not sure this will work if WoT Binding Templates is a registry where bindings are modified, added and removed out of sync with the TD specification.

This is important so that the (mandatory) security metadata can be parsed by Consumers which don't support full JSON-LD/RDF parsing.

[egekorkan]

I think we need to specify somewhere that our specifications should not require JSON-LD parsing or knowledge. So security metadata should be available as plain JSON in a somewhat hardcoded way like we did with protocol option prefixes.

[benfrancis]

security metadata should be available as plain JSON in a somewhat hardcoded way like we did with protocol option prefixes.

That was my thought too, but how would that work if the Thing Description context is fixed in the Thing Description specification but security mechanisms are defined via an ever expanding registry? A prefix would have to be added to the Thing Description context every time a new ontology is added to the WoT Binding Templates registry, or a new version of an ontology is released.

[egekorkan]

A prefix would have to be added to the Thing Description context every time a new ontology is added to the WoT Binding Templates registry, or a new version of an ontology is released.

We should not expand the TD context. They would be simply links in the context to other ontologies.

[benfrancis]

@egekorkan wrote:

We should not expand the TD context. They would be simply links in the context to other ontologies.

Yes, but the context will still continue to need editing beyond the publication of the Thing Description specification. Is that allowed?

Here is the current content of the @context member of https://www.w3.org/2022/wot/td/v1.1

  "@context": {
    "td": "https://www.w3.org/2019/wot/td#",
    "jsonschema": "https://www.w3.org/2019/wot/json-schema#",
    "wotsec": "https://www.w3.org/2019/wot/security#",
    "hctl": "https://www.w3.org/2019/wot/hypermedia#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "dct": "http://purl.org/dc/terms/",
    "htv": "http://www.w3.org/2011/http#",
    "tm": "https://www.w3.org/2019/wot/tm#",
    "@vocab": "https://www.w3.org/2019/wot/td#",
    "license": {
      "@id": "http://purl.org/dc/terms/license"
    }

If security mechanisms are defined in external protocol binding ontologies (in protocol binding template documents) rather than inside the Thing Description specification, then every time a new ontology is defined a new member would need to be added to this map in order to hard code its prefix for plain JSON parsers. Do you see my point?

It changes the nature of security mechanisms from a static set of options in the Thing Description specification to an ever expanding registry which will continue to grow after the Thing Description specification is published.

[egekorkan]

Ok, now I understand your point. First, the wotsec will stay there but its contents will be limited to abstract schemes like nosec, combo, auto, and maybe apikey. All other schemes must look like this TD example. This requires for plain JSON parsers to have the prefixes in there hardcoded in their stack and they need to of course know what they have implemented. E.g. if a Consumer sees scheme": "ace:ACESecurityScheme but does not implement ACE Auth, it needs to fail early and say it cannot consume and interact with the Thing.

Now the question is of course how can a Consumer keep track of all the possible prefixes? There is some initial proposal at https://github.com/w3c/wot-thing-description/issues/1774 but the TD context cannot be changed all the time with new prefixes. The Consumers have to use some sort of registry to learn about them. The fact that the htv prefix is in the TD context is nothing but a convenience feature we put so that at least one protocol vocabulary is in the TD context. It should be moved out as well.

[benfrancis]

OK, https://github.com/w3c/wot-thing-description/issues/1774 could provide a solution but I think it would have to extend beyond the TD specification (i.e. the prefixes hardcoded in the TD context) to all protocol binding templates which define security schemes. Presumably the protocol binding template would need to define the prefix which TDs must always use to reference its ontology? Then any Consumer which implements the protocol binding will recognise the security metadata without needing to parse it as JSON-LD and expand prefixes.

As you say in the issue this kind of goes against the principles of JSON-LD, but is the only way I can see to maintain compatibility with plain JSON Consumers.

[egekorkan]

Presumably the protocol binding template would need to define the prefix which TDs must always use to reference its ontology?

I think that this should become indeed a requirement. In a way, it is not really going against JSON-LD principles but it just constraining its usage.

[mmccool]

While an important thing to resolve I don't think it directly impacts the charter, so let me mark this as something we can put into the detailed work items.

[benfrancis]

While an important thing to resolve I don't think it directly impacts the charter, so let me mark this as something we can put into the detailed work items.

It does impact the charter in that the current charter draft says "Define reusable, external security vocabularies".

I'm saying I don't think this detail should be committed to in the charter unless there's a way to make sure security metadata can still be parsed as plain JSON.

It sounds as though there's a potential solution that problem by requiring that binding documents prescribe a prefix to be used for vocabularies. Can we assume there's a consensus on that solution, or at least that a solution must be found?

[mmccool]

I agree that a solution must be found, but it seems we just need to find a way to associate a hardcoded, unique prefix with each security extension in a registry. Security extensions, once registered, also need to be "frozen". A new version will require a new prefix, probably...