Comments on Simplified WoT Thing Description

[benfrancis]

Thank you to Siemens for presenting their Simplified WoT Thing Description proposal to us today in the TD Serialization call.

I'm going to discuss this proposal further with the Web of Things team at Mozilla this week, but I have some initial feedback to share.

Firstly, whilst this proposal is still more complex than the JSON-TD proposal from Mozilla, EVRYTHNG and Ambrosus Technologies, it is in my view a significant step forward over the current JSON-LD serialisation so thanks for going to the effort of working on this.

@context

• I agree on using this for optional semantic annotations
• Could we have the option for a context to be a single string (URI) rather than an array? You could still use an array if multiple contexts are needed.

{
  "@context": "https://iot.schema.org"
  ...
}

@type

• I agree on using this for optional semantic type annotations
• Does it need to be an array? What if a thing has a single @type and a capability (property, action and event) has a single @type?
• Could the three levels of @type (thing type, capability type and data type) be reduced down to two? (thing type and capability type). E.g. Do we really need SwitchStatus and SwitchData or could we just have an OnOffProperty capability type whose data type is defined to be boolean in the capability's JSON-LD schema?

  "@context": "https://iot.schema.org",
  "@type": "DimmableLight",
  ...
  "properties": {
    "on": {
      "name": "On/Off",
      "description": "Whether the lamp is turned on",
      "@type": "OnOffProperty",
      "schema": {
        "type": "boolean",
      } 
    }
  }

@id/id

• Why is this necessary? Why is the URL of the Thing Description not a suitable URI to identify a Thing? Why is an additional urn needed?

base

• Similarly, why is a base URL needed? Can the Thing Description's URL be used as the base URL?
• Note: I strongly recommend against automatically generating URL structures based on property/action/event names. Links to property/action/event resources should be explicit with the use of a URL.

schema

• I'm interested in the idea of directly using JSON Schema syntax like this to consistently define data schemas for properties, actions and events. It seems like it could be a good idea, as long as it doesn't add too much complexity for clients to parse Thing Descriptions. JSON Schema is a quite a big spec if clients need to implement all of it (similar to the issue with JSON-LD). How much of JSON Schema is being referenced/re-used?
• Can schemas describe units for things? How can we add SI units?
• Note that JSON Schema already has mechanisms for defining whether a property is readOnly or writeOnly, and has a mechanism for defining links (HyperSchema) although I'm not sure these are intended for our kinds of use cases. Is it intentional not to use those?
• The schema examples for actions and events in EXAMPLE 1 are using arrays and sub-schemas. JSON Schema is actually simpler than this (see here). Was this syntax intended for Example 3 (Moderate Simplified TD Example) instead? I think EXAMPLE 1 should read:

 "fade": {
    "inputSchema": {
      "type": "object",
      "fields": {
        "from": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "to": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "duration": {
          "type": "number"
        }
      }
    }
  }

• I'm interested to see use cases of outputSchema in addition to inputSchema for actions, I haven't come across that need yet

forms

• "rel": ["get", "set"] does not match my understanding of how link relations are intended to be used. They are supposed to "describe how the current context is related to another resource", not what protocol methods can be used with that resource.
• http:SubProtocol also feels like a bit of a hack
• As discussed in the meeting, I'm still not convinced by this use of "forms" as a generic mechanism for declaratively defining protocol bindings to any protocol inside a Thing Description. I think we should continue to incubate an alternative approach (inside the Interest Group) of using concrete protocol binding specifications for a small number of web protocols.
• If multiple links are needed for the same capability, an array of link relations could be used ("rel":"self" could be omitted and assumed as a default, but is included here to show a more common use of a link relation):

    "level" : {
      "name": "Level",
      "@type": "LevelProperty",
      "schema": {
        "type": "number",
        "minimum": 0,
        "maximum": 100
      }      
      "links" : [
          {
            "rel": "self",
            "href": "/things/lamp/properties/level",
            "mediaType": "application/json"
          },
          {
            "rel": "self",
            "href": "coap://things.com/things/lamp/properties/level",
            "mediaType": "application/cbor"
          }
        ]
      }

links

