Review of Common Definitions Proposal #2165
Description
I finally got to review the common definitions proposal (sorry for being late to the party). I've read through the proposal and all of the examples and I have the following feedback.
Firstly I can see a lot of hard work has gone into this and there are a lot of clever ideas for reducing redundancy in Thing Descriptions. I also love that we would finally have inline security definitions!
If the goal is to remove all redundant/repetitive metadata in a Thing Description and make them more concise, then the proposal is a good one.
However, side effects of the current proposal include:
- There are lots of ways of expressing the same thing, with different types of members that can contain each other or inherit from each other
- There is an increased risk of circular references or conflicting definitions
- It is more difficult to validate whether a TD is valid using JSON Schema alone
- It would require significantly more pre-processing for Consumers to arrive at a usable TD
- I imagine trying to write an algorithm to expand and parse a TD using all of these features (whilst detecting circular references and conflicting terms) would be very challenging
For me this raises the question of what exactly we are optimising for, and what the right trade-offs are between metadata redundancy, human readability and Consumer implementation complexity.
Taking all of those factors into account, I wonder whether the current proposal goes a bit too far and whether there could be a middle ground which optimises out some of the redundancy whilst not creating too many layers of interdependency which complicate Consumer implementation.
Proposal
I've noticed that the existing schemaDefinitions member provides common metadata for data schemas but the proposed securityDefinitions, connectionDefinitions and formDefinitions members are all essentially providing common metadata for Forms. That got me wondering whether a good compromise would be to reduce the proposal down to:
schemaDefinitionsfor data schemasformDefinitionsfor Forms, which would also includebaseandsecuritymembers
This would mean collapsing securityDefinitions and connectionDefinitions into a flatter structure as part of formDefinitions and also collapsing the top level security and connection members into a single formDefaults member (as opposed to form which I think is a confusing name at the top level of the TD alongside forms). I would also seriously consider getting rid of the inherit term which is a potential source of a lot of parsing complexity and circular references, and also reconsider how useful the top level schema member is.
If I've understood all of this correctly then the main cost of this significant simplification would be that you would not be able to share a common base or security definition between multiple formDefinitions which could result in a tiny bit more redundancy in certain scenarios, but in return it would make parsing Thing Descriptions far more straightforward.
I will include some example Thing Descriptions following this proposal in a follow-up comment.
Shared Connections
One other piece of feedback that I have is that the main use case I originally had for this feature was to provide a single WebSocket endpoint which could be connected to once and then shared between all affordances of a Thing. I note that this proposal doesn't actually fully solve that problem since it's still necessary to create a Form for every InteractionAffordance and there are no clear semantics to tell a Consumer to re-use a single connection.
Having spent many months working on a WebSocket sub-protocol for the Web of Things I am no longer sure this is such an important feature of Thing Descriptions, since it can actually be useful to have Forms for each InteractionAffordance to be explicit about which operations are supported. We also got around the connection re-use issue by simply defining the circumstances under which a socket should be re-used in the sub-protocol specification.
However, since it might be relevant to other protocols I thought I would point out that as far as I can tell this original requirement has not actually been met.