notebook-metadata

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)