tomevault-io 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)
Source: albumentations-team/albumentations_examples — distributed by TomeVault.