Switch schema version type to str (#104)

* Switch schema `version` type to `str`

Type coerce `version` to be a string

* lints

* pass interoogate

---------

Co-authored-by: M Bussonnier <[email protected]>

Author: afshin

docs/demo/demo-notebook.ipynb

@@ -47,7 +47,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -72,7 +72,7 @@
    "source": [
     "schema = \"\"\"\n",
     "$id: http://myapplication.org/example-event\n",
-    "version: 1\n",
+    "version: \"1\"\n",
     "title: Example Event\n",
     "description: An interesting event to collect\n",
     "properties:\n",

docs/user_guide/application.md

@@ -22,7 +22,7 @@ Register an event schema with the logger.
 ```python
         schema = """
         $id: http://myapplication.org/my-method
-        version: 1
+        version: "1"
         title: My Method Executed
         description: My method was executed one time.
         properties:

docs/user_guide/defining-schema.md

@@ -27,7 +27,7 @@ Beyond these required items, any valid JSON should be possible. Here is a simple
 
 ```yaml
 $id: https://event.jupyter.org/example-event
-version: 1
+version: "1"
 title: My Event
 description: |
   Some information about my event
@@ -67,7 +67,7 @@ The output will look like this, if it passes:
 
     {
       "$id": "http://event.jupyter.org/test",
-      "version": 1,
+      "version": "1",
       "title": "Simple Test Schema",
       "description": "A simple schema for testing\n",
       "type": "object",
@@ -92,7 +92,7 @@ or this if fails:
 
     {
       "$id": "http://event.jupyter.org/test",
-      "version": 1,
+      "version": "1",
       "title": "Simple Test Schema",
       "description": "A simple schema for testing\n",
       "type": "object",

docs/user_guide/event-schemas.md

@@ -13,7 +13,7 @@ from jupyter_events.logger import EventLogger
 
 schema = """
 $id: http://myapplication.org/example-event
-version: 1
+version: "1"
 title: Example Event
 description: An interesting event to collect
 properties:
@@ -38,7 +38,7 @@ print(logger.schemas)
 Validator class: Draft7Validator
 Schema: {
   "$id": "myapplication.org/example-event",
-  "version": 1,
+  ""version": 1",
   "title": "Example Event",
   "description": "An interesting event to collect",
   "properties": {

docs/user_guide/first-event.md

@@ -15,7 +15,7 @@ To begin emitting events from a Python application, you need to tell the `EventL
 ```python
 schema = """
 $id: http://myapplication.org/example-event
-version: 1
+version: "1"
 title: Example Event
 description: An interesting event to collect
 properties:

jupyter_events/schemas/event-core-schema.yml

@@ -1,6 +1,6 @@
 $schema: http://json-schema.org/draft-07/schema
 $id: http://event.jupyter.org/event-schema
-version: 1
+version: "1"
 title: Event Schema
 description: |
   A schema for validating any Jupyter Event.
@@ -12,7 +12,7 @@ properties:
     const: 1
   __schema_version__:
     title: Schema Version
-    type: integer
+    type: string
   __schema__:
     title: Schema ID
     type: string

jupyter_events/schemas/event-metaschema.yml

@@ -1,14 +1,14 @@
 $schema: http://json-schema.org/draft-07/schema
 $id: http://event.jupyter.org/event-metaschema
-version: 1
+version: "1"
 title: Event Metaschema
 description: |
   A meta schema for validating that all registered Jupyter Event
   schemas are appropriately defined.
 type: object
 properties:
   version:
-    type: integer
+    type: string
   title:
     type: string
   description:

jupyter_events/schemas/property-metaschema.yml

@@ -1,6 +1,6 @@
 $schema: http://json-schema.org/draft-07/schema
 $id: http://event.jupyter.org/property-metaschema
-version: 1
+version: "1"
 title: Property Metaschema
 description: |
   A metaschema for validating properties within

jupyter_events/utils.py

@@ -0,0 +1,8 @@
+"""
+Various utilities
+"""
+from __future__ import annotations
+
+
+class JupyterEventsVersionWarning(UserWarning):
+    """Emitted when an event schema version is an `int` when it should be `str`."""

jupyter_events/validators.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import pathlib
+import warnings
 from typing import Any
 
 import jsonschema
@@ -10,6 +11,7 @@
 from referencing.jsonschema import DRAFT7
 
 from . import yaml
+from .utils import JupyterEventsVersionWarning
 
 draft7_format_checker = (
     Draft7Validator.FORMAT_CHECKER
@@ -57,6 +59,17 @@
 def validate_schema(schema: dict[str, Any]) -> None:
     """Validate a schema dict."""
     try:
+        # If the `version` attribute is an integer, coerce to string.
+        # TODO: remove this in a future version.
+        if "version" in schema and isinstance(schema["version"], int):
+            schema["version"] = str(schema["version"])
+            msg = (
+                "The `version` property of an event schema must be a string. "
+                "It has been type coerced, but in a future version of this "
+                "library, it will fail to validate. Please update schema: "
+                f"{schema['$id']}"
+            )
+            warnings.warn(JupyterEventsVersionWarning(msg), stacklevel=2)
         # Validate the schema against Jupyter Events metaschema.
         JUPYTER_EVENTS_SCHEMA_VALIDATOR.validate(schema)
     except ValidationError as err: