Skip to main content
`Ctrl`+`K`

# 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_filepath)

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.