• I think we could probably live with this. It's a bit different to the syntax proposed in JSON-TD in that it doesn't have keys which indicate the type of link, but maybe this is a more conventional way of describing links. We could explore using rel instead of an object key to indicate the type of link, e.g. "rel":"alternate" to point to a WebSocket endpoint for a Thing. It could potentially also be used to provide a link to a custom web-based user interface for a Thing.

"links": [
  {
    "rel": "alternate",
    "wss://things.com/things/lamp"
  },
  {
    "rel": "alternate",
    "mediaType": "text/html",
    "href": "https://things.com/things/lamp/index.html"
  }
]

Media Type

I'd suggest application/td+json as that is the format used by most registered MIME types for JSON-based formats.

Objects vs. Arrays

As I've mentioned before, we'd prefer the object representation. You can easily iterate through keys of an object in JavaScript. Having an ID in an array element is doable, but thing.properties[0] is a lot more clunky than thing.properties.on.

[handrews]

@benfrancis a few responses on JSON [Hyper-]Schema:

JSON Schema is a quite a big spec if clients need to implement all of it (similar to the issue with JSON-LD). How much of JSON Schema is being referenced/re-used?

A big focus for the current draft-08 work is to make JSON Schema more modular, so that projects can both more easily extend JSON Schema with new vocabularies, and restrict or embed JSON Schema.

If there is a readily identifiable JSON Schema subset that is of interest that would be useful input to the draft-08 work.

already has mechanisms for defining whether a property is readOnly or writeOnly

Yes, these were moved from hyper-schema into validation in draft-07 because many uses of JSON Schema validation use them without using hyper-schema. Draft-07 was published in November, so this probably wasn't the case when decisions about readOnly in the TD were first being considered.

and has a mechanism for defining links (HyperSchema) although I'm not sure these are intended for our kinds of use cases. Is it intentional not to use those?

I've been trying to figure out how Hyper-Schema might fit in, and there have been some discussions in w3c/wot-thing-description#94 and w3c/wot-binding-templates#13. When TD links/forms were first being designed, Hyper-Schema was on draft-04 which had a number of problems and was not a complete system. We removed most of the problems in draft-06 in April 2017, but only really produced a complete system in draft-07 in November 2017. I think it is worth another look now, but I'm obviously biased.

"rel": ["get", "set"] does not match my understanding of how link relations are intended to be used. They are supposed to "describe how the current context is related to another resource", not what protocol methods can be used with that resource.

I'm with you on that. One of the big problems in JSON Hyper-Schema draft-04 was over-emphasis on individually specifying protocol methods. Which also led to people getting confused about rel and using it for actions instead of relations. So we removed the method field to focus the primary Link Description Object fields on the relationship, and what kind of representation and/or non-representation data is used with the link.

Indicating what protocol operations are available can be done through targetHints (which defers its specific structure to the protocol as indicated by the URI scheme, so for HTTP or CoAP, allow would be the field to use), or can be discovered at runtime in the normal way (try it and see if you get a 405, or do a HEAD or OPTIONS and look at the Allow header).

It's a bit different to the syntax proposed in JSON-TD in that it doesn't have keys which indicate the type of link

Hyper-Schema also uses an array of links, as it turns out to be fairly easy to have different links with the same rel. They are usually disambiguated by the context (e.g. every entry in a list of books has an author link, and you tell the difference by looking at the list position that is the context of the link- in JSON Hyper-Schema the context is adjusted by anchor and/or anchorPointer).

We feel that the array approach is more flexible and encourages a more general link design mentality. Applications are, of course, free to parse the list into an object indexed by whatever key works for their application. For some applications, rel may be sufficient. For others it may be a combination of rel and anchor, etc.

The alternative was to make an object of lists, since either way you organize it you have to deal with multiple links of the same relation type. There's still some discussion on allowing this, although it doesn't seem to have a strong advocate at this point.

The links example you give above is very similar to Hyper-Schema, with some naming exceptions. For instance, we all mediaType targetMediaType because there are at least two other media types in the spec: submissionMediaType in Hyper-Schema (for non-representation data, e.g. POST requests) and contentMediaType in Validation (for data encoded in a JSON string). We opted for clarity of purpose rather than following the traditional mediaType name (there are other target*, submission* and content* keywords that match these).

[mjkoster]

Use of link inside interaction with only generic mediaType does not convey enough information.

