Plan concrete structure for schemas-as-rest

[bollwyvl]

Elevator Pitch

Adopt a consistent URI/file scheme.

Problem

The original proposal (which wasn't considered normative).

The JEP recommends a URI structure like:

{
  "$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:

{
  "$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

[Zsailer]

👍 to the proposed URI template. Let's proceed with that.

I agree with the file structure. In #1 (already merged), I took this approach and deployed them with data_files.

Let's iterate more in #4.

[bollwyvl]

As discussed in the above-linked meeting notes, we likely need to consider a concrete expansion of all the things we might want to get in here. I'll start up a ROADMAP.md PR so we can consider things line-by-line.