[TF-TD] Actions vs Properties

[domguinard]

I'd like to discuss the value of allowing to write Properties. We had a number of discussions around that when writing the Web Thing Model spec https://www.w3.org/Submission/2015/SUBM-wot-model-20150824/#resources and finally decided to make a clear cut:

• Properties—A property is a variable of a web Thing. Properties represent the internal state of a web Thing. Clients can subscribe to properties to receive a notification message when specific conditions are met; for example, the value of one or more properties changed.
• Actions—An action is a function offered by a web Thing. Clients can invoke a function on a web Thing by sending an action to the web Thing. Examples of actions are “open” or “close” for a garage door, “enable” or “disable” for a smoke alarm, and “scan” or “check in” for a bottle of soda or a place. The direction of an action is from the client to the web Thing. A consequence of many Actions is a modification of properties by the Thing itself.

To draw a parallel: Actions represent the public interface of a Web Thing and Properties are the private parts. This is really important for me as allowing to modify Properties from external clients leads to state inconsistencies according to our experience. It also becomes confusing: when should I use and Action when should I update a Property?

I suggest we try to leverage this: https://www.w3.org/Submission/2015/SUBM-wot-model-20150824/#actions-resource to clarify the model.

[ganesheth]

In my attempt to adopt WoT for automation systems, I found that it is in fact useful and natural to distinguish between Property write and Action invoke. Property write reflects change of some parameter on which a program in the device might depend. For example, the setpoint of a thermostat (which is used by a PID loop). On the other hand Actions reflect some form program execution which has a physical manifestation. For example, an Action invoke to raise the sun blinds: This causes the motor to run for specific duration during which the progress can be monitored, modified, or even cancelled. In your example, enable/disable of a smoke detector would be a Property update whereas open/close of a garage door would be a Action.

[gabert]

Networking devices like routers are configured mainly by changing properties or manipulating internal configuration datastore. Datastore has mostly tree structure. Which is perfectly fine. On the other hand people comming from SOA world (WS-SOAP) to REST, which is more resource oriented, sometimes experience hard times to make a mental switch. So on the SO forums developers can find discussions and advices on how to model services in a resource oriented way. I had this problem as well. Typical scenario is taking camera snapshot with given iso, shutter speed and aperture. SOA developers would naturally call makeSnapshot(iso, speed, aperture) while resource oriented developers, (maybe embedded device developers as well?,) would either create new task resource with three mentioned parameters or lock device in transaction set camera properties as well and set 'ON' button to some state and finally commit transaction. Which results in taking camera snapshot. The more I work with REST and look around IOT/WOT the later approach is more appealing to me as a more generic approach. I would say this is a personal modeling decision based on best practices and maybe some recomendations. In addition if some vendors of network device would like to support WoT on that device they will most likely be very dependent on writable properties. Whats more, on creating new resources (technically list items) in the data tree. Hope makes some sense.

[ganesheth]

@gabert Nice example, I full agree with your observation. I could not understand the statement

Whats more, on creating new resources (technically list items) in the data tree.

Could you please clarify? Thanks.

[draggett]

We need to separate thinking about protocols from the interfaces exposed to applications for the software objects that stand for things. We now have over three decades of experience with object oriented design and event driven behaviours. The enduring practice of having properties, actions (aka methods) and events suggests that we should give designers the freedom to use these as they see fit for their use cases.

From an implementation perspective it is easy to bind properties to setter and getter methods, so there is no technical barrier to how we manage protocol bindings for properties. More importantly, there is the need for designers to understand that the Internet is a distributed system, and as such asynchronous.

Setting a property is an intent to update a thing's state. The same is true for invoking an action. Even when you get the notification that a remote server has updated its state accordingly there is no firm guarantee as to its current state, as some other client of that thing may have updated the thing's state in the meantime, furthermore, the thing's implementation may have caused the state to change.

[Kazuo-Kajimoto]

API_Category(Property vs Action).pdf

At the Libon F2F meeting, I commented that there are some view point on the "property" vs "action".