JSON is not self-describing to any WoT application like HTML is to a browser DOM.

We need to understand how to best bridge this gap, and for now we are experimenting with explicit controls, in a well-defined module within the TD mediatype, using some external vocabularies to configure a small set of transfer options.

We decided to call this an extension to the concept of "Form" because it is a control that tells the client how to submit state changes to the server.

Let's split the discussion of "Form" into two parts;

Maybe it is a small extension but I think we are creating a new extension to REST where state changes on the server are orchestrated by the client; the so-called "Action" pattern. We mostly seem to agree that it is more than simply setting resource state.

Second, how does the mediatype implement the concept of the client sending state updates to the server. Is it simply a description of the payload and a convention as to the method and options? Or do we decide to accommodate regional variations in use with different SDOs, vendors, and integrators?

We are also creating an extension for Events and property notifications, which can have a few common transfer layer mappings (subProtocols). There are complaints about this also. But they exist and it may not be in the WoT charter to pick one and only one.

There is also a hybrid approach where TD can simply link to a more descriptive external mediatype for interactions, which implements a well-known transfer-interaction model, e.g. mapping for PUT/POST, etc. and pre-selected subProtocols. For example there could be

"link": {
"href":c"http://example.com/wot-gatewayAPI.v1/uuid/my_light/actions/setBrightness",
"mediaType": "application/wot+json"
}

Where wot+json tells the client to use a particular pre-defined protocol binding for the http scheme.

[benfrancis]

@handrews: Thank you, that's useful information.

@mjkoster wrote:

Use of link inside interaction with only generic mediaType does not convey enough information.

JSON is not self-describing to any WoT application like HTML is to a browser DOM.

We need to understand how to best bridge this gap, and for now we are experimenting with explicit controls, in a well-defined module within the TD mediatype, using some external vocabularies to configure a small set of transfer options.

I recognise that an application/json mediaType is not enough to tell a client how to interact with a Web Thing over HTTP or CoAP. When I talk about a concrete protocol binding for a REST API, that includes both which methods to use and the format of the data payloads. Mozilla's current definition could certainly be improved, but I think it is worth further incubating this concrete approach as an alternative to the current abstract approach which I'm not convinced is going to work.

Maybe it is a small extension but I think we are creating a new extension to REST where state changes on the server are orchestrated by the client; the so-called "Action" pattern. We mostly seem to agree that it is more than simply setting resource state.

I don't think we're inventing anything new here, there is an established pattern for representing actions in REST APIs by POSTing to an action queue. It's not a standard, but it is a widely used design pattern which could be used by one.

Second, how does the mediatype implement the concept of the client sending state updates to the server. Is it simply a description of the payload and a convention as to the method and options? Or do we decide to accommodate regional variations in use with different SDOs, vendors, and integrators?

As described above, a concrete REST binding could specify both the methods and payloads used.

I understand the motivation for designing an abstract mechanism which can encompass a range of existing IoT protocols as it feels like we're creating interoperability by gluing existing standards together. Whilst that approach possibly creates business opportunities to provide gateways and cloud adapters to convert between all of those different protocols, it doesn't allow for true ad-hoc interoperability. It's likely to require a client to download additional software for each new protocol it encounters, which is exactly the problem I was hoping the Web of Things could solve.

We are also creating an extension for Events and property notifications, which can have a few common transfer layer mappings (subProtocols).

I agree that this is an extension to REST, and I think this is a good reason to leave the door open for web protocols to evolve to accommodate this use case. There are range of existing solutions to this problem including webhooks (which is a bit of hack), Server Sent Events (which doesn't yet have very broad browser support), CoAP (which defines additional methods to those HTTP has, but is a whole new protocol) and WebSockets (which isn't very RESTful and requires defining a web thing sub-protocol). In my ideal world we'll eventually see an HTTP/3 which provides a solution to this problem, perhaps something along the lines of CoAP but which is supported natively by web browsers. In the meantime I propose defining a web thing sub-protocol for WebSockets, because this is already supported by web browsers and many other web clients.

There is also a hybrid approach where TD can simply link to a more descriptive external mediatype for interactions, which implements a well-known transfer-interaction model, e.g. mapping for PUT/POST, etc. and pre-selected subProtocols.

