Adding array for common definitions referencing

[egekorkan]

As a result of the discussion at #2154 , we have decided that the new keywords like connection, form, etc. cannot be a string type anymore. The TDs will have either an object for an in-place definition of the definition or will have an array which lists all the possible definitions that are applied. Thus we can have examples like the following:

  {
    "@context": "https://www.w3.org/ns/wot-next/td",
    "connectionDefinitions": {
      "ipv4": {
        "base": "https://192.168.1.10:8080"
      },
      "ipv6": {
        "base": "https://[2001:db8:85a3::8a2e:370:7334]:8080"
      }
    },
    "connection": ["ipv4", "ipv6"],
    "form": {
      "contentType": "application/json"
    },
    "security": {
      "scheme": "nosec"
    },
    "properties": {
      "prop1": {
        "type": "string",
        "forms": [
          {
            "href": "/props/prop1"
          }
        ]
      },
      "prop2": {
        "type": "string",
        "forms": [
          {
            "href": "/props/prop2"
          }
        ]
      }
    }
  }

Internally, that prop1 would expand to something like the following:

      "prop1": {
        "type": "string",
        "forms": [
          {
            "href": "https://192.168.1.10:8080/props/prop1",
            "security": {
              "scheme": "nosec"
            },
            "contentType": "application/json"
          },
          {
            "href": "https://[2001:db8:85a3::8a2e:370:7334]:8080/props/prop1",
            "security": {
              "scheme": "nosec"
            },
            "contentType": "application/json"
          }
        ]
      }

As a result, the proposal and the examples in there should be updated in a PR.

[egekorkan]

In the call yesterday, @relu91 highlighted the potential problem when it comes to forms that already contain an absolute URI or other terms that can be defined in a definition when we use the array type above. We see the issue in the example below. We take the TD above but add a new property called prop3:

"prop3": {
  "type": "string",
  "forms": [
    {
      // I wanted to override and do not want expansion to happen to this form
      "href": "https://example.com/props/prop3"
    }
  ]
}

So when the expansion gets to prop3, it should not expand it. This is for the case where a single property is not following the definitions declared before. This is problematic as it also breaks the index order when the developer does not necessarily look into the forms before expansion (read property using ipv4 connection, i.e. index 0). We have discussed some solutions in the call:

• Say that this is not possible. If you use multiple common definitions (array type), you should not have partially absolute forms. The core problem is that it is not clear which definition should be used to expand. If the TD must have this prop3, the TD producer must provide an expanded TD.
• Add an affordance-level term (like in Affordance-level definition usage #2160) that is empty, i.e., connection:[] to say that none of the definitions can be used here. This still slightly breaks the index ordering.

We have also mentioned that it is not clear if this problem is a real use case. In my opinion, we should not complicate the design to cover edge cases, while making them possible to describe. In this case, they would be possible to describe by providing an expanded TD.