# Initial Connection Proposal

## Initial Examples and Discussion

Initially, Luca's Idea on separating connection and form defaults
https://github.com/w3c/wot-thing-description/pull/2040#discussion_r1822781609

Security is a special connection setup

- conDef + formDef = valid form
- nothing is mandatory in a Def but valid form has mandatory stuff
- invalid form: no href, no contentType, mismatch between uri scheme and vocabulary (`http://` and `cov:method`)

TODO: Find complex examples in current TD
- combo security
- changing contentType
- not using the default contentType
- multi security

conDef: base, security, binding connection defaults
formDef: op, contentType, binding method terms

{
  "securityDefinitions":{
      "sec1":{
          "scheme":"nosec"
      }
  },
  "connectionDefinitions": {
    "no_sec+http3" : {
      "base": "https://example.com",
      "security":"combo",
      "allOf":{
          "1":{
              "scheme":"apikey"
          },
          "2":{
              "scheme":"basic"
          }
      },
      "htv:version": "3",
      "transport": "quick"
    },
    "no_sec+http3" : {
      "base": "https://example.com",
      "security":"nosec",
      "htv:version": "3",
      "transport": "quick"
    },
    "api_sec+http3" : {
      "base": "https://example.com",
      "security":"apikey", 
      "in":"header",
      "name":"hue-api",
      "htv:version": "3",
      "transport": "quick"
    },
    "broker" : {
      "base": "mqtt://www.w3.org/2019/wot/broker",
      "contentType": "text/plain",
      "security":"no_sc"
    }
  },
  "formDefinitions": {
    "read_only_http3_properties": {
      "op": "readproperty",
      "connection": "no_sec+http3", // if this is not present, defaultConnection is picked
      "htv:methodName": "POST",
      "contentType":"application/cbor"
    },
    "writing_http3_properties": {
      "op": "writeproperty",
      "connection": "api_sec+http3",
      "htv:methodName": "PUT",
      "contentType":"application/cbor"
    },
    "observe_mqtt_properties": {
      "op": "observeproperty",
      "connection": "broker",
      "htv:methodName": "POST",
      "contentType":"application/cbor"
    },
    "write-with-embedded-connection-schema":{
      "op": "writeproperty",
      "connection": { // if not a string, it should be the map itself
        "base": "https://example.com",
        "security":"apikey", 
        "in":"header",
        "name":"hue-api",
        "htv:version": "3",
        "transport": "quick"
      },
      "htv:methodName": "PUT",
      "contentType":"application/cbor",
      "additionalResponses":{
         "schema":{"type":"string"}
      }
    }
  },
  "schemaDefinitions": {
    "schema1":{"type":"string"}
  },
  "title": "test",
  "defaultForm": "read_only_http3_properties", // this and below can also be the object from above if there is only one default form
  "defaultForm":{
        "base": "https://example.com",
        "security":"nosec"
  },
  "defaultConnection":"no_sec+http3",
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "defaultForm": "observe_mqtt_properties",
       "mqv:topic": "application/devices/thing1/program/commands/reset",
       "additionalResponses":{ // can be in form definition?
         "schema":"schema1"
       }
     }
   ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
        "defaultForm": "read_only_http3_properties",
        "href": "myDevice/properties/prop2",
      },
      {
        "defaultForm": "writing_http3_properties",
        "href": "myDevice/properties/prop2"
      }
    ]
  }
}
}

## Simple Examples

5. Equivalent Example to above with security objects and inline connections (not equivalent yet)

{
  "title": "test",
  "connectionDefinitions": {
      "base": "https://example.com",
      "security": {
          "scheme":"apikey",
          "in":"header",
          "name":"hue-api"
      }
  },
  "formDefinitions":{
        "contentType":"application/json"
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "defaultConnection":"conn1",
       "defaultForm":"form1",
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "defaultConnection":"conn1",
       "defaultForm":"form1",
       "href": "/props/prop2"
      }
    ]
   }
  }
}

