# Thing Description pain points --- ## Thing Description pain points I found few areas in which the Thing Description is painful to implement - **Uniformity** - **Relationship between specification** - **Interaction with other subspecification (profiles, protocol bindings)** - **Expectations regarding resource usage** --- ## Thing Description pain points This presentation focuses on few **Uniformity** and cross specification pain points. --- ## Uniformity - Ideally you'd like that each and every part of your specification that is conceptually similar behaves in the same way. --- ## Uniformity - We have few places in which the behavior is different even if the underlying concept is similar. --- ### DataSchema #### Different meaning of one or array - In the Thing Description some fields have the pattern of being `Item` or `Array<Item>` - with the single item and an array of a single item providing the same meaning. - `ArraySchema::items` is the exception and should be clearly marked so. --- ### Affordances We have 3 kind of affordances, but their structure and usage are non-uniform. - They all hold some `DataSchema` in some different way --- ### Affordances We have 3 kind of affordances, but their structure and usage are non-uniform. - They all hold some `DataSchema` in some different way - They all have to relate with their `Form` and `uriVariables` to map the information they would exchange with consumers --- ### Affordances #### Property and Event - **Event** has 3 fields DataSchema fields: - `data`, equivalent to what the Property inherits directly - `dataResponse` that has unclear usage - `cancellation` that is useful to unsubscribe - **Property** inherits a Data Schema and that's all - But you can observe a property... - And we'd need at least a `cancellation` field to make it as usable as `Event`. --- ### Affordances #### Action and Event - **Action** has an `input` and an `output` field, that are a bit more clear compared to `data` and `dataResponse` - **Action** can be asyncronous, but we do not have a `subscribeaction`, while we have `cancelaction` - Polling using the `queryaction` isn't great. --- ### Affordances #### Action and Property - **Property** should expose an internal state of a Thing and let you directly read, observe or manipulate it. Implies that the change is immediate and syncronous, even if it is never the case. - **Action** should let you indirectly manipulate the internal states of the thing and that the change may happen over time. Yet you cannot subscribe to get updates on how your action invocation is going. --- ### Affordances #### Forms and Affordances - The `Form` contains both `response` and `additionalResponse` fields that clash with `dataResponse`/`data` and `output`. - All the `Affordances` have a `uriVariables` that clash/interact badly with `input` and the implicit **Property** `DataSchema` - The `Form` does not have a good way to express which parts of the Affordance `DataSchema`s should map to its protocol if it has ancillary channels (e.g. in HTTP we have Headers vs uri vs actual body) while `uriVariables` seem to be additive over the Affordance `DataSchema`s. --- ## Relationship other specifications We refer to other specification, but sometimes it is not clear what is the expectation in their regard. --- ### Relationship with JSON-LD - The consensus is that you should be able to consume a TD without the requirement of a full JSON-LD processor and we'd like to allow the serialization of a TD in not-json sooner or later (e.g. CBOR) - We should make clear how we can ensure interoperability, e.g. we plan to keep a registry of prefixes for protocol bindings and profiles may/should require that you must use those prefixes. --- ### Relationship with json-schema - The DataSchema is related to the json-schema - It is unclear if it is a subset of it or a superset of it - What to do if what is in the TD and in the jsonschema specification conflict? - The json-schema specification is also evolving - we cannot sensibly just point to it.