Wot-thing-description: writable vs. readOnly

[benfrancis]

We're just about to implement the writable field for properties in Mozilla's gateway and device framework implementations and we're wondering what the rationale is behind the decision of using writable vs. using readOnly as per the JSON Schema Validation specification? (JSON Schema also defines writeOnly).

Is there a particular reason for differing from JSON Schema here? How solid is this decision? Would it make more sense for the Thing Description specification to follow the JSON Schema convention and support readOnly instead?

One benefit of readOnly is that we're finding there are more writable properties than read-only properties. If readOnly defaulted to false then it could be omitted for most property definitions.

We just wanted to make sure how solid this is before going ahead with multiple implementations.

[dhylands]

Personally, I'd prefer to have readOnly be used rather than writable. If I were to look at a description that had nothing, I would naturally assume that its readble and writable. The presence of readOnly behaves much like the const keyword in programming languages.

[zolkis]

Looks like there is enough reasoning for using readOnly (by default false?).
What about observable, should it be true by default? (currently it's false).

[handrews]

@zolkis readOnly and writeOnly default to false in JSON Schema. If you're using the same names as JSON Schema, it's probably a good idea to use the same defaults.

[zolkis]

Yes, that is clear. What about observable, should it be implicitly allowed (default: true), or should it be explicitly declared (default:false)?

[benfrancis]

What about observable, should it be true by default? (currently it's false).

Given that web resources using current web protocols are usually not observable, it might make most sense for the default to be false (as currently defined in the latest Editor's Draft). A developer will have to do something special on the server side (Long poll, SSE, WebSockets or CoAP observe) in order to make a web resource observable.

[handrews]

@zolkis I also think observable should default to false, but couldn't articulate a reason. @benfrancis got it, though- having to do additional work to implement "observable": true means that it should default to false.

[takuki]

In current TD, a form that describes how to update the property needs to be added for the write operation when the value of "writable" is explicitly specified to the value "true". At least this provides some sort of consistency. On the other hand, if we use "readOnly", then a form needs to be reducted when we specify an explicit value of readOnly. This is just my observation of the current TD draft, and is not to express a strong reason for choosing "writable" over "readOnly".

[benfrancis]

Just following up on this because we're about to implement this feature. We'd like to implement readOnly, for which there seems to be some consensus in this issue, but we're not sure how likely this is to get changed?

Is there any chance of this change making it into the next TD release?

[handrews]

@takuki given the discussion around forms in #179 perhaps we can address potential awkwardness there?

[zolkis]

In current TD, a form that describes how to update the property needs to be added for the write operation when the value of "writable" is explicitly specified to the value "true". At least this provides some sort of consistency. On the other hand, if we use "readOnly", then a form needs to be reducted when we specify an explicit value of readOnly.

I don't see this as a problem. When one writes the TD, unless a property is readOnly, it is clear that the write form should be specified as well (or a default form is applied). But yes, someone needs to write it up in the TD spec :).

As soon as the TD spec will be updated, the Scripting spec will be updated as well.

[mkovatsc]

Some time ago, the consensus was that read-only was the default (Properties are mostly sensors, only a few config parameters), resulting in a writable flag that defaults to false. Looking at the PlugFest TDs, I count less than 50% writable Properties.

Overall, I am in favor for aligning with JSON Schema. We should, however, get some consensus on which value the Participants expect as default = false:

• readOnly implies Properties are writable by default
• writable implies Properties are read-only by default

@ToruKawaguchi, @take4sano, @mmccool, @mlagally, @mjkoster, @skdatta, what is your observation and expectation?

[skdatta]

+1 for Matthias' idea.

Research Engineer, EURECOM, France | @skdatta2010 |
http://iot.eurecom.fr

On 03-10-2018 20:16, Matthias Kovatsch wrote:
>

Some time ago, the consensus was that read-only was the default
(Properties are mostly sensors, only a few config parameters),
resulting in a |writable| flag that defaults to false. Looking at the
PlugFest TDs, I count less than 50% writable Properties.

Overall, I am in favor for aligning with JSON Schema. We should,
however, get some consensus on which value the Participants expect as
default = false:

• |readOnly| implies Properties are writable by default
• |writable| implies Properties are read-only by default

@ToruKawaguchi https://github.com/ToruKawaguchi, @take4sano
https://github.com/take4sano, @mmccool https://github.com/mmccool,
@mlagally https://github.com/mlagally, @mjkoster
https://github.com/mjkoster, @skdatta https://github.com/skdatta,
what is your observation and expectation?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/w3c/wot-thing-description/issues/209#issuecomment-426665059,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ALfd1-jVgRNcOKd24gRWXJd6TpfoRlPBks5uhM3fgaJpZM4WTkML.

[draggett]

Yes, I independently came up with the same justification, in addition to a subjective personal dislike for camel casing.

[mkovatsc]

We still have to make a decision if we EITHER include the term readOnly OR the term writable. For this, I need feedback whether or not the majority of your Properties modeled so far is writable.

[skdatta]

For my TD, they are readOnly since I am working mostly on sensors.

Research Engineer, EURECOM, France | @skdatta2010 | http://iot.eurecom.fr/

Quoting Matthias Kovatsch [e-mail]:

We still have to make a decision if we EITHER include the term
readOnly OR the term writable. For this, I need feedback whether
or not the majority of your Properties modeled so far is writable
or not.

--
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/wot-thing-description/issues/209#issuecomment-426919603

---

This message was sent using EURECOM Webmail: http://webmail.eurecom.fr

[ToruKawaguchi]

In smart home area, currently majority is "writable" property, because main connected devices are home appliance products and main use case is its remote control.

But in near future, for smarter application such as home automation, more "readOnly" sensors will be necessary in the home, so choosing "writable" as field name and making "writable=false" as default would make sense to me.

[mkovatsc]

I found an interesting argument concerning robustness: I see several TDs using "writeable", a typo with the silent 'e', which might cause false metadata in handcrafted TDs. Even the last TD Working Draft included the typo in the text.

This risk is mitigated with readOnly.

[draggett]

In regards to defaults, the platform can add readOnly/writable/observable when fulfilling a produce(td) request, so platforms can decide what the default should be when the developer has omitted these from the thing description passed to produce(td) method.

[egekorkan]

But then how does the client know what the platform's default is?

[sebastiankb]

In today's f2f meeting there was a resolution on this issue: "writabe" will be changed to "readOnly".

[sebastiankb]

issue will be closed when resolution is compiled in the TD spec

[sebastiankb]

readOnly is compiled in the TD spec.
@vcharpenay Please review the context and ontology definition. If ok, please close this issue.

[vcharpenay]

See #264

[mlagally]

The current draft now has two mandatory fields: readOnly and writeOnly.
@vcharpenay can you please take another look at the generated section 5?

[sebastiankb]

since there is already a writeOnly and readOnly discussion #266 I would only consider the readOnly term here.
@vcharpenay Please check your PR again there is a conflict.

@all since this was an f2f decision to rename writable to readOnly, and this is now reflected in the TD specification I want to close this issue. The 'review' state has been around for 20 days and there are no complaints yet.

[hspaay]

Looks like this one isn't going anywhere very fast :) I came here because I raised the same concern in this issue

Quote from the thread:

Section 5.2.1 (of the binding template) says that in order to readProperty, writeOnly must be set to false and in order to write a property readOnly must be set false. This is confusing, so in order to write you have to look at readOnly and vice versa? This unnecessarily complicates things. It would be simpler to have 'readProperty' determine if the property is readable without needing to consider writeProperty, and have writeProperty determine if the property is writable without needing to consider readProperty.
The 'readOnly' property name is chosen because of the ownership (or document producer) perspective, not the consumer perspective. Eg "don't touch my stuff" instead of 'here is what you can do'. Looks like an unfortunate mixup in perspective that will live likely live long ever after.

I understand that it is nice to align with JSON-LD schema but what is more important, easy to understand/use or sticking to a schema that used a faulty rational (okay, no offense intended and this is just my personal POV based on the above rational). Also consider the amount of time spent in past and future to clarify this.
As a compromise, can both be supported?