I think this is basically what I mean by a concrete REST API specification.

[handrews]

@mjkoster @mkovatsc [edit: thanks for the feedback @benfrancis] could either of y'all give me a hint as to whether the Hyper-Schema stuff might be of interest, and if so what further questions need to be considered to decide whether to investigate it more deeply? You've both been kind enough to engage me on this topic in issues elsewhere, but I can't tell whether we're at "hmm... this might be useful" or "that's nice but we're not reconsidering this at all".

I really don't want to keep wasting everyone's time with long comments if it's not helpful. I'm certainly not going to be offended if you're not interested, but from the small amount of discussion recently it really does feel like you're going very similar places to draft-07.

it is a small extension but I think we are creating a new extension to REST where state changes on the server are orchestrated by the client; the so-called "Action" pattern. We mostly seem to agree that it is more than simply setting resource state.

Based on not just this group but others that I participate in more directly, this is the challenge of hypermedia right now. All of the most difficult discussions of designing hypermedia systems come back to it, and it's certainly something I'm looking at for hyper-schema. I'll post more on this shortly if it's of interest.

[handrews]

[EDIT: I have not dug into the TD's actions work recently so if this is either preaching to the choir or totally off-base, that's why]

I don't think we're inventing anything new here, there is an established pattern for representing actions in REST APIs by POSTing to an action queue. It's not a standard, but it is a widely used design pattern which could be used by one.

OK I know I just said I'd wait for an indication of interest but I have to reply to this :-)

My view on actions is to think of them as "data transitions". Typical hypermedia focuses on transitions from resource to resource, which I think of as "location transitions".

I've been kicking around adding data transition support to hyper-schema by adding a list of possible data transitions to a link description object, which indicate what updates are significant and why. These could be expressed through things like patch media types (JSON Patch or JSON Merge Patch), potentially with form controls on top of them. The results could be applied locally and sent as a PUT, or sent directly as a PATCH (for http/coap).

The point is to associate a vocabulary term of some sort with specific data transitions, which may be either hardcoded (closing an issue is implemented by setting the "status" field to "close") or templatized through form controls (assigning an issue is implemented by setting the "author" field to a client-supplied value that validates against schema {...} or is of semantic type ...).

This is quite different than taking actions out to the fringes of REST via POST and making what is essentially an RPC queue. It maps actions back into state transitions within the uniform interface of REST.

[mjkoster]

Let's say we create a mediatype which we call for the sake of brevity "application/wot+json". This mediatype is used to describe a href target within an interaction. It could be used in "link" because the mediatype describes the transfer layer interaction model.

The "application/wot+json" mediatype defines a serialization constraint on JSON if needed (e.g. using a map for action parameters) and a transfer layer mapping for events, actions, and properties, to http methods, options, and subProtocols.

For example:

Property payloads consist of name-value pairs in a map
{"name": value,
"name": value}
properties support GET and optionally PUT (writeable)
properties are observable using long polling and a separate URI (or some other choice of subProtocol)

Action payloads are a map as in properties:
{"name": value,
"name": value}
Actions support POST to invoke

Events return a map as in properties:
{"name": value,
"name": value}
Events support HTTP long polling on one or more separate URIs (or some other choice of subProtocol)

A Thing Description would, for example, be of mediatype "application/wot-td+json" and could contain links to the "application/wot+json" mediatype within its interactions or maybe specified as a default base.

Here is an example of such a case where a default protocol binding could be defined by the mediatype in the interaction links:

{
  "@context": [
    "http://iotschema.org/w3c-wot-td-context.jsonld",
    "http://iotschema.org/w3c-wot-common-context.jsonld",
    {"iot": "http://iotschema.org/context.jsonld"}
  ],
  "base": "http://example.net:1880",
  "@type": [ "Thing", "iot:MotionControl" ],
  "name": "Motion Sensor",
  "interaction": [
    {
      "name": "Motion State",
      "@type": ["Property", "iot:MotionDetected"],
      "observable": "true",
      "schema":  {
        "type": "object",
        "field": {
          "name": "motionState",
          "@type": ["iot:stateData"],
          "schema": {
              "type": "boolean"
          }
        }
      },
      "link": [
        {
          "href": "/wot+json/motion",
          "mediatype": "application/wot+json"
        },
        {
          "href": "/wot+json/motion/longpoll",
          "rel": ["alternate"],
          "obs" : true,
          "mediatype": "application/wot+json"
        }
      ]
    }
  ]
}

