Create echonetExampleTD.td.jsonld

[egekorkan]

I have followed slide 18 onwards of https://raw.githubusercontent.com/w3c/wot/main/PRESENTATIONS/2021-03-online-f2f/2021-03-15-ECHONET-Lite-WebAPI-ECHONET-Consortium.pdf to create this to show how an Echonet TD can look like

[relu91]

<deviceId> is not a URI variable, right? At first glace it might confuse people.

[egekorkan]

It is one as far as I understood. This is a bit of a TM than a TD since it does not have the concrete endpoints. I would imagine that there will be something like abc123 replacing the <deviceId>

[danielpeintner]

Shouldn't it than be something like

"/elapi/v1/devices/{{deviceId}}/properties/brightness"

[egekorkan]

If we are talking about a TM yes, here I just copied their URLs of the slide. Ideally there should be the concrete URI here.

[mmccool]

Comments (some discussed in main call July 14 2021):

• An example is useful but is not a spec
• Actual ECHONET spec is in Japanese, and top-down review is a lot of work (spec is 100 pages)
• I (McCool) would like to propose that we generate a "proposed ECHONET protocol binding document" (based on the example...) and then ask for feedback from ECHONET members (and others who can review the spec and check it against the protocol binding)
• Protocol binding document can also list and discuss possible solutions to various issues, e.g. HTML bodies, binary payloads, etc. Or we can just use issues against a concrete protocol binding document.
• A proposal is not a commitment... we should treat this as an IG document for now, and not a formal spec

[mlagally]

Comments (some discussed in main call July 14 2021):

• An example is useful but is not a spec
• Actual ECHONET spec is in Japanese, and top-down review is a lot of work (spec is 100 pages)
• I (McCool) would like to propose that we generate a "proposed ECHONET protocol binding document" (based on the example...) and then ask for feedback from ECHONET members (and others who can review the spec and check it against the protocol binding)
• Protocol binding document can also list and discuss possible solutions to various issues, e.g. HTML bodies, binary payloads, etc. Or we can just use issues against a concrete protocol binding document.
• A proposal is not a commitment... we should treat this as an IG document for now, and not a formal spec

@mmccool : This example is used for an analysis of potential gaps and see if we can pragmatically create a binding without hitting any blockers. So far Ege did not hit a problem when he converted the example to a TD.
We will discuss this issue in tomorrow's (15.7.) architecture + profile call.

[benfrancis]

I'm not sure what this example adds to the WoT Profile specification. It doesn't define or use a profile or even use the profile mechanism. Would it make more sense for this example to live in the Thing Description or Protocol Binding Templates repository as an example of a Thing Description which describes an ECHONET device?

[egekorkan]

It was not meant to be in the specification. The reason I had done this PR was a follow-up of a with @mlagally . As spoken in one of the calls by @ashimura , we should not discuss anything relating to Echonet without using the official channels. Thus, I propose closing this PR.

[mlagally]

@matsu200722
can you please review and provide comments?

[matsu200722]

@mlagally

can you please review and provide comments?

I will review the updated JSON. Please give me some time.

[matsu200722]

