diff --git a/index.html b/index.html index 22ebe147..51c992c4 100644 --- a/index.html +++ b/index.html @@ -92,6 +92,65 @@ }, }; + + @@ -369,7 +428,6 @@

The ThingDescription type

-

The WOT namespace

@@ -423,12 +481,20 @@

The WOT namespace

The produce() method

+      typedef object ExposedThingInit;
+
       partial namespace WOT {
-        Promise<ExposedThing> produce(ThingDescription td);
+        Promise<ExposedThing> produce(ExposedThingInit init);
       };
- Belongs to the WoT Producer conformance class. Expects a |td:ThingDescription| argument and returns a {{Promise}} that resolves with an {{ExposedThing}} object that extends {{ConsumedThing}} with a server interface, i.e. the ability to define request handlers. The method MUST run the following steps: + Belongs to the WoT Producer conformance class. Expects a |init:ExposedThingInit| argument and returns a {{Promise}} + that resolves with an {{ExposedThing}} object that extends {{ConsumedThing}} with a server interface, + i.e. the ability to define request handlers. The |init:ExposedThingInit| object is an instance of the ExposedThingInit type. + Specifically, an ExposedThingInit value is a dictionary used for the initialization of an ExposedThing and + it represents a Partial TD as described in the [[!WOT-ARCHITECTURE]]. As such, it has the same + structure of a Thing Description but it may omit some information. + The method MUST run the following steps:
  1. Return a {{Promise}} |promise:Promise| and execute the next steps in parallel. @@ -437,13 +503,97 @@

    The WOT namespace

    If invoking this method is not allowed for the current scripting context for security reasons, reject |promise| with a {{SecurityError}} and abort these steps.
  2. - Let |thing:ExposedThing| be a new {{ExposedThing}} object constructed with |td|. + Let |thing:ExposedThing| be a new {{ExposedThing}} object constructed with |init|.
  3. Resolve |promise| with |thing|.
+
+

Expand an ExposedThingInit

+ To expand an ExposedThingInit given |init:ExposedThingInit| and obtain a valid |td:ThingDescription| as + a result, + run the following steps: +
    +
  1. Run validate an ExposedThingInit on |init|. If that fails, + [= exception/throw =] {{SyntaxError}} and abort these steps.
    2. +
  2. Initialize and empty object called |td|
    3. +
  3. + For each property |key| in |init| copy |key| and value of |key| to |td| recursively. +
    4. +
  4. For each |scheme:SecurityScheme| defined in securityDefinitions check if it is supported by at least one Protocol Binding. + If not remove scheme
    5. +
  5. if the value of security is defined but it is not contained in securityDefinitions remove + security
    6. +
  6. For each |affordance| run the following sub-steps: +
      +
    1. For each |form:Form| defined in |affordance| execute: +
        +
      1. if |form|'s |contentType:string| is not recognized by the runtime as valid remove |contentType:string| from |form| +
        2. +
      2. if |form|'s |href:URL| has an unknown schema remove |href| from |form|.
        3. +
      3. if |form|'s |href:URL| is absolute and its authority it is not recognized by the runtime as a valid + remove |href| from |form|.
        4. +
      4. if |form|'s |href:URL| is already in use by other ExposedThings remove |href| from |form|.
        5. +
      +
      2. +
    +
    7. +
  7. Search for missing required properties in |td| accordingly to + TD JSON + Schema. +

    The editors find this step vague. It will be improved or removed in the next iteration.

    +
    8. +
  8. For each |missing| property run these sub-steps: +
      +
    1. If |missing| is title generate a runtime unique name and assign to title.
      2. +
    2. If |missing| is @context assign the latest supported Thing Description context URI.
      3. +
    3. If |missing| is instance assign the string 1.0.0.
      4. +
    4. If |missing| is forms generate a list of Forms using the available Protocol Bindings and content types + encoders. Then assign the obtained list to forms.
      5. +
    5. If |missing| is security assign the label of the first supported SecurityScheme in securityDefinitions field. + If no SecurityScheme is found generate a NoSecurityScheme called nosec and assing the string nosec + to security. +

      The discussion about how to properly generate a value for security is still open. + See issue #299

      +
      6. +
    6. If |missing| is href define |formStub| as the partial Form that does not have href. Generate a valid |url:URL| using the first Protocol Binding + that satisfy the requirements of |formStub|. Assign |url| to href. If not Protocol Binding can be found remove |formStub| from |td|.
      7. +
    7. Add |missing| to |td| with |value| as value
      8. +
    +
    9. +
  9. Run validate a TD on |td|. If that fails re-[= exception/throw =] the error and abort these steps
    10. +
  10. Return |td|
    11. +
