From e6bea51ca4f85ce02e26b9d833b9e3c98fff1b85 Mon Sep 17 00:00:00 2001 From: reluc Date: Thu, 21 Jan 2021 11:14:12 +0100 Subject: [PATCH 01/14] add definitions for partialTD --- index.html | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 22ebe147..95d6b70d 100644 --- a/index.html +++ b/index.html @@ -369,7 +369,106 @@

The ThingDescription type

+
+

The PartialTD type

+ 
+          typedef object PartialTD;
+
+ The [[!WOT-ARCHITECTURE]] specification provides a formal definition of a Partial TD object. In this document, a + PartialTD is a dictionary used for the initialization of an ExposedThing. As such, it has the same + structure of a Thing Description but it may omit some information. The example below shows a serialization of a + PartialTD as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, + security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate + the correct Thing Description; see implement a PartialTD algorithm for further details. + 
+      {
+        "properties" : {
+          "temperature":{}
+        }
+      }
+
+
+

Implement a PartialTD

+ To implement a PartialTD given |pTD:PartialTD| and obtain a valid |td:ThingDescription| as a result, + run the following steps: +
    +
  1. Run validate a PartialTD on |pTD|. 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 |pTD| copy |key| and value of |key| to |td| recursively. +
    4. +
  4. Search for missing required properties in |td| accordingly to + TD JSON Schema. + (TODO: possibly expand this step)
    5. +
  5. For each |missing| property run these sub-steps: +
      +
    1. If |missing| is listed in the table below then use the algorithm described there to generate + a |value| for |missing|. +
      2. +
    2. Otherwise [= exception/throw =] {{SyntaxError}} and abort these steps. + (TODO: we could check for this condition in the validation)
      3. +
    3. Add |missing| to |td| with |value| as value
      4. +
    +
    6. +
  6. Return |td|
    7. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PropertyGenerate algorithm
    hrefTODO
    titleTODO
    @contextTODO
    securityTODO
    formsTODO
    instanceTODO
    +
+
+
+

Validating a PartialTD

+ To validate a PartialTD given |pTD:PartialTD|, run the following steps: +
    +
  1. + Parse TD JSON Schema + and load it in object called |schema| +
    2. +
  2. + For each property |key| in |schema|, +
      +
    1. If |key| equals required then remove |key| from |schema|
      2. +
    +
    3. +
  3. Return the result of applying |schema| to |pTD|
    4. +
+ TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security scheme. + See also implement a PartialTD +
+

The WOT namespace

@@ -424,11 +523,11 @@

The WOT namespace

The produce() method

       partial namespace WOT {
-        Promise<ExposedThing> produce(ThingDescription td);
+        Promise<ExposedThing> produce(PartialTD pTD);
       };
- 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 |pTD: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:
  1. Return a {{Promise}} |promise:Promise| and execute the next steps in parallel. @@ -437,7 +536,7 @@

    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 |pTD|.
  3. Resolve |promise| with |thing|. @@ -2112,12 +2211,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 {{PartialTD}} + |pTD:PartialTD|, 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 implement a PartialTD steps on |pTD|. 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. @@ -3702,7 +3802,7 @@

      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.

      From 51bd08d8c7fe50576e71f7f63d673ba7454642bc Mon Sep 17 00:00:00 2001 From: reluc Date: Mon, 1 Feb 2021 12:45:40 +0100 Subject: [PATCH 02/14] rename partilaTD type to ExposedThingInit --- index.html | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/index.html b/index.html index 95d6b70d..40fe6ff8 100644 --- a/index.html +++ b/index.html @@ -370,17 +370,17 @@

      The ThingDescription type

-

The PartialTD type

+

The ExposedThingInit type

