Simplified TD: schema

[mkovatsc]

Moderated focused discussion on the Simplified TD proposal and schema. Please stay on topic and use w3c/wot#393 for any general remarks.

In w3c/wot#393 @benfrancis wrote:

• 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

[mkovatsc]

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, until now 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.

Note: We are still very interested in finding a solution that would work across all these standards! So far, our requirement for JSON-LD was higher, hence we followed that alignment. With JSON-LD 1.1 now having a working group charter, it is becoming an option to move it toward JSON Schema, which at a first glance (see #102) looks possible.

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...

[mkovatsc]

In w3c/wot#393 @benfrancis wrote:

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.

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.

[handrews]

NOTE: I'm going to say "schema vocabulary" for the JSON Schema concept of vocabularies to keep it separate from the more well established JSON-D vocabulary concept. Let's assume that plain vocabulary means a JSON-LD vocabulary

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

Is there a concise definition of the incompatibility that I can read up on? Just a link to the appropriate part of the JSON-LD spec that conflicts would suffice. @mkovatsc I clicked on your "text" link above but it seems to just say that it generally "breaks paradigms".

Aside from that, I particularly do not understand this comment:

the need to change "properties" to "fields" in schema definitions to avoid confusion

I had thought that JSON-LD was quite flexible about mapping some terms to other terms, so is there a reason that properties must specifically be reserved? Is that the main conflict in terms of syntax?

The JSON-LD @ keywords are not a conflict b/c JSON Schema has avoided using anything with an @ prefix. If we go with the schema vocabulary approach outlined in json-schema-org/json-schema-spec#561 then reserving all @ keywords as a JSON-LD schema vocabulary would just look like:

JSON-LD-only meta-schema:

{
    "$id": "https://json-schema.org/draft-08/vocabularies/json-ld",
    "$schema": "http://json-schema.org/draft-08/schema#",
    "patternProperties": {
        "^@": true
    }
}

Meta-schema for use with the TD:

{
    "$id": "https://example.org/wot/schemas/td",
    "$schema": "http://json-schema.org/draft-08/schema#",
    "$vocabularies": [
        "http://json-schema.org/draft-08/vocabularies/core-applicators",
        "http://json-schema.org/draft-08/vocabularies/validation-assertions",
        "http://json-schema.org/draft-08/vocabularies/json-ld"
    ],
    "allOf": [
        {"$ref": "http://json-schema.org/draft-08/vocabularies/core-applicators"},
        {"$ref": "http://json-schema.org/draft-08/vocabularies/validation-assertions"},
        {"$ref": "http://json-schema.org/draft-08/vocabularies/json-ld"}
    ],
    "$comment": "plus any custom properties specific to the TD would be defined here"
}

I apologize if I'm asking for things that were well covered elsewhere, but as we seem to be re-focusing the discussions, having all of the problems with JSON Schema laid out clearly in one place would be helpful.

[mkovatsc]

@handrews

Is there a concise definition of the incompatibility that I can read up on?

The main incompatibility is that with JSON-LD 1.0, we cannot use objects, but always must use arrays for correctly modeling complex types. Yet JSON Schema makes extensive use of objects, as it is much nicer.

For the sake of a single solution, we now look into options to base the TD on JSON-LD 1.1, which is work-in-progress, and hence problematic as normative dependency. Let's discuss this issue and why now elsewhere. Anyhow, the great news is that with JSON-LD 1.1, we can use object notation and derive the correct triples describing the schema in Linked Data. In #102 you already saw that it could work out, but let's wait for @vcharpenay to confirm the underlying OWL model. One issue still is how to deal with $ref vs JSON-LD references or how to get the $ref functionality (importing statements into an existing node) into JSON-LD.

is there a reason that properties must specifically be reserved

When using a single entry point interactions for TD interactions, there would only be confusion around schema properties and TD Properties.

When going back to three entry points properties, actions, events as proposed by JSON-TD and now also the Simplified TD for a better programming model, then there is an actual JSON-LD terminology conflict, as as of now, the TD properties and schema properties need to be mapped to different RDF classes.

However: I experimented with the concept of @draggett 's proposal, where Properties can be recursive, however, I kept the ability to identify and address individual Properties through a URI -- in particular the top-level one. This makes TD properties and schema properties the same base RDF class with the option to extend it by adding a links predicate ("RDF Property -- yet another use of the term "property"). Top-level properties should always have a links field. A links in a sub-property basically means that I can address and retrieve a single item or subtree in a schema, which is useful for instance for IPSO Objects / LWM2M.

@handrews I think we need to check if that matches your concept of assigning links to elements in a JSON Schema. In particular, I have to think more about your merging rule when you reference sub-schemas...

[handrews]

@mkovatsc I have filed json-ld/json-ld.org#612 to sort out questions regarding JSON-LD's JSON Schema, to see how to fit it into the schema vocabulary concept we have filed as json-schema-org/json-schema-spec#561

Top-level properties should always have a links field. A links in a sub-property basically means that I can address and retrieve a single item or subtree in a schema, which is useful for instance for IPSO Objects / LWM2M.

That sounds at least plausibly similar to attaching links to a sub-property in JSON Hyper-Schema. There are three contact points to a JSON Hyper-Schema link:

• The context (per RFC 8288)
• The target (per RFC 8288)
• The attachment point (per Hyper-Schema)

The target is always URI-identified. The context should be URI-identified, but if the link is attached to some place other than the root of a document, and the document's media type does not define a suitable fragment syntax, then a JSON Pointer may be needed to fully identify the context (need to think on how that fits with RFC 8288).

The attachment point is literally the location in the instance to which the link is attached. So given a collection of elements. a link with "rel": "item" would be attached to an element, would point to the full resource of the element, but would have the collection as the context (it is an item of a collection, so the collection must be the context).

A "rel": "self" link attached to each element would have the same target (and attachment point) as the "rel": "item" link, but the context would be the individual element (same as the attachment point), because it is a link from the self-within-the-collection (individual element) to the same resource as an independent entity.

{
  "type": "object",
  "links": [{
    "rel": "self",
    "href": "/things",
    "targetSchema": {"$ref": "#"}
  }],
  "properties": {
    "elements": {
      "type": "array",
      "items": {
        "properties": {"id": {"type": "integer", "minimum": 1}},
        "links": [{
          "rel": "item",
          "anchor": "/things",
          "href": "/things/{id}",
        },{
          "rel": "self",
          "href": "/things/{id}",
        },{
          "rel": "collection",
          "href": "/things",
          "targetSchema": {"$ref": "#"}
        }]
      }
    }
  }
}

For the two element links that do not set "anchor" directly, the anchor is the instance location to which the link is attached, e.g. /things#/elements/0, /things#/elements/1, etc.

• /things (collection) -> "rel": "item" -> /things/1234 (item-on-its-own)
• /things#/element/0 (item-in-collection) -> "rel": "collection" -> /things` (collection)
• /things#/elements/0 (item-in-collection) -> "rel": "self" -> /things/1234 (item-on-its-own)

In particular, I have to think more about your merging rule when you reference sub-schemas...

which merging rules do you have in mind? There have been several "merge" proposals in JSON Schema, most of which have been rejected in favor of several other features and approaches.

[sebastiankb]

Since w3c/wot#393 is closed and schema is now part of the TD we can close this issue.