+
+
+

Validating an ExposedThingInit

+ To validate an ExposedThingInit given |init:ExposedThingInit|, run the following steps: +
    +
  1. + Parse TD JSON + Schema + and load it in object called |exposedThingInitSchema:object| +
    2. +
  2. let |optional:Array| be a list containing the following strings: title, @context, + instance, forms, security, and href.
    3. +
  3. + For each property and sub-property |key| in |exposedThingInitSchema| equals to required execute the following steps: +
      +
    1. if |key| |value| is an Array then remove all its elements equal to the elements in |optional|
      2. +
    2. if |key| |value| is a string then if |value| is equal to one of the elements in |optional| remove |key| from |exposedThingInitSchema|
      3. +
    +
    4. +
  4. Return the result of validating an object with JSON Schema given |init| and |exposedThingInitSchema|. +

    Thevalidating an object with JSON Schema steps are still under discussion. + Currently this specification reference to the validation process of JSONSchema. Please + follow this document + when validating |init| with |exposedThingInitSchema|. Notice that the working group is evaluating an alternative formal approach. +

    +
    5. +
+

The discover() method

@@ -2112,12 +2262,13 @@

Constructing {{ExposedThing}}

Before invoking expose(), the {{ExposedThing}} object does not serve any requests. This allows first constructing {{ExposedThing}} and then initialize its Properties and service handlers before starting serving requests.

- To construct an {{ExposedThing}} with the {{ThingDescription}} - |td:ThingDescription|, run the following steps: + To construct an {{ExposedThing}} with the {{ExposedThingInit}} + |init:ExposedThingInit|, run the following steps:
  1. If invoking this method is not allowed for the current scripting context for security reasons, [= exception/throw =] a {{SecurityError}} and abort these steps.
    2. +
  2. Run the expand an ExposedThingInit steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
  3. Run the expand a TD steps on |td|. If that fails, re-[= exception/throw =] the error and abort these steps.
    4. @@ -3266,6 +3417,58 @@

    ExposedThing Examples

    console.log("Error creating ExposedThing: " + err); } +

    + The following will cover a set of examples for the generation of a Thing Description from + an ExposedThingInit using expand an ExposedThingInit steps. As hypothesis the runtime + supports HTTP and COAP protocol bindings and it is hosted at 192.168.0.1. +

    +

    + The next example shows how to exploit a ExposedThingInit to create a simple Thing Description + with one Property with the default values. +

    + +

    + TODO: add more examples where the ExposedThingInit contains suggested values that are replaced by the algorithm. +

@@ -3702,9 +3905,10 @@

Denial Of Service Security Risk

Terminology and conventions

- The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: Thing, Thing Description (in short TD), Web of Things (in short WoT), WoT Interface, Protocol Bindings, WoT Runtime, Consuming a Thing Description, Thing Directory, Property, Action, Event, + The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: Thing, Thing Description (in short TD), Partial TD, Web of Things (in short WoT), WoT Interface, Protocol Bindings, WoT Runtime, Consuming a Thing Description, Thing Directory, Property, Action, Event, - DataSchema, Form etc. + DataSchema, Form, + SecurityScheme, NoSecurityScheme etc.

WoT Interaction is a synonym for Interaction Affordance.