WoT Scripting ideas

wot-scripting-drafts.md

Check the comments below on how we arrived to this variant.

typedef DOMString PropertyFragment;  // serialized TD Property
// includes InteractionPattern and DataSchema
//   InteractionPattern contains: title, titles, description, descriptions, forms, security, uriVariables
//   DataSchema contains: type, unit,  enum, oneOf, const, readOnly, writeOnly
//       repeated (from InteractionPattern): [ title, titles, description, descriptions ]

typedef DOMString ActionFragment;  // serialized TD Action
//  includes InteractionPattern + input, output, safe, idempotent

typedef DOMString EventFragment;  // serialized TD Event
// includes InteractionPattern + data, subscription, cancellation

[Constructor(PropertyFragment init)]
interface ThingProperty: EventTarget {
  Promise<any> read();
  Promise<void> write(any value);
  readonly attribute object metadata;  // get TD members
  attribute EventHandler onchange;  // simple event
};

[Constructor(ActionFragment init)]
interface ThingAction {
  Promise<any> invoke(optional any parameters);
  readonly attribute object metadata;  // get TD members
};

[Constructor(EventFragment init)]
interface ThingEvent: EventTarget {
  readonly attribute object metadata;  // get TD members
  attribute EventHandler onnotification;
};

typedef DOMString ThingFragment;  // serialized Thing Description

[Constructor(optional ThingFragment init)]
interface ConsumedThing: EventTarget {
  Promise<void> updateMetadata(USVString url);  // former fetch()
  readonly attribute object metadata;  // get TD members
  // expose the WoT interactions explicitly
  ThingProperty getProperty(DOMString name);
  ThingAction getAction(DOMString name);
  ThingEvent getEvent(DOMString name);
  attribute EventHandler onchange;  // simple event for TD change
};

typedef (ThingFragment or ConsumedThing) ThingModel;  
typedef (PropertyFragment or ThingProperty) PropertyModel;
typedef (ActionFragment or ThingAction) ActionModel;
typedef (EventFragment or ThingEvent) EventModel;

[Constructor(ThingModel init)]
interface ExposedThing: ConsumedThing {
  ExposedThing addProperty(DOMString name, PropertyModel property, optional any initValue);
  ExposedThing setPropertyReadHandler(DOMString name, PropertyReadHandler readHandler);
  ExposedThing setPropertyWriteHandler(DOMString name, PropertyWriteHandler writeHandler);
  ExposedThing removeProperty(DOMString name);

  ExposedThing addAction(DOMString name, ActionModel init, ActionHandler action);
  ExposedThing removeAction(DOMString name);
  ExposedThing setActionHandler(DOMString name, ActionHandler action);

  ExposedThing addEvent(DOMString name, EventModel event);
  ExposedThing removeEvent(DOMString name);  
  void emitEvent(DOMString name, any data);

  Promise<void> expose();
  Promise<void> destroy();

  Promise<void> register(USVString directory);
  Promise<void> unregister(USVString directory);
};

callback PropertyReadHandler = Promise<any>();
callback PropertyWriteHandler = Promise<void>(any value);
callback ActionHandler = Promise<any>(any parameters);

dictionary ThingFilter {
  (DiscoveryMethod or DOMString) method = "any";
  USVString? url;
  USVString? query;
  ThingFragment? fragment;
};

[Constructor(optional ThingFilter filter)]
interface ThingDiscovery: EventTarget {
  void start();
  void stop();
  attribute EventHandler onfound;
  attribute EventHandler onerror;
  attribute EventHandler oncomplete;
};

interface WOT {
  Promise<void> start(optional WotOptions options);
  void stop();
  Promise<ThingDescription> fetch(USVString url);
};

Updating the gist from the comments above.

This proposals seems to be very close to the version we used to have before this current scripting/TD iteration.

• Explicit calls for properties, actions, etc
• special methods for metadata etc
• ...

e.g., getMetadata() used to be a simple get(), correct?

The nice thing about the current solution is that one can parse a construct (e.g, a Thing TD) and gets also this getters and setters out of the box. The only missing part are handlers that need to get attached...

@zolkis, let's talk about it in the scripting call today.

Model definitions for ExposedThing addXxx() methods.

typedef object InteractionMetadata; // @id, @type, defined in prose

dictionary InteractionPattern {
  DOMString title;
  DOMString description;
  sequence<Form> forms;
  sequence<DataSchema> uriVariables;
};
Interaction includes InteractionMetadata;

dictionary PropertyModel: InteractionPattern {
  boolean observable;
};

dictionary ActionModel: InteractionPattern {
    DataSchema input;
    DataSchema output;
    boolean safe;
    boolean idempotent;
};

dictionary EventModel: InteractionPattern {
    DataSchema data;
    DataSchema subscriptionData;
    DataSchema cancellationData;
};

enum InteractionType { 
    "readproperty", "writeproperty", "observproperty",
    "readallproperties", "writeallproperties",
    "readmultipleproperties", "writemultipleproperties",
    "invokeaction", "subscribeevent", "unsubscribeevent",
};

dictionary Form {
    USVString href;
    DOMString contentType;
    ExpectedResponse response;
    sequence<InteractionType> op;
    DOMString subprotocol;
    sequence<DOMString> security;
    sequence<DOMString> scopes;
};

dictionary ExpectedResponse {
    DOMString contentType;
};

dictionary MultiLanguage {
    // what comes here???
};

dictionary Link {
    USVString href;
    DOMString type;
    DOMString rel;
    USVString anchor;
};

typedef object DataSchemaMetadata; // @context, @type, const, enum described in prose

enum DataSchemaType { "null", "boolean", "number", "integer", "string", "object", "array" };

dictionary DataSchema {
    DOMString title;
    DOMString description;
    DataSchemaType type;
    DOMString unit;
    sequence<DataSchema> oneOf;
    boolean readOnly;
    boolean writeOnly;
};
DataSchema includes DataSchemaMetadata;