jupyter / jupyter/telemetry

$id must be valid URI in json schema

Open
#56 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
51
Forks
19
PR merge metrics
No merged PRs in 30d

Description

## Problem

Since JSON Schema Draft 6, `$id` is required to be a valid URI reference as defined in [RFC3986, section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1), which is either a URI (*e.g.,* `http://eventlogging.jupyter.org/event-schema`) or a relative reference ( *e.g.,* `/event-schema`). Currently, the `$id`s used in event schemas across different Jupyter project do not follow this rule:

[`binderhub.jupyter.org/launch`](https://github.com/jupyterhub/binderhub/blob/91e6bdd401b23a6cd19d097d2fa7158465fa02ce/binderhub/event-schemas/launch.json#L2)
[`hub.jupyter.org/server-action`](https://github.com/jupyterhub/jupyterhub/blob/477ee23ad396590482e4f1566ca6acef3961b1a9/jupyterhub/event-schemas/server-actions/v1.yaml#L1)

They lack the scheme part of the URI and thus are not valid URIs.

Due to this the schemas are not guaranteed to always work with JSON schema validators. One example is when trying to use `$ref`

```python
import jsonschema

schema = {
"$id": "hub.jupyter.org/example-schema",
"properties": {
"requester": {"$ref": "#/definitions/user"},
"target_user": {"$ref": "#/definitions/user"}
},
"definitions": {
"user": {
"type": "object",
"properties": {
"name": {"type": "string"},
"id": {"type": "string"}
}
}
}
}

instance = {
"requester": {"name": "a", "id": "1"},
"target_user": {"name": "b", "id": "2"}
}

jsonschema.validate(instance, schema)
```

This would fail

```python
jsonschema.exceptions.RefResolutionError: unknown url type: 'hub.jupyter.org/hub.jupyter.org/example-schema'
```

Change to `"$id": "http://hub.jupyter.org/example-schema"` or `"$id": "/example-schema"` and it validates fine.

There are potentially other undiscovered problems as well.

## Proposed solution

Either change `$id` to fully formed URI or keep it as a relative reference. The later is what's being used in MediaWiki eventlogging ([example](https://schema.wikimedia.org/repositories/primary/jsonschema/mediawiki/user/blocks-change/current.yaml))

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by inspecting the referenced event schema files: binderhub/event-schemas/launch.json and jupyterhub/event-schemas/server-actions/v1.yaml, then reproduce the jsonschema validation example. Check the event schemas for `$id` values that are not valid URI references and update them consistently; done means the affected schemas validate and `$ref` resolution works.

Written by the indexing model from the issue text.

Assessment

Tech stack
json, python, yaml
Domain
backend-api-design
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.