• No.1 Static vs Dynamic
• No.2 Internal software status vs device hardware status
• No.3 simple low level API vs complex high level API (I've uploaded pdf file.)

According to No.1, "set ledOnOff" is categorized as property, "set fadeIn with duration" is categorized as action. According to No.2, both "set ledOnOff" and "set fade In with duration" are categorized as action.

Even though, above definition still includes ambiguous boundary, but the discussion point is which interpretation is easier to understand for designer.

I think current TD is like to be designed as No.1 concept, but so many SDOs feedback including this thread "#247" is likely to insist No.2.

Is my understanding correct ?

[sebastiankb]

I would like to spend some time about this issue next TD restructuring web meeting on Wednesday. I will try to provide an overview about the different proposals. I hope, all of you can join. @Kazuo-Kajimoto I like the idea. However, what about a resource that is something in between software and hardware status? E.g., 'gps-routing' is a combination of map (software) information and hardware information (gps position).

[draggett]

I don't agree that static vs dynamic is the main basis for choosing between properties and actions, and see that as a false dichotomy. We should consider the extensive experience wth design of object oriented programs. In principle, a property can always be replaced by explicit getter and setter method (aka action), but in practice, many people have found object properties to be very convenient as a design feature. Objects allow one to decouple the interface exposed to applications from the implementation details, and it is common practice for implementations to do so with hidden setter and getter methods.

We need to explain to people that the interface exposed by the objects to applications is decoupled from the underlying protocols and the communication patterns used with those protocols. Just because a property is set, or a method is called, doesn't imply an immediate effect, as we're dealing with a distributed system on a potentially global scale, along with devices that may be sleeping, or where data needs to be buffered before transmission.

Similarly, if a sensor reading changes, it will take some time for this to be visible to applications. The platform the application is running on may need to pull the new reading, or it may be pushed to the platform, but either way, this is hidden from the application. Likewise, the sensor readings may be transmitted individually, or buffered up and sent as a block. In most circumstances, the application doesn't need to know.

In some cases, applications may need to be aware of what is happening at lower layers, e.g. whether the transport is able to fulfil an application's realtime requirements. This however can be dealt with through the communications metadata.

A clean separation between applications and the underlying protocols and communication patterns is vital for the applicability of the web of things across a broad range of application domains as the requirements will vary enormously from one use case to another.

p.s. I can't attend this Wednesday's call as I will be travelling for the Web.BR conference in Sao Paolo, Brazil.

[vcharpenay]

We should consider the extensive experience wth design of object oriented programs. In principle, a property can always be replaced by explicit getter and setter method (aka action), but in practice, many people have found object properties to be very convenient as a design feature. Objects allow one to decouple the interface exposed to applications from the implementation details, and it is common practice for implementations to do so with hidden setter and getter methods.

I'm not sure I follow here. I see your analogy TD property/action and OO attribute/method, it seems clear and makes sense. But are you saying having writable properties is convenient feature of OO programming? Because one of the lessons learned from decades of OO programming is that an attribute should always be replaced by getter/setter methods unless they are constants. C# even features inline getters/setters. The Gang of Four promotes programming against an interface instead of an implementation (as you also said). But interfaces don't have attributes at all.

So, to me, the OO analogy would speak in favor of not having writable properties, as @domguinard suggested initially. At least from a programmatic point of view. These considerations do not help much solving the problem formulated by @Kazuo-Kajimoto though...

[gabert]

In OO state is managed within object boundary. WoT or more generic IoT "global" state consists of set of smaller states represented by Things. Functionality will be often be represented by "Service Thing" which will orchestrate state between sensor thing and actuator thing. So in this case it seems that state boundary represented by interface, encapsulates multiple devices. In case of IoT it's not clear where encapsulation boundary is.

My very personal view is that Things fall into two categories:

1. The ones which represents states with exposed writable properties
2. And the ones with functionalities/logic exposed by interface

On Mon, Oct 10, 2016 at 2:26 PM, Victor Charpenay notifications@github.com wrote:

We should consider the extensive experience wth design of object oriented programs. In principle, a property can always be replaced by explicit getter and setter method (aka action), but in practice, many people have found object properties to be very convenient as a design feature. Objects allow one to decouple the interface exposed to applications from the implementation details, and it is common practice for implementations to do so with hidden setter and getter methods.

I'm not sure I follow here. I see your analogy TD property/action and OO attribute/method, it seems clear and makes sense. But are you saying having writable properties is convenient feature of OO programming? Because one of the lessons learned from decades of OO programming is that an attribute should always be replaced by getter/setter methods unless they are constants. C# even features inline getters/setters. The Gang of Four promotes programming against an interface instead of an implementation (as you also said). But interfaces don't have attributes at all.

So, to me, the OO analogy would speak in favor of not having writable properties, as @domguinard https://github.com/domguinard suggested initially. At least from a programmatic point of view. These considerations do not help much solving the problem formulated by @Kazuo-Kajimoto https://github.com/Kazuo-Kajimoto though...

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

[kej715]

The ThingWorx platform (see http://thingworx.com for details) has been in the IoT market for the past few years and coincidentally appears to implement much of what is being discussed here about the WoT model and semantics. Perhaps it can be treated as a kind of reference implementation to test ideas/arguments being discussed here against what has been experienced with a working implementation.

As in the WoT model, ThingWorx is object oriented (i.e., has concepts analogous to interfaces, classes, inheritance, etc.), and it provides for defining "Things" that have properties, services (aka actions), and events. In practice, properties are often mapped directly to sensor or actuator values, and they are also used in defining traditional OO attributes. They can be defined to be readable, writable, or both. Services are like OO methods, like actions in the WoT model. They can be used to implement accessors, and they can also be used to implement/expose much more complex behavior including interactions with enterprise business systems (for example, to provide access to CRM data about a thing). The event model supports capabilities such as notification when a property value changes, notification when a value exceeds a threshold, etc.

The ThingWorx philosophy is consistent with Dave Raggett's earlier assertion, "we should give designers the freedom to use these [properties, actions, events] as they see fit for their use cases", and the philosophy seems to work well in practice.

[Kazuo-Kajimoto]

@sebastiankb As you mentioned there is ambiguous boundary, but gps routing case can be treated as hardware, so it is categorized as "action".

[Kazuo-Kajimoto]

@draggett

I don't agree that static vs dynamic is the main basis for choosing between properties and actions

I do not agree to adopt static vs dynamic as principle of categorizing property or action, either.

[Kazuo-Kajimoto]

@vcharpenay

So, to me, the OO analogy would speak in favor of not having writable properties, as @domguinard >suggested initially. At least from a programmatic point of view. These considerations do not help much solving the problem formulated by @Kazuo-Kajimoto though..

@gabert

My very personal view is that Things fall into two categories:

1. The ones which represents states with exposed writable properties
2. And the ones with functionalities/logic exposed by interface

As analogy of the boundary between "property" and "action", OO's porperty and intreface is easy for understanding. However, "property"-"action" issue is independent from programming mode. So it might be so rough definition that in IoT/WoT

1. The ones which represents states with exposed writable properties is software oriented, treated as "property"
2. And the ones with functionalities/logic exposed by interface is hardware oriented, treated as "action" OO analogy looks like No.2 of my table.

Then how should we define this in elegant :-) and easy to understand wording....

[zhangyongjing]

Two cents from my experience in oneM2M:

oneM2M adopts HGI SDT (smart device template) as the information model framework, which has the concepts of 'property', 'datapoint', 'action' and 'event'. The sdt:property is different from sdt:datapoint in the way that the sdt:property stands for static, most likely non-functional attributes of devices (like serial-no), while the sdt:datapoint is mostly used for mutable and functional variables (maybe writable or read-only, like the measurement of a temperature sensor).

In the case of actuating a thing (e.g. set the target temperature of a thermostat), the question comes as whether it should be done by directly change a sdt:datapoint which semantically stands for the 'target temperature' (RESTful-style), or by designing a sdt:action which is called 'setTemperature' (RPC-style). Pretty like the debate here. In fact, both approaches are doable. It's more or less the choice of flavor.

So in oneM2M TS-0023, a designing principle is given based on whether the operation is stateful or stateless: "• Rule 2: Rule for description of Action, DataPoint:

• DataPoint shall be used to represent stateless operations. (e.g. powerState of binarySwitch for on/off operations).
• Action shall be used when describing stateful condition, handling unknown internal state conditions (e.g. upVolume/downVolume by increasing/decreasing the audioVolume in steps, handling transactional procedures, or checking integrity using username plus password at the same time). "

And the rule between sdt:property and sdt:datapoint: "• Rule 3: Rule for description of DataPoint and Property:

• Non-functional information shall be described as a Property. Functional information shall be described as a DataPoint. (E.g. non-functional information: version, id; functional information: targetTemperature, targetVolume)."

Hope this information can help with the discussion here.

See more in clause 5.2.2 Description rules for Module Classes and Device models, oneM2M TS-0023: http://www.onem2m.org/images/files/deliverables/Release2/TS-0023-Home_Appliances_Information_Model_and_Mapping-V2_0_0.zip

Note: 'event' is not relevant to the discussion here.

[zhangyongjing]

I think the key think is to ensure TD schema is flexible and powerful enough to be able to describe and interwork with most of the IoT devices/things, no matter how the developers are actually designing them (e.g. oneM2M/SDT or other means). We don't have to fix the rules (like oneM2M did) since W3C WoT won't actually define different device models. But we may recommend similar guidance based on the TD schema.

[mjkoster]

@zhangyongjing Yes, this is my experience also. It is difficult to formulate hard rules for when to use an action pattern and when to use an update pattern, even though it is often apparent.

I prefer to leave it up to the resource designer, and provide a small set of reusable patterns for a range of use cases. This limits the complexity needed in the client to adapt to different patterns.

To accommodate this, we can draw from hypermedia forms, which describe how to accomplish a state change on the server, the nature of which may be indicated through semantic annotation. For example, a lighting design could have "setbrightness" semantic annotation on a form describing an update pattern and "increasebrightness" annotation on a different form that describes an action pattern.

The server indicates what it offers and the client application adapts. It's the standard hypermedia tradeoff, where the client is generalized so the server may specialize. I think this fits nicely with IoT and servers often being constrained devices.

At this point I would like to remind everyone of the RESTful Actuation pattern used in the REST protocol binding proposal. This is an example of how REST clients can use a common pattern for invoking and tracking actions, and which can be easily described by a hypermedia control.

[zolkis]

@gabert

My very personal view is that Things fall into two categories:

1. The ones which represents states with exposed writable properties
2. And the ones with functionalities/logic exposed by interface

What would be arguments for dividing Things in 2 distinct categories, one using purely writable properties, and the other using purely actions. Or what is the process to determine whether a thing should be a property-thing, or an action-thing?

@mjkoster

I prefer to leave it up to the resource designer, and provide a small set of reusable patterns for a range of use cases.

I also thought it was up to the solution designer how to expose a given set of functionality by properties, actions or events. In a general case, it can be a mix, but then we do need some well defined way to document rationale and expected usage patterns.

I would use actions for encapsulating a complexity the app doesn't need to know about. For instance

• well known user actions ("put thing in night mode", "put thing in airplane mode", "open door for invalid person" etc) that need some translation into the solution domain, or
• transactional encapsulation, when multiple properties need to be set in a transaction.

As to the distinction between properties (read-only) and data-points (writable properties): data-points could be represented as an action with a single parameter, or just a writable property, so whatever we choose, things and descriptions should carry the same amount of information either way. Then it's perhaps better to use a wider known paradigm, i.e. writable property.

In the end @domguinard 's proposal seems fine, but from the comments it seems it's more like a recommendation or pattern, rather than a hard rule.

[zhangyongjing]

My previous comment mentioning ‘property’ vs ‘dataPoints’ is not because of the writability, but non-functional/static vs functional/dynamic in the designing principle of oneM2M/SDT. That said, I agree that the choice is more or less up to the developers, especially from W3C WoT point of view (oneM2M developer) - W3C WoT TD should support enough flexibility and descriptivity in the case that the developers choose either way.

BR, Yongjing

From: Zoltan Kis [mailto:notifications@github.com] Sent: Monday, October 17, 2016 1:34 PM To: w3c/wot Cc: Zhangyongjing (Yongjing); Mention Subject: Re: [w3c/wot] [TF-TD] Actions vs Properties (#247)

@gaberthttps://github.com/gabert

My very personal view is that Things fall into two categories:

1. The ones which represents states with exposed writable properties
2. And the ones with functionalities/logic exposed by interface

What would be arguments for dividing Things in 2 distinct categories, one using purely writable properties, and the other using purely actions. Or what is the process to determine whether a thing should be a property-thing, or an action-thing?

@mjkosterhttps://github.com/mjkoster

I prefer to leave it up to the resource designer, and provide a small set of reusable patterns for a range of use cases.

I also thought it was up to the solution designer how to expose a given set of functionality by properties, actions or events. In a general case, it can be a mix, but then we do need some well defined way to document rationale and expected usage patterns.

I would use actions for encapsulating a complexity the app doesn't need to know about. For instance

• well known user actions ("put thing in night mode", "put thing in airplane mode", "open door for invalid person" etc) that need some translation into the solution domain, or
• transactional encapsulation, when multiple properties need to be set in a transaction.

As to the distinction between properties (read-only) and data-points (writable properties): data-points could be represented as an action with a single parameter, or just a writable property, so whatever we choose, things and descriptions should carry the same amount of information either way. Then it's perhaps better to use a wider known paradigm, i.e. writable property.

In the end @domguinardhttps://github.com/domguinard 's proposal seems fine, but from the comments it seems it's more like a recommendation or pattern, rather than a hard rule.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/w3c/wot/issues/247#issuecomment-254183157, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AKyCnMt9KOGrwvV0EDgQ2uAKGWQCTOxPks5q011CgaJpZM4KE2Hb.

[sebastiankb]

Last week in the TD web meeting we discussed the tendency in this thread of having not hard rules regarding properties/actions as well as the TD should be powerful enough to interwork with some existing or upcoming models. There was also this agreement of this in the meeting. However, we need also a clear statement of the soft rules. How do they look like? Here are first ideas:

• An Action may initiate a process.
• An Action has a start and an end.
• A Property may reflect a readable and/or writable value state.
• ..

@zhangyongjing The issue #258 reflects the simplification of the TD structure. Doing this, it would be very simple to reflect oneM2M's dataPoint concept within the TD.

[ganesheth]

The Manufacturing Message Specification (MMS) has a flexible definition of an equivalent of Actions (called Program Executions). Taking inspiration from it, some of the soft rules could be: An Action:

• May intitiate a process
• Has a start, and may have an end
• Can notify about state transitions and progress
• May be aborted, paused, or resumed
• May be result in mutiple and concurrent executions
• ... I look forward to the results of this discussion and testing them out on some use-cases in Automation Systems :)

[benfrancis]

As I think the "WoT Interface" and "Scripting API" should be combined into a single WoT REST API I think about this not in terms of Object Oriented Programming but in terms of RESTful API design.

If we're being dogmatic about REST then there really shouldn't be any "actions" in a RESTful API because all resources should be nouns and the only verbs should be those defined by the HTTP protocol. However, it's a known problem that if followed rigidly this can sometimes result in a very complex API and there are cases where actions resources can actually make sense.

One recommendation is to to treat an /actions collection as a queue of actions to be executed so a new action can be POSTed into the queue. That is to say that you wouldn't call an action by a GET request on a resource with a verb in the name but rather you POST an action resource to add it to a queue of actions to be performed, where it is given a unique ID. You can then GET that resource by its ID (/actions/{id}) to find out its status, PUT a new version of the action to update it in the queue or DELETE it to remove it from the queue.

I wouldn't say that properties should therefore be read-only, but that actions can be used to define more complex behaviour which may modify multiple properties or modify state in different ways which may have different side effects.

In other words, properties should be set directly wherever possible (e.g. using a PUT request), but requesting an action to be added to a queue may be appropriate in certain more complex cases.

[benfrancis]

For example, a property may be set to turn a light on and off but an action might be used to tell it to fade out. The end result is the same (the property ends up in the off state) but the side effect is that the light gradually fades out in transitioning to this state. In this case calling an action would be preferable to setting a brightness property to 256 different brightness values in quick succession to achieve the same effect!

[draggett]

@benfrancis

As I think the "WoT Interface" and "Scripting API" should be combined into a single WoT REST API I think about this not in terms of Object Oriented Programming but in terms of RESTful API design.

I believe that we need to enable the use of RESTful protocols for the platforms that support them, but that we should decouple this from the application scripts. So, a Mozilla platform could indeed expose a RESTful API. A web of things library for the Mozilla platform would map this to the object interaction model for things that is exposed to the applications. The thing descriptions would need to provide the information the library needs to perform this mapping.

a property may be set to turn a light on and off but an action might be used to tell it to fade out

Indeed, as the action allows you to pass parameters that control the duration, trajectory and target for the fade action. Yes, these could alternatively be set via properties, but it would be cumbersome compared to passing the parameters to a method invocation.

[danicic]

This is not the first time that we discuss this topic. So far quite few people were confused while specifying TDs for their Things (e.g., in preparation for the plugfests or otherwise). Typical question was whether something is supposed to be a property or an action. Hence as @sebastiankb mentioned in one of last TD web meetings we tend to agree that some soft rules are needed, or as @mjkoster put it, we need to provide a small set of reusable patterns for a range of use cases. What could be those?

From my point of view in this discussion quite few good and simple rules have already been given. We could go with the following:

Properties shall be used to represent stateless operations (operations whose output are dependent only on its present input). Examples include:

• powerState of binarySwitch for on/off operations
• update of non-functional information: name, serial number, version etc.
• update of functional information but still performed as stateless operations...

Actions shall be used to represent stateful operations (operations whose outputs are a function of both the current inputs and the current state, or the past history of inputs). Examples include operations that:

• intitiate a process
• have a start, and may have an end
• may be aborted, paused, or resumed
• are transactions...

Events shall be used to notify the change of a state, either if the state change happens by a property or action. Examples include:

• notification when binarySwitch goes from on to off
• notification when an action is paused
• notification when a transaction succeeds...

[zhangyongjing]

+1

From: Darko Anicic [mailto:notifications@github.com] Sent: Wednesday, November 02, 2016 2:59 AM To: w3c/wot wot@noreply.github.com Cc: Zhangyongjing (Yongjing) zhangyongjing@huawei.com; Mention mention@noreply.github.com Subject: Re: [w3c/wot] [TF-TD] Actions vs Properties (#247)

This is not the first time that we discuss this topic. So far quite few people were confused while specifying TDs for their Things (e.g., in preparation for the plugfests or otherwise). Typical question was whether something is supposed to be a property or an action. Hence as @sebastiankbhttps://github.com/sebastiankb mentioned in one of last TD web meetings we tend to agree that some soft rules are needed, or as @mjkosterhttps://github.com/mjkoster put it, we need to provide a small set of reusable patterns for a range of use cases. What could be those?

From my point of view in this discussion quite few good and simple rules have already been given. We could go with the following:

Properties shall be used to represent stateless operations (operations whose output are dependent only on its present input). Examples include:

• powerState of binarySwitch for on/off operations
• update of non-functional information: name, serial number, version etc.
• update of functional information but still performed as stateless operations...

Actions shall be used to represent stateful operations (operations whose outputs are a function of both the current inputs and the current state, or the past history of inputs). Examples include operations that:

• intitiate a process
• have a start, and may have an end
• may be aborted, paused, or resumed
• are transactions...

Events shall be used to notify the change of a state, either if the state change happens by a property or action. Examples include:

• notification when binarySwitch goes from on to off
• notification when an action is paused
• notification when a transaction succeeds...

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/w3c/wot/issues/247#issuecomment-257660939, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AKyCnIqMJbueomKTe6hQrlGPclGL8CYtks5q54wIgaJpZM4KE2Hb.

[draggett]

By using "shall" you are transforming suggestions into commands. I think that is too strong, and I would advocate wording that recognises that a broader range of considerations may need to be taken into account.

I think that stateless isn't the best term to use here and will be confusing to many people. Whether a switch is in the on or off position would be interpreted as state by most people, i.e. the switch has a persistent state, and indeed you use "powerState" for your example.

Moreover, you fail to make clear what you mean by operations, and by the functional/non-functional distinction.

I therefore recommend a more informal approach that uses examples to introduce the concepts rather than assuming that readers all have the same mindset and background.

p.s. being married to someone trained as a technical writer makes me sensitive to unstated assumptions in technical prose.

[danicic]

@draggett

By using "shall" you are transforming suggestions into commands. I think that is too strong, and I would advocate wording that recognises that a broader range of considerations may need to be taken into account.

I agree about "shell". I didn't have such intention.

@draggett

I think that stateless isn't the best term to use here and will be confusing to many people. Whether a switch is in the on or off position would be interpreted as state by most people, i.e. the switch has a persistent state, and indeed you use "powerState" for your example.

Well the term stateless does not mean "no state". If we associate stateless interactions with a Property, it means there is no record of previous interactions with the Property, and each interaction request (e.g., to change the Property) has to be handled based entirely on information that comes with it. Contrary to this, interactions with an Action can be seen as stateful since the outcome depends on the input and its internal state.

For example, I would model a state-changing process as an Action because it may be important for a client to be notified about changes of internal states of the process (after invoking the action). On the other hand, I would model a binary switch as a Property because it is important for a client either to be able to set the property with a new value (state) or to read its current value (state). In both cases internal states for a Property do not exist. For both Actions and Properties, events can be used to notify a client about state changes. The only difference is that for actions there may be few events triggered for each internal state, and in case of a Property there is only one event (that denotes the current state change).

@draggett

Moreover, you fail to make clear what you mean by operations, and by the functional/non-functional distinction.

I mean by operations the interactions (as used in the current practice document). An example of a functional information is, for example, DataPoint (see above). Non-functional information is, e.g., name, serial number, version etc.

[sebastiankb]

@draggett

I therefore recommend a more informal approach that uses examples to introduce the concepts rather than assuming that readers all have the same mindset and background.

Examples are always good. Do you have a set of examples in mind? It would good to share and discuss on.

[draggett]

Lights are one example that can help explain the choices. A simple on/off control is fine as a property. A light with a dimmer is also okay as a property whose value is the new light level. If the transition to the new value isn't instantaneous it gets less clear whether to use a property or an action. You could use an annotation on the light level property for the transition time, or you could specify the transition time as a peer property at the same level as the light level. Alternatively, you could use an action and pass the new light level and the transition time as parameters to the action. Generalising yet further, we could specify an animation path for the light level to follow during the transition. If this varies from one transition to the next, then an action is the natural approach to use. A related use case is for disco lights which change direction, intensity and colour. Actions are thus appropriate when you need to pass information specific to the operation you want to invoke.

[AlexOwen]

I think it's very important we leave this much flexibility in the system and don't try to prescribe how people should use it too much. Controlling large systems is as much an artistic endeavour as it is a technical one, and multiple ways of working is essential.

[danicic]

@draggett I agree - it is essentially similar as my example above. A light with a dimmer is okay as a property. For a transition that isn't instantaneous one can use an action if she wants to capture intermediate states (e.g., to be notified when they occur, get their values etc.). Otherwise one can just use properties for non-instantaneous transitions.

[zolkis]

In an approach related to #256, couldn't we model actions as a compound (dictionary) property. Then we could invoke an action with an UPDATE request. The response to an UPDATE request is usually (or may include) the current representation of the Thing.

Obviously, the name of the dictionary is the action name, and its properties are the action arguments, where each argument may be a compound property or a result of another action.

Basically we'd reduce actions to compound properties, i.e. purely a data model issue.

[zolkis]

Similarly, triggering a remote event on an exposed Thing could be an UPDATE request with a semantic annotation corresponding to events, so in fact, an action.

[draggett]

@zolkis, I think this is the wrong issue for your comments which seem to be about binding the interaction model to REST and not about design considerations for properties versus actions. I suggest opening a new issue about thing description metadata for REST bindings.

[zolkis]

Well, the question is whether can we, or do we want to model actions like compound properties. It's secondary whether it matches well with REST.

[draggett]

@zolkis, could you explain what you mean as it isn't obvious to me. I believe that we need the name of the action, the data passed to it (if any), whether it returns zero, one or more responses along with the data returned (if any), and whether it may be canceled. For the data passed or returned, we almost certainly want to support named arguments, along with their data types and annotations (e.g. min and max values). These could involve compound data types.

[zolkis]

Sorry if it was not clear (maybe not a good idea anyway).

In my view, actions should be modeled so that an action would always result in changing the Thing representation, so that observers could be consistently notified.

The name of the action would be the property name. The property value is a dictionary object containing the options/arguments as properties in that dictionary.

We could implement that as

thing.update( { doorclose: { doorlight: "red", lightpattern: "blinking", sound: "warning" } })
.then(function() { 
    console.log("Door status: " + this.doorStatus); 
});

The action results in a new representation of the thing that is sent back in the response. It may send the response when the action completes, or it may send an intermediary state, depending on the thing description/semantics. It is not a problem if update results in an intermediary state, and not the state following the completion of the action. Eventually that state will also be reached, and reacted upon by the listeners of an onupdate event on thing.

Indeed, alternatively we could also say

thing.action("doorclose", { doorlight: "red", lightpattern: "blinking", sound: "warning" } )
.then(...);

I find them rather close syntactically, except that in this case the promise would make sense to be resolved when the action is completed, where completion is defined by the Thing description. But if there are intermediate states, all of them may be tweeted to observers and that would be confusing, or a complexity to handle.

Of course the behavior depends on the Thing design, but in principle I'd be happier with the former option that is easier to map to REST, while still serving the use case.

[draggett]

@zolkis wrote

In my view, actions should be modeled so that an action would always result in changing the Thing representation, so that observers could be consistently notified.

Not all actions update the state of the thing that hosted the action, as for example, for a thing which acts as an agent controlling other things, an action on this thing could result in changes to other things, e.g. one of my early examples was an agent controlling the door and lights for a hotel room.

[zolkis]

In that case actions will then update the state of more than one Thing. I don't see this would change the assumption that the result of an action is the changed state of a Thing, or more Things.

Also, it does not seem to change the assumption that actions can be represented as compound properties, since in order to be able to trigger an action, we need a Thing to host that action, and that Thing must represent the relevant properties of the combined Things participating in the action, so that itself does have a state.

Dave you seem to say that a language abstraction that uses action as a keyword would be more generic way to handle WoT use cases than a REST model. We could carry on with an action construct, but since the need for compound properties was raised elsewhere, I thought it could be applied in this case as well.

I was curious how far could we go with it and whether we miss something by doing that. So far I don't think we'd miss much if used a RESTful approach. Quite a few of us in this thread seem to agree on that - which does not exclude higher level constructs either. It would be nice to have layers defined in WoT for these.

[draggett]

Not all actions result in a change of state. For instance, an action that directs a device to emit a beep sound. Some actions may update the state of one or more things, however, I don't agree that we need to define the responses to actions as mutations on thing properties. Instead, I would expect that web developers to handle the responses as they see fit, just as they are used to doing with the return value from method calls. The only difference is that actions return responses asynchronously.

I also agree with the need to layer constructs, and think that web developers will expect a simple direct way to declare actions as methods with arguments and return values. Lower level constructs will be part of the definition of protocol bindings. This binding needs to consider the communication patterns requested by developers through communications metadata. If a platform cannot comply with the developer's intent, the application needs to be able to adapt its behaviour accordingly. We therefore need to consider how the platform signals the application about how it has handled the developer's intent. Some ideas for this include access to metadata describing what the platform is using or can support, along with some form of notifications (events) that the apps can listen to handle dynamic changes, e.g. loss of connectivity, changes to bandwidth or latency.

[egekorkan]

I think that most of these discussions happened and resulted in a flexible way to look at actions and properties. The discussion here is very nice and could be used in the future as a reference for giving examples on the distinction between the two. I am creating a label called "informative" to track such issues that can almost act like a guide for newcomers. However, any further discussion on this, if needed, should be done in the Architecture task force, thus closing this issue.