[mjkoster]

Here is the same example using the proposed progressive simplified JSON TD format, with object structured interactions but with a "link" array pointing to resources that use the application/wot+json content format:

{
  "base": "http://example.net:1880",
  "name": "Motion Sensor",
  "property": {
    "MotionState": {
      "observable": "true",
      "schema":  {
        "type": "object",
        "field": {
          "name": "motionState",
          "schema": {
            "type": "boolean"
          }
        }
      },
      "link": [
        {
          "href": "/example/motion",
          "mediatype": "application/wot+json"
        },
        {
          "href": "/example/motion/longpoll",
          "rel": ["alternate"],
          "obs" : true,
          "mediatype": "application/wot+json"
        }
      ]
    }
  }
}

[mkovatsc]

@benfrancis Please also have a look at the text in the proposal, which already gives explanations for many of the design choices. I am updating the text based on your questions.

I try to give quick answers here, although a focused discussion will be hard after the generalization of the issue.

@context

JSON-LD allows for having either a single string (or any type) or an array. In the WG we follow a convention to have arrays wherever arrays are possible to self-describe what is possible and to simplify parsing/serializing (avoid the need for checking if simple type or array).

Question is if you would implement the full support including array or would only support the single string case. If you would support also arrays, would you prefer having the check in your parser/serializer for a more simple-looking TD over reduced parsing complexity?

@type

Array convention also applies here.

The data annotations are mainly for complex types. The syntactic information of object key names does not give you the information what data item must go where. It is again the argument of separating instance (cf., href) from meaning (cf., rel):

From { "temp": 23, "hum": 71 }, only a human can guess the meaning of the fields, because the author was so nice to choose something sensible. To be formal, one needs to attach the semantic type to the keys as well.

Note that capability !== Properties, Actions, Events

Properties, Actions, Events == Interactions

Capabilites == set of Interactions

@id

For identity and related device management. It is necessary for all commercial/industrial use cases.

base

Similar to base in HTML and only an optimization. Alternative would be to enforce only absolute URIs in TDs.

The reason is that the context of a TD can (and very often is) different form the Thing itself. e.g., when using directories or augmenting an existing or constrained Thing with an externally hosted TD.

We could include the rule that if no base is given, relative URIs need to be resolved based on the context. Yet this is a bit error prone when exchanging and moving TDs is a common use case (which it is for us).

schema

Please read the text. JSON Schema syntax is not compatible with JSON-LD, and hence a Linked Data representation. Using it would break the TD model and exclude data schemas from reasoning/machine-handling, which is bad. Furthermore, we (WoT WG and JSON Schema authors) could not find a good solution to integrate semantic annotations in JSON Schema to go the other direction.

Thus, we are only using the JSON Schema vocabulary and use the TD syntax, resulting in a "Linked Data Schema". The syntax given in Example 1 is correct, it is WoT TD syntax.

Units are not syntactic information, but semantic information. As far as I know, they are hence not part of JSON Schema. @handrews please correct or add your view on this.

Thus units would go into the semantic annotations or LD metadata (additional key-value pairs in the elements). We had them once as part of the common TD vocabulary, but then postponed as it was a rather trivial brush-up that can be done toward the end, when the big questions are finished. A main question is, which of the many unit ontologies to pick...

forms

In forms, rel is not a link relation type. It is a form relation type that describes the operation, e.g., Coral:
" A form can be viewed as an instruction of the form "To perform a
form relation type operation on form context, make a request
method request to submission IRI" where the payload of the request
may be further described by form data."

Here get and set are not the methods, but identify that this form is to be used for getting the Property value and setting the Property value (maybe to big step, as they are currently readProperty and writeProperty). The methods are taken from the defaults and not shown in the TD, as they correspond to the default. For get forms it is GET, for set forms it is PUT.

The subProtocol is closing a gap in current links and forms. There is no way to express sub-protocols such as long-poll or SSE; today this is always hard-wired into the application, which is not applicable when you do not own and control both sides of the communication (cf. WebSocket purpose and problem for interoperability).

links

Good, agreement.