-          typedef object PartialTD;
+          typedef object ExposedThingInit;
- The [[!WOT-ARCHITECTURE]] specification provides a formal definition of a Partial TD object. In this document, a - PartialTD is a dictionary used for the initialization of an ExposedThing. As such, it has the same + An ExposedThingInit is a dictionary used for the initialization of an ExposedThing. It represents an instance + of 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 example below shows a serialization of a - PartialTD as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, + ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate - the correct Thing Description; see implement a PartialTD algorithm for further details. - 
+    the correct Thing Description; see implement an ExposedThingInit algorithm for further details.
+    
       {
         "properties" : {
           "temperature":{}
@@ -388,15 +388,15 @@ 
The PartialTD type

       }
     

     

-      
Implement a PartialTD

-      To implement a PartialTD given |pTD:PartialTD| and obtain a valid |td:ThingDescription| as a result,
+      
Implement an ExposedThingInit

+      To implement an ExposedThingInit given |init:ExposedThingInit| and obtain a valid |td:ThingDescription| as a result,
       run the following steps:
       
    
-        
  1. Run validate a PartialTD on |pTD|. If that fails,
+        
  2. Run validate an ExposedThingInit on |init|. If that fails,
         [= exception/throw =] {{SyntaxError}} and abort these steps.
    3. 
         
  3. Initialize and empty object called |td|
    4. 
         
  4. 
-          For each property |key| in |pTD| copy |key| and value of |key| to |td| recursively.
+          For each property |key| in |init| copy |key| and value of |key| to |td| recursively.
         
    5. 
         
  5. Search for missing required properties in |td| accordingly to 
           TD JSON Schema. 
@@ -449,8 +449,8 @@ 
    Implement a PartialTD
    
       

     

     

-      
Validating a PartialTD

-      To validate a PartialTD given |pTD:PartialTD|, run the following steps:
+      
Validating an ExposedThingInit

+      To validate an ExposedThingInit given |init:ExposedThingInit|, run the following steps:
       
    
         
  1. 
           Parse TD JSON Schema
@@ -462,11 +462,11 @@ 
    Validating a PartialTD
    
           
  2. If |key| equals required then remove |key| from |schema|
    3. 
         

         
-        
  • Return the result of applying |schema| to |pTD|
    • 
+        
  • Return the result of applying |schema| to |init|
    • 
       
 
       TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security scheme. 
-      See also implement a PartialTD
+      See also implement an ExposedThingInit
    @@ -523,11 +523,11 @@

    The WOT namespace

    The produce() method

           partial namespace WOT {
-        Promise<ExposedThing> produce(PartialTD pTD);
+        Promise<ExposedThing> produce(ExposedThingInit init);
       };
    - Belongs to the WoT Producer conformance class. Expects a |pTD: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 method MUST run the following steps:
    1. Return a {{Promise}} |promise:Promise| and execute the next steps in parallel. @@ -536,7 +536,7 @@

      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 |pTD|. + Let |thing:ExposedThing| be a new {{ExposedThing}} object constructed with |init|.
    3. Resolve |promise| with |thing|. @@ -2211,13 +2211,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 {{PartialTD}} - |pTD:PartialTD|, 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 implement a PartialTD steps on |pTD|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
        3. +
      3. Run the implement an ExposedThingInit steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
      4. Run the expand a TD steps on |td|. If that fails, re-[= exception/throw =] the error and abort these steps.
        5. From ba1dc2f53081c217e7008347a6557a0e8471feb9 Mon Sep 17 00:00:00 2001 From: reluc Date: Mon, 1 Feb 2021 15:26:30 +0100 Subject: [PATCH 03/14] fix ExposedThingInit definition --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 40fe6ff8..e7af4555 100644 --- a/index.html +++ b/index.html @@ -374,8 +374,8 @@

        The ExposedThingInit type

                   typedef object ExposedThingInit;
        - An ExposedThingInit is a dictionary used for the initialization of an ExposedThing. It represents an instance - of a Partial TD as described in the [[!WOT-ARCHITECTURE]]. As such, it has the same + An ExposedThingInit is a dictionary used for the initialization of an ExposedThing. 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 example below shows a serialization of a ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate From bbd7957f071973f7dfa93d5d19be5c8488fbd17b Mon Sep 17 00:00:00 2001 From: reluc Date: Mon, 1 Feb 2021 15:48:21 +0100 Subject: [PATCH 04/14] move ExposedThingInit def to produce method --- index.html | 210 +++++++++++++++++++++++++++-------------------------- 1 file changed, 108 insertions(+), 102 deletions(-) diff --git a/index.html b/index.html index e7af4555..47f29712 100644 --- a/index.html +++ b/index.html @@ -369,106 +369,6 @@

        The ThingDescription type

    -
    -

    The ExposedThingInit type

    - 
    -          typedef object ExposedThingInit;
-
    - An ExposedThingInit is a dictionary used for the initialization of an ExposedThing. 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 example below shows a serialization of a - ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, - security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate - the correct Thing Description; see implement an ExposedThingInit algorithm for further details. - 
    -      {
-        "properties" : {
-          "temperature":{}
-        }
-      }
-
    -
    -

    Implement an ExposedThingInit

    - To implement 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. Search for missing required properties in |td| accordingly to - TD JSON Schema. - (TODO: possibly expand this step)
      5. -
    5. For each |missing| property run these sub-steps: -
        -
      1. If |missing| is listed in the table below then use the algorithm described there to generate - a |value| for |missing|. -
        2. -
      2. Otherwise [= exception/throw =] {{SyntaxError}} and abort these steps. - (TODO: we could check for this condition in the validation)
        3. -
      3. Add |missing| to |td| with |value| as value
        4. -
      -
      6. -
    6. Return |td|
      7. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      PropertyGenerate algorithm
      hrefTODO
      titleTODO
      @contextTODO
      securityTODO
      formsTODO
      instanceTODO
      -
    -
    -
    -

    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 |schema| -
      2. -
    2. - For each property |key| in |schema|, -
        -
      1. If |key| equals required then remove |key| from |schema|
        2. -
      -
      3. -
    3. Return the result of applying |schema| to |init|
      4. -
    - - TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security scheme. - See also implement an ExposedThingInit -
    -

    The WOT namespace

    @@ -522,12 +422,20 @@

    The WOT namespace

    The produce() method

    +      typedef object ExposedThingInit;
+
       partial namespace WOT {
         Promise<ExposedThing> produce(ExposedThingInit init);
       };
    - 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 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. @@ -543,6 +451,92 @@

      The WOT namespace

    +
    +

    Use an ExposedThingInit

    + To use 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. Search for missing required properties in |td| accordingly to + TD JSON + Schema. + (TODO: possibly expand this step) +
      5. +
    5. For each |missing| property run these sub-steps: +
        +
      1. If |missing| is listed in the table below then use the algorithm described there to generate + a |value| for |missing|. +
        2. +
      2. Otherwise [= exception/throw =] {{SyntaxError}} and abort these steps. + (TODO: we could check for this condition in the validation)
        3. +
      3. Add |missing| to |td| with |value| as value
        4. +
      +
      6. +
    6. Return |td|
      7. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PropertyGenerate algorithm
      hrefTODO
      titleTODO
      @contextTODO
      securityTODO
      formsTODO
      instanceTODO
      +
    +
    +
    +

    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 |schema| +
      2. +
    2. + For each property |key| in |schema|, +
        +
      1. If |key| equals required then remove |key| from |schema|
        2. +
      +
      3. +
    3. Return the result of applying |schema| to |init|
      4. +
    + + TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security + scheme. + See also use an ExposedThingInit +

    The discover() method

    @@ -2217,7 +2211,7 @@

    Constructing {{ExposedThing}}

  • If invoking this method is not allowed for the current scripting context for security reasons, [= exception/throw =] a {{SecurityError}} and abort these steps.
    • -
  • Run the implement an ExposedThingInit steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
    • +
  • Run the use an ExposedThingInit steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
  • Run the expand a TD steps on |td|. If that fails, re-[= exception/throw =] the error and abort these steps.
    • @@ -3366,6 +3360,18 @@

    ExposedThing Examples

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

    The example below shows a serialization of a + ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it + misses the title, @context, + security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate + the correct Thing Description; see use an ExposedThingInit algorithm for further details.

    + 
    +              {
+                "properties" : {
+                  "temperature":{}
+                }
+              }
+
    From 66d5a7512009a0f916260f78f533627f779c3758 Mon Sep 17 00:00:00 2001 From: reluc Date: Fri, 5 Feb 2021 18:38:13 +0100 Subject: [PATCH 05/14] Improve Use ExposedThingInit algorithm --- index.html | 69 ++++++++++++++++++++++++------------------------------ 1 file changed, 31 insertions(+), 38 deletions(-) diff --git a/index.html b/index.html index 47f29712..5b38bdae 100644 --- a/index.html +++ b/index.html @@ -463,6 +463,24 @@

    Use an ExposedThingInit

  • For each property |key| in |init| copy |key| and value of |key| to |td| recursively.
    • +
  • For each |scheme:SecurityScheme| defined in securityDefinitions check if it is supported by the Protocol Bindings. + if not remove scheme
    • +
  • if the value of security is defined but it is not contained in securityDefinitions remove + security
    • +
  • 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. +
    +
  • Search for missing required properties in |td| accordingly to TD JSON Schema. @@ -470,49 +488,23 @@

    Use an ExposedThingInit

  • For each |missing| property run these sub-steps:
      -
    1. If |missing| is listed in the table below then use the algorithm described there to generate - a |value| for |missing|. -
      2. +
    2. If |missing| is title generate a runtime unique name and assign to title.
      3. +
    3. If |missing| is @context assign the latest supported Thing Description context URI.
      4. +
    4. If |missing| is instance assign the string 1.0.0.
      5. +
    5. 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. (TODO: expand?)
      6. +
    6. 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. (TODO: ask for guidance to Security task force)
      7. +
    7. 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|.
    8. Otherwise [= exception/throw =] {{SyntaxError}} and abort these steps. (TODO: we could check for this condition in the validation)
    9. Add |missing| to |td| with |value| as value
    • +
  • Run validate a TD on |td|. If that fails re-[= exception/throw =] the error and abort these steps
  • Return |td|
    • - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    PropertyGenerate algorithm
    hrefTODO
    titleTODO
    @contextTODO
    securityTODO
    formsTODO
    instanceTODO
    @@ -3810,7 +3802,8 @@

    Denial Of Service Security Risk

    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. From 2eea3f40f1e13f59729333180cf8c30540b36db1 Mon Sep 17 00:00:00 2001 From: reluc Date: Fri, 12 Feb 2021 14:29:42 +0100 Subject: [PATCH 06/14] rename use an ExposedThingInit to expose an ExposedThingInit --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 5b38bdae..534b79ce 100644 --- a/index.html +++ b/index.html @@ -452,8 +452,8 @@

    The WOT namespace

    -

    Use an ExposedThingInit

    - To use an ExposedThingInit given |init:ExposedThingInit| and obtain a valid |td:ThingDescription| as +

    Expand an ExposedThingInit

    + To expand an ExposedThingInit given |init:ExposedThingInit| and obtain a valid |td:ThingDescription| as a result, run the following steps:
      @@ -527,7 +527,7 @@

      Validating an ExposedThingInit

      TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security scheme. - See also use an ExposedThingInit + See also expand an ExposedThingInit
    @@ -2203,7 +2203,7 @@

    Constructing {{ExposedThing}}

  • If invoking this method is not allowed for the current scripting context for security reasons, [= exception/throw =] a {{SecurityError}} and abort these steps.
    • -
  • Run the use an ExposedThingInit steps on |init|. if that fails re-[= exception/throw =] the error and abort these steps. Otherwise store the obtained |td:ThingDescription|
    • +
  • 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|
  • Run the expand a TD steps on |td|. If that fails, re-[= exception/throw =] the error and abort these steps.
    • @@ -3356,7 +3356,7 @@

    ExposedThing Examples

    ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it misses the title, @context, security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate - the correct Thing Description; see use an ExposedThingInit algorithm for further details.

    + the correct Thing Description; see expand an ExposedThingInit algorithm for further details.

                   {
                 "properties" : {

From 86b9779fbbae0815566fee68d57a23b84f894bae Mon Sep 17 00:00:00 2001
From: reluc 
Date: Fri, 12 Feb 2021 14:32:49 +0100
Subject: [PATCH 07/14] fix securityDefinitions check in Expand
 ExposedThingInit

---
 index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 534b79ce..8ac8c8ec 100644
--- a/index.html
+++ b/index.html
@@ -463,8 +463,8 @@ 
    Expand an ExposedThingInit
    
         
  • 
           For each property |key| in |init| copy |key| and value of |key| to |td| recursively.
         
    • 
-        
  • For each |scheme:SecurityScheme| defined in securityDefinitions check if it is supported by the Protocol Bindings. 
-        if not remove scheme 
    • 
+        
  • For each |scheme:SecurityScheme| defined in securityDefinitions check if it is supported by at least one Protocol Binding. 
+        If not remove scheme 
    • 
         
  • if the value of security is defined but it is not contained in securityDefinitions remove 
         security
    • 
         
  • For each |affordance| run the following sub-steps:

From 5fbec2d521c0f04728d53936565b4eceafa4915d Mon Sep 17 00:00:00 2001
From: reluc 
Date: Fri, 12 Feb 2021 15:01:31 +0100
Subject: [PATCH 08/14] improve validation algorithm for ExposedThingInit

---
 index.html | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/index.html b/index.html
index 8ac8c8ec..ebc26bfa 100644
--- a/index.html
+++ b/index.html
@@ -498,8 +498,6 @@ 
    Expand an ExposedThingInit
    
           to security. (TODO: ask for guidance to Security task force)  
    • 
             
  • 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|. 
    • 
-            
  • Otherwise [= exception/throw =] {{SyntaxError}} and abort these steps.
-              (TODO: we could check for this condition in the validation)
    • 
             
  • Add |missing| to |td| with |value| as value
    • 
           
         
@@ -516,18 +514,17 @@ 
    Validating an ExposedThingInit
    
             Schema
           and load it in object called |schema|
         
+        
  • let |optional:Array| be a list containing the following strings: title, @context, 
+        instance, forms, security, and href. 
    • 
         
  • 
-          For each property |key| in |schema|,
+          For each property and sub-property |key| in |schema| equals to required execute the following steps:
           
      
-            
    1. If |key| equals required then remove |key| from |schema|
      2. 
+            
    2. if |key| |value| is an Array then remove all its elements equal to the elements in |optional|
      3. 
+            
    3. if |key| |value| is a string then if |value| is equal to one of the elements in |optional| remove |key| from |schema|
      4. 
           
    
         
    • 
         
  • Return the result of applying |schema| to |init|
    • 
       
-    
-      TODO: is there any property that we should still require? for example flow property is mandatory for oAuth Security
-      scheme.
-      See also expand an ExposedThingInit
     
   
 

From 8d7c41d4120f11dcc09da0a5218209ad40f64ded Mon Sep 17 00:00:00 2001
From: reluc 
Date: Fri, 12 Feb 2021 15:11:01 +0100
Subject: [PATCH 09/14] Resolve todos in ExposedThingInit algorithm

---
 index.html | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index ebc26bfa..1c54b6d1 100644
--- a/index.html
+++ b/index.html
@@ -484,7 +484,7 @@ 
    Expand an ExposedThingInit
    
         
  • Search for missing required properties in |td| accordingly to
           TD JSON
             Schema.
-          (TODO: possibly expand this step)
+          
    The editors find this step vague. It will be improved or removed in the next iteration. 
    
         
    • 
         
  • For each |missing| property run these sub-steps:
           
      
@@ -492,10 +492,13 @@ 
      Expand an ExposedThingInit
      
             
    1. If |missing| is @context assign the latest supported Thing Description context URI.
      2. 
             
    2. If |missing| is instance assign the string 1.0.0.
      3. 
             
    3. 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. (TODO: expand?)
      4. 
+              encoders. Then assign the obtained list to forms.
             
    4. 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. (TODO: ask for guidance to Security task force)  
      5. 
+          to security. 
+          
      The discussion about how to properly generate a value for security is still open. 
+            See issue #299 
      
+          
             
    5. 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|. 
      6. 
             
    6. Add |missing| to |td| with |value| as value
      7. 

From f253670b2504753620d0818a321bbfe3137434ce Mon Sep 17 00:00:00 2001
From: reluc 
Date: Mon, 15 Feb 2021 12:57:29 +0100
Subject: [PATCH 10/14] add example draft

---
 index.html | 101 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 95 insertions(+), 6 deletions(-)

diff --git a/index.html b/index.html
index 1c54b6d1..33d4a4c7 100644
--- a/index.html
+++ b/index.html
@@ -92,6 +92,65 @@
         },
       };
     
+    
+    
   
   
 
@@ -3357,13 +3416,43 @@ 
      ExposedThing Examples
      
       misses the title, @context,
       security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate
       the correct Thing Description; see expand an ExposedThingInit algorithm for further details.
      
-      
      -              {
-                "properties" : {
-                  "temperature":{}
-                }
+      
      
+      
+     
      
    
 

From 45347715084d1c68466a98dc436dddb4f07890db Mon Sep 17 00:00:00 2001
From: reluc 
Date: Tue, 16 Feb 2021 11:05:42 +0100
Subject: [PATCH 11/14] Add editor note for step 4 in ExposedThingInit
 validation

---
 index.html | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 33d4a4c7..99b73423 100644
--- a/index.html
+++ b/index.html
@@ -585,7 +585,13 @@ 
      Validating an ExposedThingInit
      
             
    7. if |key| |value| is a string then if |value| is equal to one of the elements in |optional| remove |key| from |schema|
      8. 
           
    
         
    • 
-        
  • Return the result of applying |schema| to |init|
    • 
+        
  • Return the result of validating |init| with |schema|
+          
    Validating steps are still under discussion.
+            Currently this specification reference to the validation process of JSONSchema. Please
+            follow this document 
+            when validating |init| with |schema|. Notice that the working group is evaluating an alternative formal approach.
+          
    
+        
    • 
       
     
   

From 3e909c9a5c338f4f66b41bd52f65c4286a735109 Mon Sep 17 00:00:00 2001
From: reluc 
Date: Tue, 16 Feb 2021 11:08:29 +0100
Subject: [PATCH 12/14] rename schema to exposedThingInitSchema

---
 index.html | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/index.html b/index.html
index 99b73423..fc3559e5 100644
--- a/index.html
+++ b/index.html
@@ -574,22 +574,22 @@ 
    Validating an ExposedThingInit
    
         
  • 
           Parse TD JSON
             Schema
-          and load it in object called |schema|
+          and load it in object called |exposedThingInitSchema:object|
         
    • 
         
  • let |optional:Array| be a list containing the following strings: title, @context, 
         instance, forms, security, and href. 
    • 
         
  • 
-          For each property and sub-property |key| in |schema| equals to required execute the following steps:
+          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 |schema|
      3. 
+            
    3. if |key| |value| is a string then if |value| is equal to one of the elements in |optional| remove |key| from |exposedThingInitSchema|
      4. 
           
    
         
    • 
-        
  • Return the result of validating |init| with |schema|
+        
  • Return the result of validating |init| with |exposedThingInitSchema|
           
    Validating steps are still under discussion.
             Currently this specification reference to the validation process of JSONSchema. Please
             follow this document 
-            when validating |init| with |schema|. Notice that the working group is evaluating an alternative formal approach.
+            when validating |init| with |exposedThingInitSchema|. Notice that the working group is evaluating an alternative formal approach.
           
    
         
    • 
       

From a3147c15e97ca85adf1d0b416a5ea8fe1fae1109 Mon Sep 17 00:00:00 2001
From: reluc 
Date: Wed, 17 Feb 2021 15:41:54 +0100
Subject: [PATCH 13/14] polishing ExposedThingInit example

---
 index.html | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/index.html b/index.html
index fc3559e5..3353e8f4 100644
--- a/index.html
+++ b/index.html
@@ -3417,12 +3417,16 @@ 
    ExposedThing Examples
    
            console.log("Error creating ExposedThing: " + err);
         }
    -

    The example below shows a serialization of a - ExposedThingInit as a JSON object. It can be noticed that it is not a valid Thing Description because it - misses the title, @context, - security information, and forms fields. Nevertheless, it could be used by a runtime as an hint to instantiate - the correct Thing Description; see expand an ExposedThingInit algorithm for further details.

    -