Switch schema version type to str

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:

pyproject.toml

@@ -128,6 +128,7 @@ filterwarnings= [
   "module:datetime.datetime.utc:DeprecationWarning",
   # Ignore importwarning on pypy for yaml
   "module:can't resolve package from __spec__ or __package__:ImportWarning",
+  "ignore::jupyter_events.utils.JupyterEventsVersionWarning",
 ]
 
 [tool.coverage.report]

tests/schemas/bad/bad-id.yaml

@@ -1,5 +1,5 @@
 $id: not-a-uri
-version: 1
+version: "1"
 title: Schema with a Bad URI ID
 description: |
   A schema with a bad id

tests/schemas/bad/nested-reserved-property.yaml

@@ -1,5 +1,5 @@
 $id: http://event.jupyter.org/test
-version: 1
+version: "1"
 title: Schema with Array
 description: |
   A  schema for an array of objects.

tests/schemas/good/array.yaml

@@ -1,5 +1,5 @@
 $id: http://event.jupyter.org/test
-version: 1
+version: "1"
 title: Schema with Array
 description: |
   A  schema for an array of objects.

tests/schemas/good/basic.json

@@ -1,6 +1,6 @@
 {
   "$id": "http://event.jupyter.org/test",
-  "version": 1,
+  "version": "1",
   "title": "Simple Test Schema",
   "description": "A simple schema for testing",
   "type": "object",

tests/schemas/good/basic.yaml

@@ -1,5 +1,5 @@
 $id: http://event.jupyter.org/test
-version: 1
+version: "1"
 title: Simple Test Schema
 description: |
   A simple schema for testing

tests/schemas/good/nested-array.yaml

@@ -1,5 +1,5 @@
 $id: http://event.jupyter.org/test
-version: 1
+version: "1"
 title: Schema with Array
 description: |
   A  schema for an array of objects.

tests/schemas/good/user.yaml

@@ -1,5 +1,5 @@
 $id: http://event.jupyter.org/user
-version: 1
+version: "1"
 title: User
 description: |
   A User model.

tests/test_logger.py

@@ -101,7 +101,7 @@ def test_timestamp_override():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "properties": {
             "something": {
                 "type": "string",
@@ -133,7 +133,7 @@ def test_emit():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "properties": {
             "something": {
                 "type": "string",
@@ -162,7 +162,7 @@ def test_emit():
     del event_capsule["__timestamp__"]
     expected = {
         "__schema__": "http://test/test",
-        "__schema_version__": 1,
+        "__schema_version__": "1",
         "__metadata_version__": 1,
         "something": "blah",
     }
@@ -178,7 +178,7 @@ def test_message_field():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "properties": {
             "something": {
                 "type": "string",
@@ -209,7 +209,7 @@ def test_message_field():
     del event_capsule["__timestamp__"]
     expected = {
         "__schema__": "http://test/test",
-        "__schema_version__": 1,
+        "__schema_version__": "1",
         "__metadata_version__": 1,
         "something": "blah",
         "message": "a message was seen",
@@ -226,7 +226,7 @@ def test_nested_message_field():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "properties": {
             "thing": {
                 "type": "object",
@@ -259,7 +259,7 @@ def test_nested_message_field():
     del event_capsule["__timestamp__"]
     expected = {
         "__schema__": "http://test/test",
-        "__schema_version__": 1,
+        "__schema_version__": "1",
         "__metadata_version__": 1,
         "thing": {"message": "a nested message was seen"},
     }
@@ -274,7 +274,7 @@ def test_register_event_schema(tmp_path):
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -297,7 +297,7 @@ def test_register_event_schema_object(tmp_path):
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -321,7 +321,7 @@ def test_emit_badschema():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -350,7 +350,7 @@ def test_emit_badschema_format():
     """
     schema = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {"type": "string", "title": "test", "format": "date-time"},
@@ -369,7 +369,7 @@ def test_emit_badschema_format():
 def test_unique_logger_instances():
     schema0 = {
         "$id": "http://test/test0",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -381,7 +381,7 @@ def test_unique_logger_instances():
 
     schema1 = {
         "$id": "http://test/test1",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -424,7 +424,7 @@ def test_unique_logger_instances():
     del event_capsule0["__timestamp__"]
     expected = {
         "__schema__": "http://test/test0",
-        "__schema_version__": 1,
+        "__schema_version__": "1",
         "__metadata_version__": 1,
         "something": "blah",
     }
@@ -439,7 +439,7 @@ def test_unique_logger_instances():
     del event_capsule1["__timestamp__"]
     expected = {
         "__schema__": "http://test/test1",
-        "__schema_version__": 1,
+        "__schema_version__": "1",
         "__metadata_version__": 1,
         "something": "blah",
     }
@@ -451,7 +451,7 @@ def test_unique_logger_instances():
 def test_register_duplicate_schemas():
     schema0 = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -463,7 +463,7 @@ def test_register_duplicate_schemas():
 
     schema1 = {
         "$id": "http://test/test",
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -495,7 +495,7 @@ async def test_noop_emit():
     schema_id1 = "http://test/test"
     schema1 = {
         "$id": schema_id1,
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something": {
@@ -507,7 +507,7 @@ async def test_noop_emit():
     schema_id2 = "http://test/test2"
     schema2 = {
         "$id": schema_id2,
-        "version": 1,
+        "version": "1",
         "type": "object",
         "properties": {
             "something_elss": {