6. Explicit linking keyword (not equivalent yet)

{
  "title": "test",
  "connectionDefinitions": {
    "conn1" : {
      "base": "https://example.com",
      "security": {
          "scheme":"apikey",
          "in":"header",
          "name":"hue-api"
      },
      "security":"mysec1"
    }
  },
  "formDefinitions":{
      "form1": {
        "contentType":"application/json"
      }
  },
  "securityDefinitions":{
      "mysec1":{
          "scheme":"apikey",
          "in":"header",
          "name":"hue-api"
      }
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "defaultConnection":"conn1",
       "defaultForm":"form1",
       "security": {
          "scheme":"apikey",
          "in":"header",
          "name":"hue-api"
      }
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "defaultConnection":"conn1",
       "defaultForm":"form1",
       "href": "/props/prop2"
      }
    ]
   }
  }
}

## Documentation

### Introduction

Motivation

#### Basic mechanism

##### Defaultable elements

An element that is defaultable has a container `{element}Def` at the root of the Thing that is a map of element of that kind.

Every element as a term `inherit` that points to a single element in `{element}Def`, if inherit is populated all the fields in the pointed element are used as default for the current element.

##### Inlineable fields

A field may contain either a string pointing to an element in `{element}Def` or may contain the element of that kind itself.

##### Thing-wide default

Fields that override the starting default for all the elements of that kind.

##### Usage in the TD

`Form`, `Connection`, `DataSchema` and `Security` are **Defaultable Elements**. All the fields that can take one are **Inlineable fields**.

#### Keywords and Types

##### Thing Level

###### Thing-wide defaults

These set a default for the whole Thing

- **connection**:
- *type*: String pointing to the `connectionDefinitions` map or Object with type `Connection`.
- *Mandatory*: Optional.
- *Description*: A reference to or an in-place definition of a connection definition, if missing a protocol binding default is in place.
- *Remarks*: If string, it MUST refer to a first-level key in `connectionDefinitions`.
- **security**:
- *type*: String pointing to the `securityDefinitions` map or Object with type `Security` (currently called SecurityScheme)
- *Mandatory*: Optional
- *Description*:
- *Remarks*: The array of strings of the current spec can be dropped
- **schema**: This will be done later to express default data schemas (e.g. lwm2m object wrapper)
- **form**:
- *type*: String pointing to the `formDefinitions` map or Object with type`Form`.
- *Mandatory*: Optional
- *Description*: A reference to or an in-place definition of a Form, if missing the affordance/operation-specific defaults apply.
- *Remarks*: If string, it MUST refer to a first-level key in `formDefinitions`.

###### Definitions/Defaults container

- **connectionDefinitions**:
- *type*: Map of Object with of type `Connection`.
- *Mandatory*: Optional
- *Description*: A set of connections that can be reused in forms to group common connection information such as a base URI or security
- *Remarks*: The first-level keys are free to choose by the TD producer.
- **formDefinitions**:
- *type*: Map of Object with of type `Form`.
- *Mandatory*: Optional
- *Description*: A set of form information that can be referenced in a forms to group common form information such as `contentType`.
- *Remarks*: The first-level keys are free to choose by the TD producer.
- **schemaDefinitions**:
- *type*: Map of Object with of type `DataSchema`.
- *Mandatory*: Optional
- *Description*:
- *Remarks*: The first-level keys are free to choose by the TD producer. Same as now
- **securityDefinitions**:
- *type*: Map of Object with of type ~~`SecurityScheme`~~ `Security`.
- *Mandatory*: Optional
- *Description*:
- *Remarks*: The first-level keys are free to choose by the TD producer. Same as now

Note: Even if a single form of an affordance is not complete, a defaultable element should exist.

##### Elements

###### Overall Rules

