diff --git a/kernelspec-spec/kernelspec-spec.md b/kernelspec-spec/kernelspec-spec.md index 88fa8ae8..efcf35d6 100644 --- a/kernelspec-spec/kernelspec-spec.md +++ b/kernelspec-spec/kernelspec-spec.md @@ -10,18 +10,15 @@ date-started: "2023-04-19" ## 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. +The kernelspec configuration file is [documented](https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.rst) aside the kernel protocol documentation, and an [implementation](https://github.com/jupyter/jupyter_client/blob/main/jupyter_client/kernelspec.py#L21) is available, 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. +We propose to specify the kernelspec with the JSON schema joined in this PR. The specification would reflect +[the current description of the kernelspec](https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs), +and adds an optional `kernel_protocol_version` field. -[A dedicated repo](https://github.com/jupyter-standards/kernelspec) for the specification and the documentation of -the kernelspec has been created. +The specification and the documentation of the kernelspec will be stored aside [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) ### Impact on existing implementations diff --git a/kernelspec-spec/kernelspec.schema.json b/kernelspec-spec/kernelspec.schema.json index a0d3f635..d959ee5d 100644 --- a/kernelspec-spec/kernelspec.schema.json +++ b/kernelspec-spec/kernelspec.schema.json @@ -1,9 +1,10 @@ { "$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", + "$id": "https://schemas.jupyter.org/kernelspec-v1.0.schema.json", + "title": "Jupyter Kernelspec", + "description": "A description of the data required to start and manage a Jupyter Kernel", "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.", @@ -22,13 +23,14 @@ "type": "string" }, "kernel_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" + "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. The kernel protocol uses semantic versioning (SemVer).", + "type": "string", + "pattern": "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" }, "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"] + "enum": ["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 ${} and will be substituted with the corresponding value. Administrators should note that use of ${} can expose sensitive variables and should use only in controlled circumstances.", @@ -37,7 +39,8 @@ }, "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" + "type": "object", + "additionalProperties": {"type": "object"} } }, "required": ["argv", "display_name", "language"]