KhronosGroup / KhronosGroup/glTF

Best practices for JSON schema structure (e.g. in `KHR_interactivity`)

Open
#2,640 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
7.8k
Forks
1.2k
Avg merge
17h 26m
Merged PRs (30d)
5

Description

The JSON schema has a distressing degree of arbitrariness in terms of its structure. There are some general descriptions of what is technically _possible_, e.g. in the [Modular JSON Schema combination](https://json-schema.org/understanding-json-schema/structuring) section. But it's not so explicit about what is "good" or "bad".

One point revolves around the question: **What should be in its own file?**

And I do have the somewhat strong opinion that _each type should be in its own file_. There should not be types that are "inlined" or "nested" in other type declarations. A specific example is that of the `KHR_interactivity` schema. It contains several nested type definitions, like the [event value sockets](https://github.com/KhronosGroup/glTF/blob/f798712c5685bc9223a628140fba707db8889300/extensions/2.0/Khronos/KHR_interactivity/schema/event.KHR_interactivity.schema.json#L15). The type of these elements does not have a name. It's just inlined as the `additionalProperties`.

A _seemingly(!) unimportant_ technical detail here is that my current, home-brewn JSON-to-code-generator handled this by creating a class called `EventInteractivityPropertiesValuesAdditionalProperties`. And one could say "That sounds like _your_ problem", and that's true, and I could trivially override that class name to whatever I want. (Except for... what is the **name** of this thing? Naming is hard...). But I think that having each type in one file could result in a cleaner structure, similar to how you'd try to give a _name_ to structures in Object Oriented class design.

So given that the title of the surrounding element is
`"title": "The event value sockets."`,
I think that this should be pulled into a file that may be called
`EventValueSocket.schema.json`
and that contains a single type definition that can just be `$ref`ed there.

This applies to some of the elements of the interactivity schema spec. Some suggestions for names, based on the respective `title`, could be:

- `event.KHR_interactivity.schema.json` : `values` : `EventValueSocket`
- `node.KHR_interactivity.schema.json` : `configurations`: `Configuration`
- `node.KHR_interactivity.schema.json` : `values`: `InputValueSocket`
- `node.KHR_interactivity.schema.json` : `flows`: `OutputFlowSocket`

Does anyone know **strong, technical** reasons to **not** pull these type definitions into their own files?

Contributor guide

Open the contributing guide

Research direction

Start with the cited KHR_interactivity schema files, especially event.KHR_interactivity.schema.json and node.KHR_interactivity.schema.json, and compare their nested definitions with the proposed separate names. Investigate JSON Schema references and code-generation implications, then establish whether a consistent file and naming convention is wanted; done requires a decided convention and agreement on the affected definitions.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.