- All of them contain `inherit`, which has type `String`
- Form can refer to a connection via `Form::connection`
- Connection can refer to a security `Connection::security`
- Form can refer to a schema via `Form::additionalResponse` (no change)
- Security can be overridden in a form using an inline definition for connection. No `security` term in the form level.
- Thing can refer to some forms in `Thing::forms`
- Security cannot refer to a connection, form or schema
- Connection cannot refer to a form or schema
- Schema cannot refer to anything beside itself, i.e. inheriting or `oneOf` etc.

###### Connection

- **base**:
- *type*: String of URI
- *Mandatory*: Optional
- *Description*: The base URI that is used for building an absolute URI together with relative URIs in forms
- *Remarks*: None
- **security**:
- *type*: SecurityDefinition (no change)
- *Mandatory*: Mandatory
- *Description*:
- *Remarks*:
Note: When the security definition moves to the bindings, these terms can be moved a layer up to `connection`

###### Form

- **connection**:
- *type*: String or Object with type `Connection`.
- *Mandatory*: Optional.
- *Description*: A reference to or an in-place definition of a connection definition
- *Remarks*: If string, it MUST refer to a first-level key in `connectionDefinitions`.
- **op**:
- *type*: String or Array of String (no change)
- *Mandatory*: with default
- *Description*:
- *Remarks*:
- **contentType**:
- *type*: String (no change)
- *Mandatory*: with default
- *Description*:
- *Remarks*:

###### Schema

Same as now

###### Security

Same as now

#### Guidelines

hints for designing TDs. When to use this or not.

1. If you have one mechanism (security, connection, form, schema), just inline it.

- Security term at the top level is optional
- McCool not mandatory -> Reducing verbosity, make TDs simpler and shorter. People say it is annoying and does not improve security. Defining a "useless" security at the top and always overwriting it is not clear.
- No resolution: Having no security field at all (none in the forms, none in the top level) -> reverting to defaults
- No resolution: Security defaults:
- McCool auto -> Assuming nosec is wrong assumption

TODO: Documenting why we have multi sec for one Thing. Some properties being public, some not. Reading being public, writing not.

##### Validation Rules

- Reference for an object that doesn't exist: What happens in TD 1.1 is same here.

#### Algorithm

TODO: Discuss flattening, normalization and canonicalization algorithm should take the connection

Each TD form MUST be expanded before using its information in a protocol driver. It does repeat until the there is no populated `inherit`. (single inheritance)

To expand the form in an affordance:
- Check if there is a `connection` or a `form` available. If neither is present, check if there is a top-level `connection` or a `form` available. If neither is present, this form is complete and can be used in a binding driver.

#### Examples

##### TD Examples

1. One Connection, one Form, one security no definitions

1.a Defaults separate

{
  "title": "test",
  "connection":{
      "base": "https://example.com"
  },
  "form":{
      "contentType":"application/json"
  },
  "security":{
      "scheme":"nosec"
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "href": "/props/prop2"
      }
    ]
   }
  }
}

1.b Only with form

{
  "title": "test",
  "form":{
      "contentType":"application/json",
      "connection":{
          "base": "https://example.com",
          "security":{
            "scheme":"nosec"
          }
      }
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "href": "/props/prop2"
      }
    ]
   }
  }
}

2. Equivalent Example to above, just more verbose

{
  "title": "test",
  "connectionDefinitions": {
    "conn1" : {
      "base": "https://example.com"
      // "security":"sec1" can be added here instead. We should recommend since there is only one.
    }
  },
  "formDefinitions":{
      "form1": {
        "contentType":"application/json",
        // "connection":"conn1" can be added here instead. We should recommend since there is only one.
      }
  },
  "securityDefinitions":{
      "sec1":{
          "scheme":"nosec"
      }
  },
  "connection": "conn1",
  "form":"form1",
  "security":"sec1", // This applies to all connections
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "href": "/props/prop2"
      }
    ]
   }
  }
}

3. Equivalent Example to above without reuse (same as TD 1.0 but with security in form)

