# Initial Connection Container Proposals

## Opinions

- Daniel: The simple case with one base and one protocol (and just HTTP), should not require complex forms or uri arithmetics. (+1 from Cris)
- Cris: These proposals are from a time where we wanted to be backwards compatible. Now we do not have the limitations and we should not think in that way.
- Cris: Proposal 4 is not good due to ordering problem.
- Cris: Proposal 5 mixed with 1 seems like a good direction.
- Luca: Security are connections, we can abuse that for TD 1.1
- Luca: Security and Connection can be put together but we should check compositionality
- Luca: Binding the base with connection is good but we can have a base without the connection.

- Daniel Ege: The TD got complex for implementations and humans at the same time.
- Ege: This should be used in complex TDs. A simple TD version should be provided. I will also provide the "expanded" version.
- Luca: The connection is a form in the end. If we keep it that way, the parser should be fine.
- Daniel:

## Past

1. Ege in 878: https://github.com/w3c/wot-thing-description/issues/878#issuecomment-879794045

{
        "@context":"...",
	"bases": {
		"webthing": {
			"href": "wss://mywebthingserver.com/things/lamp",
			"subprotocol": "webthing"
		},
		"base2": {
			"href": "http://localhost:8080"
		},
		"base3": {
			"href": "http://localhost:8081"
		},
		"base4": {
			"href": "coap://localhost:8081"
		},
		"base5": {
			"href": "mqtt://localhost:1883",
			"security": ["basic"]
		},
		"asyncAPIbase": {  //this is how asyncAPI does it
			"url": "development.gigantic-server.com",
			"description": "Development server",
			"protocol": "kafka",
			"protocolVersion": "1.0.0"
		}
	},
	"properties": {  //different properties for the different base values
		"myProperty1": {
			"forms": [{
				"dependsOn": "webthing", //one way using a new keyword dependsOn
				"href": ""
			}]
		},
		"myProperty2": {
			"forms": [{
				"href": "{{base2}}/property2" //using only templating mechanism
			}]
		},
		"myProperty3": {
			"forms": [{
				"href": "{{base3}}/property3"
			}]
		},
		"myProperty4": {
			"forms": [{
				"dependsOn": "base4",
				"href": "property4"
			}]
		},
		"myProperty5": {
			"forms": [{
				"dependsOn": "base5",
				"href": "property5" //for mqtt this becomes the topic name
			}]
		}
	}
}

2. Cris at 1070 https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825

{
"bases": {
    "http": {
      "href": "http://mywebthingserver.com/things/lamp",
      "subprotocol": "webthing"
    },
    "ws": {
      "href": "wss://mywebthingserver.com/things/lamp",
      "subprotocol": "webthing"
    }
  }
}

3. Cris at 1070 https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825

{
  "@context": "http://www.w3.org/ns/td",
  "id": "urn:dev:ops:32473-WoTLamp-1234",
  "title": "MyLampThing",
  "forms": [
    {
      "href": "http://mywebthingserver.com/things/lamp",
      "protocolId": "http"
    },
    {
      "href": "wss://mywebthingserver.com/things/lamp",
      "subprotocol": "webthing",
      "protocolId": "ws"
    }
  ],
  "properties": {
    "status": {
      "type": "string",
      "forms": [
        {
          "href": "/properties/status",
          "baseProtocol": "http"
        },
        {
          "href": "/",
          "baseProtocol": "ws"
        }
      ]
    }
  }
}

4. Cris at 1070 https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825

{
    "forms": [
        {
            "href": "wss://mywebthingserver.com/things/lamp",
           "subprotocol": "webthing",
        }
    ],
    "actions": {},
    "properties": {
        "hello": {
            "forms": [
                {
                    "op": "readproperty",
                    "base": "/forms[0]",
                    "href": ""
                }
            ]
        }
    }
}

5. Cris at 1070 https://github.com/w3c/wot-thing-description/issues/1070#issuecomment-815095825

{
    "connections": {
        "webthing" : {
            "href": "https://www.w3.org/2019/wot/lamp",
            "subprotocol": "webthing",
            "keepalive": true // possibly remove this field, can we infer it from "webthing" protocol?
        },
       "broker" : {
            "href": "mqtt://www.w3.org/2019/wot/broker",  
        }
    },
    "title": "test",
    "securityDefinitions": {
        "no_sec": {
            "scheme": "nosec"
        }
    },
    "security": "no_sec",
    "connection": "webthing",
    "actions": {},
    "properties": {
      "hello_mqtt": {
           
            "forms": [
                {
                   "connection": "broker",
                    "op": "readproperty",
                    "href": "#hello"
                }
            ]
        },
        "hello": {
            "forms": [
                {
                    "href": "", // still this bad boy :(
                }
            ]
        }
    },
    "events": {}
}

## New Proposals

To be filled and moved to issue or markdown documents in the TD repo.

Starting from proposal 5 above. First a complex TD, then a simple TD.

{
    "connections": {
        "basichttp" : { //trying to put EVERYTHING possible
            "href": "https://example.com", // usual base URI
            "contentType": "application/cbor", // This is the default for this Thing's forms
            "security":["basic_sc"], // must be defined in securityDefinitions first
            "htv:methodName":"POST", // This is the default for this Thing. Even a property read would be with POST unless otherwise specified
            "reusable": false, // to be discussed. Can be deduced from binding
                // for how long
        },
       "broker" : {
            "href": "mqtt://www.w3.org/2019/wot/broker",
            "contentType": "text/plain",
            "security":"no_sc",
            "reusable": true,
        }
    },
    "title": "test",
    "securityDefinitions": { // should these be also embedded into connections?
        "no_sec": {
            "scheme": "nosec"
        },
        "basic_sc":{
            "scheme": "basic"
        }
    },
    "security": "no_sec", // it is probably not needed anymore
    "connection": "basichttp", // like security, this is the default connection to be used throughout
    "actions": {},
    "properties": {
      "prop1": {
           "type":"string",
            "forms": [
                {
                   "connection": "broker",
                   "op": "readproperty",
                   "href": "",
                   "base":"application/devices/" // kind of weird, let's discuss :)
                   "mqv:topic": "application/devices/thing1/program/commands/reset""mqv:"
                }
            ]
        },
        "prop2": {
            "type":"string",
            "forms": [
                {
                    "connection": "basichttp",
                    "op":["readproperty"],
                    "href": "myDevice/properties/prop2",
                    "htv:methodName":"GET",
                    "security":"no_sc", //but this is to add. Should not be allowed to mean extending?
                },
                {
                    "connection": "basichttp",
                    "op":"writeproperty",
                    "href": "myDevice/properties/prop2"
                    // default is POST
                }
            ]
        }
    },
    "events": {},
    "links":[
        
    ]
}