By name: notebook-metadata description: Ensures Jupyter notebooks have required metadata and nbformat. Use when adding, creating, or modifying .ipynb files, or when the user asks about notebook structure or validation.
Notebook Metadata and nbformat
When to Apply
- Adding or creating new Jupyter notebooks
- Modifying notebook structure
- User asks about notebook validation or metadata
Required Structure
Every .ipynb file must have these top-level keys:
| Key | Type | Notes |
|---|---|---|
metadata |
object | Can be empty {} but must exist |
nbformat |
int | Must be 4 or 5 |
nbformat_minor |
int | Minor version |
cells |
list | Array of cell objects |
Minimal Valid Notebook
{
"cells": [],
"metadata": {},
"nbformat": 4,
"nbformat_minor": 4
}
Validation
Run the project script:
python scripts/check_notebook_metadata.py [path]
Omit path to check current directory recursively. Pre-commit runs this automatically on staged .ipynb files.
Fixing Invalid Notebooks
If a notebook is missing fields, add them at the root level:
import json
with open("notebook.ipynb") as f:
nb = json.load(f)
nb.setdefault("metadata", {})
nb.setdefault("nbformat", 4)
nb.setdefault("nbformat_minor", 4)
nb.setdefault("cells", [])
with open("notebook.ipynb", "w") as f:
json.dump(nb, f, indent=1)