Media Type

Good, agreement.

Object vs. Arrays

Yes, for a more intuitive Scripting API, I now also tend toward objects. The @id part is also a nice side-effect.

[handrews]

@mkovatsc

Furthermore, we (WoT WG and JSON Schema authors) could not find a good solution to integrate semantic annotations in JSON Schema to go the other direction.

I'm aware that I haven't been all that attentive here, as much as I wish otherwise, but I did not know that we'd given up on this. Being able to integrate semantic annotations is one of several use cases driving the modularity work that is the primary focus of draft-08. Which has finally gotten unblocked after a month of wrestling with a particularly difficult problem. I still hope to have it published by late May.

I don't know if you want to go into details here, but what is the incompatibility that makes it flat-out impossible to use JSON Schema as specified? I had thought we'd decided that they could be mixed pretty freely. [or we could continue this part of the discussion in json-schema-org/json-schema-spec#309]

[mkovatsc]

@handrews

I did not know that we'd given up on this.

Please understand my above comment for the status quo in the TD spec. I am not done with the simplified proposal and we actually just discussed a further push of hopefully stable JSON-LD 1.1 features, which allow for a virtually identical syntax. JSON Schema validators would only need to be instructed to ignore @... keys in the schema. (You might be able to peek into the coming pull request, but we still need to check this by modelling in OWL..)

The incompatibility has been JSON-LD 1.0. It will be quite a gamble to start a dependency on JSON-LD 1.1. Need to figure out how to deal with this, but JSON-LD 1.1 is really much better...

Are you coming to IETF 101?

[handrews]

@mkovatsc oh, great- sorry, I just woke up, my apologies for misreading :-)

JSON Schema should already ignore @... keys as we do not define any such keywords (and would avoid doing so specifically because JSON-LD uses them). Once draft-08's multi-vocabulary support is finalized, it should be easy to define a "vocabulary" (in the JSON Schema rather than JSON-LD sense) that simply reserves all @... keywords, to ensure that no one tries to process your schemas against some other vocabulary that re-defines JSON-LD's terms. I'll try to put an example of this somewhere and at-mention you.

Regarding IETF 101, no, I won't be there. JSON Schema is the only IETF-related thing I'm doing right now, and when we floated the idea of looking at JSON Schema to the recently-concluded JSON working group, they were quite dismissive of us, and said any such effort would almost certainly not adopt our drafts in anything resembling their current form. No clear reason was given.

We're exploring our options, including the possibility of going through W3C for standardization. In fact I think @draggett might have been on a call with @Relequestual on this topic?

Ironically, another IETF working group just asked us why we weren't on a standards track :-P We pointed them to the working group email thread where we were discouraged from that and haven't heard back. So right now I'm just focusing on meeting our community's needs with draft-08.

[handrews]

@mkovatsc one more point:

Units are not syntactic information, but semantic information. As far as I know, they are hence not part of JSON Schema.

They are not part of JSON Schema validation. Draft-07 and draft-08 are making annotations first-class citizens alongside of assertions (which are what implement validation). Simple annotations such as title are defined in the Validation spec, and Hyper-Schema's links is just a complex annotation.

As we make JSON Schema more modular and extensible, I expect people to extend it mostly with annotations to convey application-specific or usage-specific information. A few people will not doubt make custom validation extensions for cases that are not generic enough to go into the standard validation.

Once we have that it's probably worth looking at best practices for how to integrate semantic information with structural information. Perhaps JSON Schema just considered JSON-LD terms to be annotations (which would be the default behavior if they're not ignored entirely). It might also be worth re-considering JSON Schema's format keyword which is a rather weak semantic extension attached to the validation spec.

So semantic annotations would be in scope for JSON Schema as a generic system (as defined by the Core spec) once we have modular vocabularies. It would just not be in scope for JSON Schema Validation, and there would be no need to re-defined JSON-LD in the context of JSON Schema. We'd just reference it somehow.

[mkovatsc]

This matches my expectations. Units are not part of data validation, they are application-specific and should be annotations as mentioned above. Thanks.

[mkovatsc]

@handrews

BTW: JSON Schema has readOnly and writeOnly, which makes sense for schema properties.

We have only writeable also with a default false, which makes sense for Interaction Properties (some concluded that a write-only Property is basically an Action, as no state is exposed).

