observablejs.types

observablejs.types publishes annotations for advanced inputs and synchronized state.

import observablejs as obs

file: obs.types.FileSpec = {
    "url": "https://example.test/data.csv",
    "mimeType": "text/csv",
}

document: obs.types.ObservableDocument = {
    "title": "Report",
    "nodes": [{"id": 1, "mode": "js", "value": "answer = 42"}],
}

Input contracts

Type	Contract
CellMode, CellFormat	Supported Notebook Kit cell modes and file formats.
CellSelector	String key, authored Cell, or notebook-owned NotebookCell.
NotebookViewOptions	Keyword options shared by Notebook.view() and view factories.
NotebookTheme, ThemePair, Theme	Theme names and light or dark pairs.
FileSpec, FileInput	File input record, URL, or filesystem path.
NotebookKitCellMetadata	Mode metadata for database, format, and since.
ObservableClassicDocument, ObservableNode, ObservableFile	Classic Observable document records.
ObservableNotebookModel, ObservableBody, ObservableCell, ObservableAttachment	Native Notebook Kit source.
ObservablePageDocument, ObservableDocument	Public-page source and the accepted source union.
ObservableResolution	Classic dependency and standard-library resolution.
ObservableSource, ObservableData, ObservableDisplay	Nested ObservableHQ source and display records.

NotebookViewOptions currently accepts one optional key:

Key	Type	Default	Contract
capture_state	bool	True	Synchronizes browser evaluation state with Python.

Runtime parsing remains defensive when JSON data does not match an annotation.

State contracts

CellStatus is pending, success, or error. ErrorPhase is analysis, evaluation, rendering, or serialization.

The immutable records are:

• NotebookState
• ViewState
• CellResult
• CellError
• ViewError
• BrowserErrorValue

FileSnapshot and ThemeSnapshot describe the read-only mappings inside NotebookState.

See Notebook for controller snapshots and View state and graph for browser revisions and results.

Inspection and data contracts

NotebookInspection, CellInspection, ImportInfo, ImportBinding, and AttachmentInspection describe prepared source and static references. DatasetInfo, DatasetDescription, and ColumnInfo describe evaluated data. DataReference and AsyncDataReference provide direct conversions. DataCatalog carries discovered references and diagnostics. These records are available under obs.types. Custom exceptions and diagnostic records live under obs.errors.

See Data access for selectors, formats, and lifecycle.