bollwyvl commented 8 months ago

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 commented 8 months ago

:+1: 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.