jupyter / jupyter/nbformat

Consider making metadata.kernelspec.display_name optional

Open
#448 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.