"Thing description" for Directory should be a "Thing Model"

[mmccool]

The TD defined for a Directory service should really be a Thing Model. We should also "template" the "base" parameter (or omit it, and say it needs to be added when the Thing Model is instantiated).

Since we are talking about a class of things, we should have a Thing Model. However, the definition of Thing Model needs to be updated to allow specifying security scheme templates, form templates (including URL templates giving https), etc.

[farshidtz]

Is that the WoT Binding Template?
When I search for WoT Thing Model, I only find content referring to https://www.w3.org/Submission/wot-model/

[mmccool]

Thing Models used to be called "Thing Description Templates" which were basically Thing Descriptions that omitted instance-specific information. But the TD 1.1 spec is attempting to make this a little clearer and allow URL templates (for instance) rather than just omitting hrefs. I think all we need to do is use the following:

"base": "https://{DIRECTORY}"

or the like. I'd rather use a template like this rather than omitting the base so it's clear that it needs to be filled in.

[egekorkan]

@farshidtz there is work going on here: https://w3c.github.io/wot-thing-description/#thing-model

@mmccool: I completely agree :)

[farshidtz]

Thanks. It is clear now. But I think it needs more changes to become a Thing Model:

1. base must be replaced with placeholder, as @mmccool mentioned.

wot-discovery/directory.td.json

Line 51 in fad66ff

"base": "https://tdd.example.com",

2. @type must be ThingModel

Thing Model definitions MUST use the keyword @type at top level and a value of type string or array that equals or respectively contains ThingModel

wot-discovery/directory.td.json

Line 3 in fad66ff

"@type": "Directory",

3. securityDefinitions should be completely omitted? We don't know what definitions/schemes the instances will use.

The Thing Model ... does not contain Thing instance-specific information, such as concrete protocol usage (e.g., IP address), or even a serial number and GPS location. However, Thing Models allows to include, e.g., security schemes if they apply to the entire class of instances the model describes.

wot-discovery/directory.td.json

Lines 8 to 49 in fad66ff

	"securityDefinitions": {
	"oauth2_code": {
	"scheme": "oauth2",
	"flow": "code",
	"authorization": "https://auth.example.com/authorization",
	"token": "https://auth.example.com/token",
	"scopes": [
	"write",
	"read",
	"search"
	]
	},
	"oauth2_client": {
	"scheme": "oauth2",
	"flow": "client",
	"token": "https://auth.example.com/token",
	"scopes": [
	"write",
	"read",
	"search"
	]
	},
	"oauth2_device": {
	"scheme": "oauth2",
	"flow": "device",
	"authorization": "https://auth.example.com/device_authorization",
	"token": "https://auth.example.com/token",
	"scopes": [
	"write",
	"read",
	"search"
	]
	},
	"combo_sc": {
	"scheme": "combination",
	"oneOf": [
	"oauth2_code",
	"oauth2_client",
	"oauth2_device"
	]
	}
	},

---

My suggestion is to keep the Thing Description as is: An example TD.

[relu91]

The Thing Model is still under discussion, but I don't see any problem in leaving SecurityDenifitions as long as we substitute specific URLs with URL templates.

[zolkis]

When consumed, IMHO it should be a TD, or instance-specific information needs to be shared out of band, right?
When defined, it could be a TM, until exposed (likewise, in other use cases as well).

[mmccool]

@benfrancis can you clarify your downvote, please? Note that I updated the description to clarify that I meant in the spec itself (an actual TDD instance would still return a TD), and that we should need to see Thing Models updated to include templates for security schemes and form templates, since we need those to fully specify what we want for TDDs.

We need to make clear in the TD discussion that TDDs are a use case for Thing Models and suggest updates to the specification of TMs so that they meet our needs (as discussed above).

[benfrancis]

@mmccool Thank you for the clarification, I was indeed confused by your original description. From scanning the F2F meeting minutes I suspected I may have misunderstood that context, but hadn't had chance to catch up yet, so apologies for the misunderstanding. I've removed the downvote.

I just wanted to make sure that a physical device providing a directory service (i.e. a gateway) can use a single Thing Description to describe its directory service in addition to other properties, actions and events representing its own physical affordances.

I'm still not keen on the general idea of inventing a new JSON templating language (Thing Description Templates/Thing Models) just for WoT Thing Descriptions, but I don't have a particular objection to using it as a mechanism to describe the directory API in the WoT Discovery specification itself.

[mmccool]

To clarify, a TDD instance would return a TD, not a TM. The TM is just a template that constrains the TD used by TDDs. We need to take our current "example TD" and turn it into a TM as a starting point. If we're not sure about something (e.g. should we have securityDefinitions) we can just omit them for now, then argue about whether we should add them later. I think we should keep the current TD as an example since it DOES show some of these blanks filled in (eg. security).

[mmccool]

Note we can leave the "scopes" in the forms even in a TM that does not define a securityScheme. They are orthogonal to the use of OAuth, and having consistent scopes across all TDDs is a fine thing.

[mmccool]

Note the data schema for query responses needs some consideration. For instance, the return data schema for XPath 3.1 may not include objects since it is converted from XML. See #248. Also, JSONPath and XPath APIs are only "suggestions" (informative) and may change. If the TM is normative, then including them is troublesome, but perhaps we can mark them as informative (in the TM, and in the introduction).

[farshidtz]

@mmccool

JSONPath and XPath APIs are only "suggestions" (informative) and may change. If the TM is normative, then including them is troublesome, but perhaps we can mark them as informative (in the TM, and in the introduction).

I don't like what I'm about to suggest due to its complexity, but I think that is technically the right way to do it:

Move JSONPath and XPath to another TM kept in an informative section which extends the normative one. TM extension and import: https://w3c.github.io/wot-thing-description/#thing-model-extension-import

[mmccool]

XPath is not going to change, nor should SPARQL. These should be optional but normative. JSONPath is, however, subject to change, and the IETF spec is missing some key features like substring matching, and that’s an issue. We *could* just leave it out. Michael McCool From: Farshid Tavakolizadeh ***@***.***> Date: Friday, February 18, 2022 at 9:01 AM To: w3c/wot-discovery ***@***.***> Cc: Mccool, Michael ***@***.***>, Mention ***@***.***> Subject: Re: [w3c/wot-discovery] "Thing description" for Directory should be a "Thing Model" (#86) @mmccool<https://github.com/mmccool> JSONPath and XPath APIs are only "suggestions" (informative) and may change. If the TM is normative, then including them is troublesome, but perhaps we can mark them as informative (in the TM, and in the introduction). I don't like what I'm about to suggest due to its complexity, but I think that is technically the right way to do it: Move JSONPath and XPath to another TM kept in an informative section which extends the normative one. TM extension and import: https://w3c.github.io/wot-thing-description/#thing-model-extension-import — Reply to this email directly, view it on GitHub<#86 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AA4JY6E33JZIWIUDLAS6IW3U3Y7IJANCNFSM4SYMIX2A>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[mmccool]

There is now a TM in the spec so I am closing this issue.