{
  "title": "test",
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "href": "https://example.com/props/prop1",
       "connection":{
           "security":{"scheme":"nosec"}
       }, // this is possible but we want to flatten
       "contentType":"application/json"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "href": "https://example.com/props/prop2",
       // applying flattening, we would get this
       "security":{"scheme":"basic"},
       "contentType":"application/json"
      }
    ]
   }
  }
}

4. Equivalent Example to above without defaults

4.a Completely flat

{
  "title": "test",
  "securityDefinitions":{
    "sec1":{
      "scheme":"nosec"
    }
  },
  "connectionDefinitions": {
    "conn1" : {
      "base": "https://example.com"
    }
  },
  "formDefinitions":{
      "form1": {
        "contentType":"application/json"
      }
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "connection":"conn1",
       "form":"form1",
       "security":"sec1",
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "connection":"conn1",
       "form":"form1",
       "security":"sec1",
       "href": "/props/prop2"
      }
    ]
   }
  }
}

4.b Definition-level reusage

{
  "title": "test",
  "securityDefinitions":{
      "sec1":{
          "scheme":"nosec"
      }
  },
  "connectionDefinitions": {
    "conn1" : {
      "security":"sec1",
      "base": "https://example.com"
    }
  },
  "formDefinitions":{
      "form1": {
        "connection":"conn1",
        "contentType":"application/json"
      }
  },
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "form":"form1",
       "href": "/props/prop1"
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "form":"form1",
       "href": "/props/prop2"
      }
    ]
   }
  }
}

5. Requiring more security for writing

{
  "title": "test",
  "connectionDefinitions": {
    "conn1" : {
      "base": "https://example.com"
    }
  },
  "formDefinitions":{
      "form1": {
        "contentType":"application/json"
      }
  },
  "securityDefinitions":{
      "sec1":{
          "scheme":"nosec"
      },
      "sec2":{
          "scheme":"basic"
      }
  },
  "connection": "conn1",
  "form":"form1",
  "security":"sec1",
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "href": "/props/prop1",
       "op":"readproperty"
      },
      {
       "href": "/props/prop1",
       "op":"writeproperty",
       "connection":{
          "inherit":"conn1",
          "security":"sec2"
       }
      }
     ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
       "href": "/props/prop2"
      }
    ]
   }
  }
}

{
  connection: "something",
  op: "readproperty"
},
{
  connection: "something-strict",
  op: "writeproperty"
}

##### TD Examples with State Machines for MQTT and WS

TODO

#### How to combine with TMs

TODO

## Archive

### Ege last proposal but without the big container

{
  "connectionDefinitions": {
    "basichttp1" : {
      "href": "https://example.com",
      "contentType": "application/cbor", 
      "security":["basic_sc"], 
      "htv:methodName":"POST",
      "op":"writeproperty"
    },
    "basichttp2" : {
      "connection":"basichttp1",
      "htv:methodName":"PUT",
      "op":"readproperty"
    },
    "broker" : {
      "href": "mqtt://www.w3.org/2019/wot/broker",
      "contentType": "text/plain",
      "security":"no_sc"
    }
  },
  "securityDefinitions": {
    "no_sec": {
      "scheme": "nosec"
    },
    "basic_sc":{
      "scheme": "basic"
    }
  },
  "schemaDefinitions": {
    "schema1":{"type":"string"}
  },
  "title": "test",
  "security": "no_sec",
  "connection":"basichttp1",
  "properties": {
    "prop1": {
     "type":"string",
     "forms": [
      {
       "connection": "broker",
       "op": "readproperty",
       "mqv:topic": "application/devices/thing1/program/commands/reset",
       "additionalResponses":{
         "schema":"schema1"
       }
     }
   ]
   },
   "prop2": {
    "type":"string",
    "forms": [
      {
        "connection": "basichttp2",
        "href": "myDevice/properties/prop2",
        "htv:methodName":"GET"
      },
      {
        "connection": "basichttp1",
        "href": "myDevice/properties/prop2"

      }
    ]
  }
}
}