Is there a way forward besides making one format ugly? :)

[handrews]

@mkovatsc

JSON Schema already had readOnly (it was in the Hyper-Schema spec, but we moved it over with the other annotations), and OpenAPI has been using readOnly and writeOnly for quite some time. So we adopted writeOnly from them. They are one of the largest users of JSON Schema, and we're working on converging with them.

Write-only properties have several use cases, the two obvious being passwords or similarly sensitive information, and yes, action-ish controls. For those of us who prefer to model actions through state, that is a very important use case and needs to be supported. State need not be exposed to be valid resource state. One way state transfer makes sense in either direction. I'm not trying to sell you on this as much as emphasize that there's a demand for this independent of the TD's views on how to solve the "actions" problem.

Is there a way forward besides making one format ugly? :)

Can you elaborate a bit on ugly vs not-ugly? At this point I stare at so much JSON Schema that I have no idea what looks off to most people :P

[mkovatsc]

Yes, I am aware that they are now part of JSON Schema and I also understand the usage there, why I said it makes sense there :)

For Things the logic is a bit differently, in particular at the top level: When a Thing offers a Property, it is because it wants to expose this internal state. If it is not readable, it would not be a Property in the first place; Action are for modifying state that is not exposed. Hence, writeOnly is not so useful for us.

Being read-only would be the default case for our Properties (e.g., Evrythng proposal and experience), so there is an expectation to be able to omit this information. Thus, we have the attribute writeable, as a boolean default should be false.

When adopting readOnly, we would have to put "readOnly": true for the default case and can omit the statement in the "special" case. I would call this ugly ;)

I am not opposed to align with JSON Schema and OpenAPI, so it might be that we have to live with this.

[handrews]

@mkovatsc thanks, that makes a lot of sense! I do get the point of how and why you ended up with writeable.

What I am hoping is that we can make all of this more modular in a way that implementations can support pluggable vocabularies easily. This would be done by making the annotation collection process much more clear and formalized (until draft-07 there was no guidance at all on it), marking vocabularies at a more granular level, e.g.:

• core ($id, $schema, $ref)
• applicators (all of the keywords that have one or more subschemas as their value)
• validation proper (type, enum, maxLength, maxItems, etc.)
• basic annotation (title, description, default, examples, readOnly, writeOnly)
• hyper-schema (links, base)

and also make it easier to overly constraints on a vocabulary. So you could express something like:

• Using core, applicators, validation, basic annotation, json-ld, and the TD extension vocabulary
• With additional constraints that readOnly and writeOnly are not allowed

and then have writeable in your TD vocabulary. So you'd sacrifice interoperability with any system that tries to use readOnly and writeOnly, but you'd get a clear error if someone tried to use them. If that's what you want, anyway, you could also just ignore them.

There's a lot of hand-waving here but I'm filing the proposals that would implement this in the next week or two, so hopefully we'll make it more concrete very soon.

[benfrancis]

@mjkoster wrote:

Let's say we create a mediatype which we call for the sake of brevity "application/wot+json". This mediatype is used to describe a href target within an interaction. It could be used in "link" because the mediatype describes the transfer layer interaction model.

The "application/wot+json" mediatype defines a serialization constraint on JSON if needed (e.g. using a map for action parameters) and a transfer layer mapping for events, actions, and properties, to http methods, options, and subProtocols.

This is exactly the kind of concrete approach we have in mind, and is what we have started to specify as a Web Thing REST API, and have implemented in our Web of Things gateway implementation. I would like to continue to incubate this approach within the Interest Group, as an extension to the JSON-TD proposal.

You could indeed argue that there should be one MIME type for the Thing Description and one MIME type for the HTTP request payloads. I had just been thinking of it all as part of a Web Thing API.

[benfrancis]

@mkovatsc:

I try to give quick answers here, although a focused discussion will be hard after the generalization of the issue.

I'm happy to split this out into separate issues for areas that warrant a more lengthy discussion. I may have also filed this issue in the wrong repository because I only just realised you put the Siemens proposal in the wot-thing-description repository whereas the other proposals are in this wot repo.

@context

