# WoT WG/IG Position for JSON Schema

## Logistics

- Review: Call for resolution after the main call on 17th of April. Email to member's list: https://lists.w3.org/Archives/Member/member-wot-wg/2024Apr/0003.html
- Target: A single comment at the W3C Strategy Issue at https://github.com/w3c/strategy/issues/108
- Commenter: Ege Korkan (@egekorkan) but it can/should be discussed. The commenter represents the whole group.

## Resources

Previous collaboration: https://json-schema.org/blog/posts/w3c-wot-case-study

Other relevant resources:
- https://github.com/json-schema-org/community/pull/325
- https://github.com/orgs/json-schema-org/discussions/671
- https://github.com/w3c/strategy/issues/108
- https://github.com/json-schema-org/json-schema-spec/pull/1500

## Submission text

Dear W3C Strategy team,

This comment represents the collective opinion of [the W3C Web of Things (WoT) Working Group (WG)](https://www.w3.org/groups/wg/wot/) 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](https://json-schema.org/blog/posts/w3c-wot-case-study)), which was also reviewed by the W3C MarComm team.

The WoT WG supports the path 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 it 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](https://www.w3.org/TR/wot-thing-description11/#sec-data-schema-vocabulary-definition)), 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 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 can 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 the 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 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](https://www.thingweb.io/) in [the Eclipse Foundation](https://www.eclipse.org/).
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 more stricter than the validation algorithm used in JSON Schema.