JSON schema

[dontcallmedom]

See http://lists.w3.org/Archives/Public/site-comments/2018Jan/0005.html and https://datatracker.ietf.org/doc/draft-handrews-json-schema/

[jdesrosiers]

@mnot Thank you, that's really useful information!

Regarding RFCs being "done", we don't consider that the case for HTTP (where four separate RFCs have defined HTTP/1.1 successively - 2068, 2616, 7230, and 9112).

Actually, HTTP was what I had in mind when I mentioned reasons for change being the world changing and real life being messy. I know you expect things may need updates from time to time. However, that's not same thing as a continuous maintenance / "living spec" type of process. I haven't seen an RFC Series spec that works like that, but I'm very intrigued to hear that there might be support for such a process within the IETF or the Independent Stream.

[mnot]

Could you like us to maybe a few RFCs from the Independent Stream?

See: https://rfc.fyi/?stream=independent

I did a little reading and it looks like the RFC could only be published as "Informational" or "Experimental". Is that correct?

Correct.

It looks like the preferred contact method is to email rfc-ise@rfc-editor.org, correct?

Yes.

I know you expect things may need updates from time to time. However, that's not same thing as a continuous maintenance / "living spec" type of process.

In my mind, you'd be publishing drafts (either as Internet-Drafts or on your own site) more often, with publications of 'checkpoint' / 'milestone' RFCs less often. YMMV, of course.

[egekorkan]

Dear W3C Strategy team,

This comment represents the collective opinion of the W3C Web of Things (WoT) Working Group (WG) and has been reviewed by the entire group.

The WoT WG is a long-time user and supporter of the JSON Schema activities. This message has been conveyed in the past via a joint blog post at the JSON Schema blog (see here), which was also reviewed by the W3C MarComm team.

The WoT WG supports the path the JSON Schema Project has decided to take in becoming a self-governed entity that maintains the JSON Schema standards. We prefer W3C to consider JSON Schema specifications to be normatively referencable and integratable into W3C specifications. This is supported due to its strong usage within the WoT WG, which is explained below. The WoT WG needs a firm basis for our current and future standardization work.

Usages within WoT WG

WoT WG uses JSON Schema in the WoT Thing Description Recommendation since its first public working draft, still a major part of the 1.1 Recommendation and will be used in the scope of the next WG charter in similar ways.

Data Modeling and Description

The primary use of JSON Schema is modeling and description of the data that an IoT device sends or receives. TD document calls it a Data Schema (see this section), which is tightly bound to the JSON Schema specification but also to its lifecycle. We have even published a JSON Schema ontology at https://www.w3.org/2019/wot/json-schema#

Problem: The WG had to manually copy over a subset of JSON Schema Draft 7 since we are not able to create a normative reference to JSON Schema and tell our readers, users, and implementers that they can just the JSON Schema Draft 7 version. This is problematic because:

• This requires additional work from the WG to write, sync, and maintain it.
• Our readers, users, and implementers get confused. Some implementers started implementing a JSON Schema validator from scratch since they did not realize that they could use an off-the-shelf validator
• There is the potential to create an accidentally incompatible dialect by not staying aligned with JSON Schema.

Validation of TD Instances

Since WoT TDs are usually serialized into JSON-LD, we provide a JSON Schema for validation of TDs. This is published together with the REC at https://www.w3.org/2022/wot/td-schema/v1.1 and is used by the WoT Discovery specification for validation of TDs submitted to a TD Directory. Other validations (code, SHACL) are also possible but JSON Schema is a good balance of lightweightness and expressiveness.

JSON Schema is also the core of the tooling used for generating the implementation report, a crucial step in getting to the REC stage.

Scripting Usage

WoT Scripting API uses JSON Schema for two purposes:

1. Generation of TypeScript definitions, which are used by open-source projects such as the Thingweb project in the Eclipse Foundation. These can be found at https://github.com/w3c/wot-scripting-api/tree/main/typescript
2. It describes a validation process of payloads at https://www.w3.org/TR/wot-scripting-api/#dfn-check-data-schema, which can be omitted if JSON Schema can be just referenced. This has caused implementation issues in the past since the algorithm was stricter than the validation algorithm used in JSON Schema.

[egekorkan]

Also see https://landscape.json-schema.org/ for JSON Schema's adoption in the industry overall, where WoT is also listed.