jupyter / jupyter/schema

Plan concrete structure for schemas-as-rest

Open
#2 2 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.