From 86ef612b592e8275970a9ccbc4822c10e27e27bc Mon Sep 17 00:00:00 2001
From: Johan Mabille <johan.mabille@gmail.com>
Date: Wed, 19 Apr 2023 15:51:20 +0200
Subject: [PATCH] Kernelspec JSON schema

---
 kernelspec-spec/kernelspec-spec.md     | 29 +++++++++++++++++
 kernelspec-spec/kernelspec.schema.json | 44 ++++++++++++++++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 kernelspec-spec/kernelspec-spec.md
 create mode 100644 kernelspec-spec/kernelspec.schema.json

diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md
new file mode 100644
index 00000000..88fa8ae8
--- /dev/null
+++ b/kernelspec-spec/kernelspec-spec.md
@@ -0,0 +1,29 @@
+---
+title: kernelspec specification
+authors: Johan Mabille
+issue-number: XX
+pr-number: XX
+date-started: "2023-04-19"
+---
+
+# Specification of the kernelspec
+
+## Problem
+
+The kernelspec configuration file is documented aside the kernel protocol documentation, but it is not
+*specified*. Besides, it might be unclear whether the kernelspec is part of the kernel protocol, or
+independent.
+
+## Proposed Enhancement
+
+We propose to specify the kernelspec with the JSON schema joined in this PR. The specification is conform
+to [the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs),
+and adds an optional `protocol_version` field.
+
+[A dedicated repo](https://github.com/jupyter-standards/kernelspec) for the specification and the documentation of
+the kernelspec has been created.
+
+### Impact on existing implementations
+
+None, this JEP only adds an optional field in the kernelspec.
+
diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json
new file mode 100644
index 00000000..98190ef1
--- /dev/null
+++ b/kernelspec-spec/kernelspec.schema.json
@@ -0,0 +1,44 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://standards.jupyter.org/kernelspec.schema.json",
+    "title": "Kernelspec",
+    "description": "Specification of the kernelspec file",
+    "type": "object",
+    "properties": {
+        "argv": {
+            "description": "A list of command line arguments used to start the kernel. The text {connection_file} in any argument will be replaced with the path to the connection file.",
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "minItems": 3
+        },
+        "display_name": {
+            "description": "The kernel’s name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters.",
+            "type": "string"
+        },
+        "language": {
+            "description": "The name of the language of the kernel. When loading notebooks, if no matching kernelspec key (may differ across machines) is found, a kernel with a matching language will be used. This allows a notebook written on any Python or Julia kernel to be properly associated with the user’s Python or Julia kernel, even if they aren’t listed under the same name as the author’s.",
+            "type": "string"
+        },
+        "protocol_version": {
+            "description": "The version of protocol this kernel implements. If not specified, the client will assume the version is <5.5 until it can get it via the kernel_info request.",
+            "type": "string"
+        },
+        "interrupt_mode": {
+            "description": "May be either signal or message and specifies how a client is supposed to interrupt cell execution on this kernel, either by sending an interrupt signal via the operating system’s signalling facilities (e.g. SIGINT on POSIX systems), or by sending an interrupt_request message on the control channel (see Kernel interrupt). If this is not specified the client will default to signal mode.",
+            "type": "string",
+            "enume": ["signal", "message"]
+        },
+        "env": {
+            "description": "A dictionary of environment variables to set for the kernel. These will be added to the current environment variables before the kernel is started. Existing environment variables can be referenced using ${<ENV_VAR>} and will be substituted with the corresponding value. Administrators should note that use of ${<ENV_VAR>} can expose sensitive variables and should use only in controlled circumstances.",
+            "type": "object",
+            "additionalProperties": {"type": "string" }
+        },
+        "metadata": {
+            "description": "A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection. Metadata added here should be namespaced for the tool reading and writing that metadata.",
+            "type": "object"
+        }
+    },
+    "required": ["argv", "display_name", "language"]
+}