JSON-LD allows for having either a single string (or any type) or an array. In the WG we follow a convention to have arrays wherever arrays are possible to self-describe what is possible and to simplify parsing/serializing (avoid the need for checking if simple type or array).

Question is if you would implement the full support including array or would only support the single string case. If you would support also arrays, would you prefer having the check in your parser/serializer for a more simple-looking TD over reduced parsing complexity?

Fair question. I'd be inclined to support both a string and an array because I imagine a single context could be a common case if stable schema repositories like schema.org emerge.

@type
The data annotations are mainly for complex types. The syntactic information of object key names does not give you the information what data item must go where. It is again the argument of separating instance (cf., href) from meaning (cf., rel):

From { "temp": 23, "hum": 71 }, only a human can guess the meaning of the fields, because the author was so nice to choose something sensible. To be formal, one needs to attach the semantic type to the keys as well.

It has never been my intention that the key names provide semantic information. Rather that a schema for a Web Thing type could define what properties a Thing has. An optional @type for a property could define its meaning.

Note that capability !== Properties, Actions, Events

Properties, Actions, Events == Interactions

Capabilites == set of Interactions

I'm proposing that as a simplification the interactions level could be removed and that capabilities are either a property, action or event.

@id

For identity and related device management. It is necessary for all commercial/industrial use cases.

That doesn't answer my question. Why can't the Thing URL be used as as that identifier? Why is an additional URN needed?

@base
Similar to base in HTML and only an optimization. Alternative would be to enforce only absolute URIs in TDs.

The reason is that the context of a TD can (and very often is) different form the Thing itself. e.g., when using directories or augmenting an existing or constrained Thing with an externally hosted TD.

We could include the rule that if no base is given, relative URIs need to be resolved based on the context. Yet this is a bit error prone when exchanging and moving TDs is a common use case (which it is for us).

OK. Perhaps base can be optional and the Thing URL could be used as a fallback, like in HTML and CSS.

schema

Please read the text. JSON Schema syntax is not compatible with JSON-LD, and hence a Linked Data representation.

I thought the idea of adding a pre-processing step was to remove the hard dependency on JSON-LD and RDF. If these constraints continue to exist, I think that alone justifies continuing to incubate a separate plain JSON serialisation which doesn't suffer from these constraints.

I understand the need to change "properties" to "fields" in schema definitions to avoid confusion, but this serialisation of nested schemas with arrays rather than using JSON Schema object notation seems unnecessarily complex for a JSON serialisation.

Units are not syntactic information, but semantic information. As far as I know, they are hence not part of JSON Schema. @handrews please correct or add your view on this.

Thus units would go into the semantic annotations or LD metadata (additional key-value pairs in the elements). We had them once as part of the common TD vocabulary, but then postponed as it was a rather trivial brush-up that can be done toward the end, when the big questions are finished. A main question is, which of the many unit ontologies to pick...

The JSON-TD proposal suggests case-insensitive fulll names defined in the International System of Units, but I realise this could benefit from a more formal definition.

forms

In forms, rel is not a link relation type. It is a form relation type that describes the operation, e.g., Coral:
" A form can be viewed as an instruction of the form "To perform a
form relation type operation on form context, make a request
method request to submission IRI" where the payload of the request
may be further described by form data."

Here get and set are not the methods, but identify that this form is to be used for getting the Property value and setting the Property value (maybe to big step, as they are currently readProperty and writeProperty). The methods are taken from the defaults and not shown in the TD, as they correspond to the default. For get forms it is GET, for set forms it is PUT.

This is an interesting reference which explains a lot of the thinking in your approach, thanks.

I'd be happy to see some incubation work to test out using this approach with IoT to prove that it allows for the kind of automatic ad-hoc interoperability you imply it does. I remain sceptical but am happy to be proven wrong. In the meantime I'd also like to continue to incubate an approach built only on links and concrete protocol bindings.

[mkovatsc]

Let me split up the issues in JSON tagged Issues in the WG TD repo. A quick info here: digging deeper into JSON-LD 1.1 and applying it allows for further simplifications. If everything works out, the schema of a JSON-LD 1.1 compliant TD might turn out identical to JSON Schema!

[benfrancis]

@mkovatsc: Thanks for filing all those separate issues, next time I will do that in the first place!

The experimental version making use of JSON-LD 1.1 flexibility is already looking interesting.