Defining an event schema¶
All Jupyter Events schemas are valid JSON schema and can be written in valid YAML or JSON. More specifically, these schemas are validated against Jupyter Event’s “meta”-JSON schema, here.
A common pattern is to define these schemas in separate files and register them with an EventLogger
using the .register_event_schema(...)
method:
schema_filepath = Path("/path/to/schema.yaml")
logger = EventLogger()
logger.register_event_schema(schema_file)
Note that a file path passed to register_event_schema()
must be a Pathlib
object. This is required for register_event_schema()
to distinguish between
file paths and schemas specified in a Python string.
At a minimum, a valid Jupyter event schema requires the following keys:
$id
: a URI to identify (and possibly locate) the schema.version
: the schema version.properties
: attributes of the event being emitted.
Beyond these required items, any valid JSON should be possible. Here is a simple example of a valid JSON schema for an event.
$id: https://event.jupyter.org/example-event
version: 1
title: My Event
description: |
Some information about my event
type: object
properties:
thing:
title: Thing
description: A random thing.
user:
title: User name
description: Name of user who initiated event
required:
- thing
- user
Checking if a schema is valid¶
When authoring a schema, how do you check if you schema is following the expected form? Jupyter Events offers a simple command line tool to validate your schema against its Jupyter Events metaschema.
First, install the CLI:
pip install "jupyter_events[cli]"
Then, run the CLI against your schema:
jupyter-events validate path/to/my_schema.json
The output will look like this, if it passes:
──────────────────────────────────── Validating the following schema ────────────────────────────────────
{
"$id": "http://event.jupyter.org/test",
"version": 1,
"title": "Simple Test Schema",
"description": "A simple schema for testing\n",
"type": "object",
"properties": {
"prop": {
"title": "Test Property",
"description": "Test property.",
"type": "string"
}
}
}
──────────────────────────────────────────────── Results ────────────────────────────────────────────────
✔ Nice work! This schema is valid.
or this if fails:
──────────────────────────────────── Validating the following schema ────────────────────────────────────
{
"$id": "http://event.jupyter.org/test",
"version": 1,
"title": "Simple Test Schema",
"description": "A simple schema for testing\n",
"type": "object",
"properties": {
"__badName": {
"title": "Test Property",
"description": "Test property.",
"type": "string"
}
}
}
──────────────────────────────────────────────── Results ────────────────────────────────────────────────
❌ The schema failed to validate.
We found the following error with your schema:
'__badName' is an invalid property name because it starts with `__`. Properties starting with
'dunder' are reserved as special meta-fields for Jupyter Events to use.