@mlagally @egekorkan
I am sorry to be very late in replying to your review request.
First of all, I would like to apologize that the example of ECHONET Lite Web API Device Description that @egekorkan referred to (in P18 of our presentation on March 15, 2021) was wrong. A correct example of ECHONET Lite Web API Device Description is in P9-P11 of our presentation on October 15, 2021 (https://github.com/w3c/wot/blob/main/PRESENTATIONS/2021-10-online-f2f/2021-10-14-WoT-OpenDay-ECHONET-Matsuda.pdf)
P9-P11 of our presentation on October 15, 2021 also shows how a Device Description is mapped to a Thing Description in our understanding (except that the binding template does not express JSON format in ECHONET Lite Web API HTTP message body as we suggested in P9 and P13-P16 of our presentation).
That said, I have three comments for your Thing Model.

1. Definitions of properties does not seem to be correct, depending on the behaviour of a WoT consumer.
   For example, property "brightness" is defined as follows in your example.

---

	"brightness": {
		"type": "object",
		"properties": {
			"brightness": {
				"type": "number"
			}
		},
		"epc": "0xB0",
		"descriptions": {
			"ja": "照度レベル設定",
			"en": "Illuminance level"
		},
		"observable": false,
		"forms": [{
			"href": "/elapi/v1/devices/{{deviceId}}/properties/brightness",
			"op": ["readproperty", "writeproperty"],
			"contentType": "application/json"
		}]
	},

---

It seems to me that the following definition is a more desirable one. The type of property "brightness" is "number" , not "object" in ECHONET Lite Web API Device Description.
With your example Thing Model definition, a WoT consumer can access ECHONET Lite Web API thing with an ordinary HTTP binding. However, the WoT consumer needs to be aware that a property name is nested in "object" type definition. I am not sure such handling is generally appropriate.

---

	"brightness": {
		"type": "number",
		"epc": "0xB0",
		"descriptions": {
			"ja": "照度レベル設定",
			"en": "Illuminance level"
		},
		"observable": false,
		"readOnly": false,
		"writeOnly": false
	},

---

2. I think that your example is an example of Thing Model. I am not sure if "forms" can be specified in a Thing Model. When I read the currently published working draft of TD v1.1, I thought that "forms" is not a part of Thing Model.

3. An ECHONET Lite Web API Device Description is a representation of one "thing" and there is no concept corresponding to Thing Model in ECHONET Lite Web API at present.

[mlagally]

@matsu200722
Many thanks for your review and your comments.

I think you are right that the example is a TD for a specific device and contains forms, so it should follow the ".td." pattern.

I also agree that the representation of properties could be simplified to correspond to your example.

@egekorkan , what do you think?

[egekorkan]

Thank you @matsu200722 . I will answer your feedback:

1. From the new slides, I see that the response is an object, thus the schema in the TD has to be an object as well. I totally agree that we are trying to represent the reality without simplifications. There will be some work on this later on but no matter how we decide to that, if one decides to simplify a TD, the Consumer application will become more complex since the Consumer cannot be specific to one API (ECHONET Lite Web API) in this case.
2. TMs can have forms but they do not have to. In your case, I think it is valuable to have forms since the API endpoint can change but the relative hrefs will stay the same and HTTP is always used.
3. I think that is fine. I had changed it to a TM based on feedback of others in the call.

[matsu200722]

@mlagally @egekorkan
Thank you for your answers.
As for @egekorkan 's answer to 1, I assume that it is desirable for the serailization of a propoerty value for read/write request in http message body of ECHONET Lite Web API to be handled by binding template, not by the definition of the property, even though I think that the current binding template notation can not express the serailization of a propoerty value for read/write request in http message body of ECHONET Lite Web API. I acknowlege that your way of defining a property is one choice.

[egekorkan]

@matsu200722 sorry for the late reply. I understand your concerns and sadly do not have a very satisfying (neither for me nor you) answer.

• Ideally, we should avoid putting these information into bindings, which means that TD will contain out of band information even though the Thing is still using HTTP. The danger is that if each standard or platform does that, we will have a new binding for each standard or platform and have reduced interoperability.
• I had heard of the binding template notation not good enough before but now I understand what was implied. This is sadly a feature that is lacking in the TD specification. Ideally, we should not need a new notation for binding a standard/platform.

[matsu200722]

@egekorkan Thank you for your reply.
Reading your reply, I assume you think that it is desirable for an existing device to support WoT standard HTTP protocol binding (or whatever protocol binding defined in WoT) if the device needs to be connected to WoT. (Here, I do not mean binding template by protocol binding.) I am sorry if I misunderstood what you mean.
I have a different view. I expect WoT to connect an existing device to WoT Web API as it is by accommodating the differences in its native protocol and its native data model with the help of binding template. That way,
I expect WoT to play a role, for Web applications, similar to the role played by IP layer in communication protocol stack, which hides the differences in physical and data link layer from the layers above. Just a thought.