0
# JupyterLab NBFormat
1

2
JupyterLab NBFormat provides comprehensive TypeScript interfaces and utilities for working with Jupyter Notebook format (nbformat) specifications. It defines strongly-typed interfaces for all notebook components including cells (code, markdown, raw), outputs (execute results, display data, streams, errors), metadata structures, and MIME bundles, enabling type-safe operations on notebook documents and consistent handling of notebook format versions.
3

4
## Package Information
5

6
- **Package Name**: @jupyterlab/nbformat
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jupyterlab/nbformat`
10

11
## Core Imports
12

13
```typescript
14
import * as nbformat from "@jupyterlab/nbformat";
15
```
16

17
Or with specific imports:
18

19
```typescript
20
import { 
21
  INotebookContent, 
22
  ICell, 
23
  ICodeCell, 
24
  validateMimeValue, 
25
  isCode,
26
  MAJOR_VERSION 
27
} from "@jupyterlab/nbformat";
28
```
29

30
For CommonJS:
31

32
```javascript
33
const nbformat = require("@jupyterlab/nbformat");
34
const { INotebookContent, validateMimeValue, isCode } = require("@jupyterlab/nbformat");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { 
41
  INotebookContent, 
42
  ICodeCell, 
43
  validateMimeValue, 
44
  isCode, 
45
  MAJOR_VERSION, 
46
  MINOR_VERSION 
47
} from "@jupyterlab/nbformat";
48

49
// Check format version compatibility
50
console.log(`Supporting nbformat ${MAJOR_VERSION}.${MINOR_VERSION}+`);
51

52
// Create a basic notebook structure
53
const notebook: INotebookContent = {
54
  metadata: {
55
    kernelspec: {
56
      name: "python3",
57
      display_name: "Python 3"
58
    },
59
    language_info: {
60
      name: "python",
61
      version: "3.8.0"
62
    }
63
  },
64
  nbformat: 4,
65
  nbformat_minor: 4,
66
  cells: []
67
};
68

69
// Type-safe cell operations
70
const cells = notebook.cells;
71
cells.forEach(cell => {
72
  if (isCode(cell)) {
73
    console.log(`Code cell with ${cell.outputs.length} outputs`);
74
    console.log(`Execution count: ${cell.execution_count}`);
75
  }
76
});
77

78
// Validate MIME data
79
const isValid = validateMimeValue("text/plain", "Hello, world!");
80
console.log(`MIME validation result: ${isValid}`);
81
```
82

83
## Architecture
84

85
JupyterLab NBFormat is organized around several core concepts:
86

87
- **Notebook Structure**: Complete notebook document format with metadata and cells
88
- **Cell Types**: Strongly-typed interfaces for code, markdown, and raw cells  
89
- **Output System**: Type-safe representation of cell execution results
90
- **MIME Handling**: Validation and type checking for multimedia content
91
- **Type Guards**: Runtime type checking functions for cells and outputs
92
- **Version Compatibility**: Constants and interfaces supporting nbformat 4.4+
93

94
## Capabilities
95

96
### Notebook and Metadata Interfaces
97

98
Core interfaces for notebook documents, metadata structures, and format specifications. Essential for creating and manipulating notebook files programmatically.
99

100
```typescript { .api }
101
interface INotebookContent extends PartialJSONObject {
102
  metadata: INotebookMetadata;
103
  nbformat_minor: number;
104
  nbformat: number;
105
  cells: ICell[];
106
}
107

108
interface INotebookMetadata extends PartialJSONObject {
109
  kernelspec?: IKernelspecMetadata;
110
  language_info?: ILanguageInfoMetadata;
111
  orig_nbformat?: number;
112
}
113

114
const MAJOR_VERSION: number;
115
const MINOR_VERSION: number;
116
```
117

118
[Notebook and Metadata](./notebook-metadata.md)
119

120
### Cell Interfaces and Types
121

122
Comprehensive type definitions for all notebook cell types including code, markdown, and raw cells, with their associated metadata structures.
123

124
```typescript { .api }
125
type ICell = IRawCell | IMarkdownCell | ICodeCell | IUnrecognizedCell;
126
type CellType = 'code' | 'markdown' | 'raw' | string;
127

128
interface ICodeCell extends IBaseCell {
129
  id?: string;
130
  cell_type: 'code';
131
  metadata: Partial<ICodeCellMetadata>;
132
  outputs: IOutput[];
133
  execution_count: ExecutionCount;
134
}
135

136
function isCode(cell: ICell): cell is ICodeCell;
137
function isMarkdown(cell: ICell): cell is IMarkdownCell;
138
function isRaw(cell: ICell): cell is IRawCell;
139
```
140

141
[Cell Interfaces](./cell-interfaces.md)
142

143
### Output Interfaces and Types
144

145
Type-safe interfaces for all cell output types including execution results, display data, streams, and errors, with comprehensive type guard functions.
146

147
```typescript { .api }
148
type IOutput = IUnrecognizedOutput | IExecuteResult | IDisplayData | IStream | IError;
149
type OutputType = 'execute_result' | 'display_data' | 'stream' | 'error' | 'update_display_data';
150

151
interface IExecuteResult extends IBaseOutput {
152
  output_type: 'execute_result';
153
  execution_count: ExecutionCount;
154
  data: IMimeBundle;
155
  metadata: OutputMetadata;
156
}
157

158
function isExecuteResult(output: IOutput): output is IExecuteResult;
159
function isDisplayData(output: IOutput): output is IDisplayData;
160
function isStream(output: IOutput): output is IStream;
161
function isError(output: IOutput): output is IError;
162
```
163

164
[Output Interfaces](./output-interfaces.md)
165

166
### MIME and Validation Utilities
167

168
MIME bundle interfaces and validation functions for handling multimedia content in notebook cells, ensuring data integrity and format compliance.
169

170
```typescript { .api }
171
interface IMimeBundle extends PartialJSONObject {
172
  [key: string]: MultilineString | PartialJSONObject;
173
}
174

175
type MultilineString = string | string[];
176

177
function validateMimeValue(
178
  type: string,
179
  value: MultilineString | PartialJSONObject
180
): boolean;
181
```
182

183
[MIME and Validation](./mime-validation.md)
184

185
## Types
186

187
```typescript { .api }
188
type ExecutionCount = number | null;
189
type OutputMetadata = PartialJSONObject;
190
type StreamType = 'stdout' | 'stderr';
191

192
interface IAttachments {
193
  [key: string]: IMimeBundle | undefined;
194
}
195

196
type ICellMetadata = IBaseCellMetadata | IRawCellMetadata | ICodeCellMetadata;
197

198
// From @lumino/coreutils - base type for JSON-compatible objects
199
type PartialJSONObject = { [key: string]: any };
200
```