microsoft / microsoft/typespec
Add alternative JSON schema bundling suitable for JSON path refs
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
### Clear and concise description of the problem
The current bundling for JSON schema uses the 2020-12 approach requiring `$id` values for every schema. This has many implications for developers, including:
- Tooling must support the latest draft of the standard. Many tools have not yet been updated (e.g. json-schema-ref-parser)
- References between schemas within the bundle are no longer compatible with JSON path, making it considerably more difficult to find or build tools that can resolve cross references within the bundle (and probably explains why existing tools have not yet been updated)
- The `$id` values imply versioning. If we don’t incorporate a version into the `$id`, then it is impossible to unambiguously distinguish referenced versions without overlaying a custom versioning/referencing scheme (I haven’t yet seen a dialect that includes this). For packages of related schemas, it is preferable to version at the package level rather than at the individual schema level. Versioning at the individual schema level is a maintenance nightmare (it would be equivalent to versioning each type/model in a Typescript or TypeSpec package). Even at the package level, I would prefer that versioning is managed in a separate dependency management tool like npm (as is done for TypeSpec).
- The `$id` values imply a requirement for a resolvable, fixed URL for each schema if we want to support JSON-path-compatible references. For flexible packaging and publication (e.g. in a schema or artifact repository), it is not desirable to “lock” the individual schema into a specific, resolvable URL base. Even at the package level, while use of non-resolvable, canonical URLs is an option, it means these `$id` values will not resolve with a JSON path reference unless appropriate routing infrastructure is maintained to ensure the URL resolves to the preferred artifact storage (which inevitably changes over time).
To avoid these impacts, could you please add a bundling option that generates a simpler bundle using relative JSON path references between schemas in the bundle, and also permitting the use of external JSON path references relative to the bundle parent. The parent could still include a `$id` if desired, although ideally it would be optional to avoid the need to manage non-resolvable, canonical URLs and the versioning implications noted above.
A possible structure would be something like:
```
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
“title”: “mynamespace“,
“$defs”: {
“sub-namespace”: {
“schema1”: {
“type”: “object”,
“properties”: {
…
}
},
“schema2”: {
“type”: “object”,
“$ref”: “schema1”
}
}
}
}
```
Say the above is stored in `mynamespace.json`, I can then reference this from other, external schemas like this:
```
“$ref”: “schemas/mynamespace.json#/$defs/sub-namespace/schema1”
```
### Checklist
- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Contributor guide
Assessment
This issue has not been assessed yet.