Plan concrete structure for schemas-as-rest
- Dominant language
- Python
- Stars
- 4
- Forks
- 6
- PR merge metrics
- No merged PRs in 30d
Description
## Elevator Pitch
Adopt a consistent URI/file scheme.
## Problem
The original proposal (which wasn't considered normative).
The [JEP](https://github.com/Zsailer/enhancement-proposals/blob/7f462d9251794ef035fefdfff9ecd2cc26cd7616/jupyter-subdomain-for-schemas/proposal.md#guide-level-explanation) recommends a URI structure like:
```json
{
"$id": "https://schema.jupyter.org/jupyter_server/some-event/v1/event.json"
}
```
- uses `{:name_space}/v{:version}/{:noun}.json`
- underscores look bad when underlined (which they often will, as URL-like things)
#1 proposes some URIs that would look like:
```json
{
"$id": "https://schema.jupyter.org/jupyter_server/events/kernel_actions/v1"
}
```
- uses `{:name_space}/{:version}`
- but is _named_ `{:version}.json`
While neither of these are _referenced_ anywhere, it really doesn't matter that they don't line up. However, as these schemas here _will_ reference each other, it's important we have something of a plan
## Proposed
### URI template
As a starting point for discussion, I recommend:
```
https://schema.jupyter.org/{:name-space}/v{:version}/{:noun}.schema.json
```
- this ensures we're not looking at five `v1.json` at the same time
- using `-` gives better visual separation when rendered as a link
- using `.schema.json` makes it clear that e.g. `kernelspec.schema.json` _isn't_ an instance of itself
### File structure
Move these out of the python package, to the root of the repo:
```
https://github.com/jupyter/schema/blob/main/schema/server/contents/v1/contents.schema.json
```
- these will still be deployed with e.g. `data_files`
## Some examples
```
https://schema.jupyter.org/kernel/messages/v1/any.schema.json
https://schema.jupyter.org/kernel/messages/v1/execute-request.schema.json
https://schema.jupyter.org/kernel/messages/v1/execute-response.schema.json
https://schema.jupyter.org/kernel/spec/v1/kernelspec.schema.json
https://schema.jupyter.org/server/contents/v1/contents.schema.json
https://schema.jupyter.org/server/events/kernel-actions/v1/kernel-actions.schema.json
```
## Gotchas
- the depth of nesting is up to the implementer, but probably _shouldn't_ mix versions and nouns
```
https://schema.jupyter.org/kernel/messages/v1/execute-response.schema.json
https://schema.jupyter.org/kernel/v1/any.schema.json
```
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.