Consider making metadata.kernelspec.display_name optional
- Dominant language
- Python
- Stars
- 313
- Forks
- 176
- PR merge metrics
- No merged PRs in 30d
Description
### Problem
The notebook v4 schema requires both `name` and `display_name` whenever
`metadata.kernelspec` is present:
https://github.com/jupyter/nbformat/blob/main/nbformat/v4/nbformat.v4.5.schema.json
However, `name` is the stable identifier needed to select a kernel, while
`display_name` is presentation metadata belonging to the locally installed
kernelspec. Requiring it duplicates a local UI label in every notebook.
This is particularly visible with text notebook formats such as Jupytext,
where remembering the kernel currently requires serialising:
```yaml
kernelspec:
display_name: Python (my-project)
name: my-project
```
The useful persistent information is only:
```yaml
kernelspec:
name: my-project
```
This is not exclusively a Jupytext issue. JupyterLab can itself produce a
kernelspec containing only `name` after a kernel is uninstalled, after which
nbformat validation prevents the notebook from opening:
https://github.com/jupyterlab/jupyterlab/issues/17303
### Minimal reproduction
```python
import nbformat
nb = nbformat.v4.new_notebook()
nb.metadata.kernelspec = {"name": "python3"}
nbformat.validate(nb)
```
This raises:
```text
NotebookValidationError: 'display_name' is a required property
```
### Proposed change
Would maintainers consider making `display_name` optional in the next
appropriate notebook-format revision, while continuing to require `name`?
Consumers could use the following fallback:
1. If `display_name` is present, use it.
2. Otherwise, if `name` resolves locally, use the installed kernelspec's
`display_name`.
3. Otherwise, display `name`.
This preserves the existing ability to record a historical/readable label,
while allowing minimal metadata when only kernel selection needs to persist.
I understand that documents omitting `display_name` would not validate against
older schemas, so this may require a notebook-format minor revision and
corresponding frontend fallback support.
Related discussion about whether local kernelspec information belongs in
notebook metadata:
https://github.com/jupyter/nbformat/issues/81
Contributor guide
Research direction
Start with nbformat/v4/nbformat.v4.5.schema.json and reproduce the issue using nbformat.v4.new_notebook() followed by nbformat.validate(). Check how the schema represents kernelspec.name and display_name, then assess the appropriate notebook-format revision and validation coverage. Done means name remains required while display_name can be omitted without validation failure.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100