| Type System |
DeepnoteBlock now a discriminated union |
✅ Yes - requires type narrowing |
N/A |
Consumer code must use type guards to access variant-specific fields |
| Type System |
Unknown block types rejected |
✅ Yes |
❌ No |
Discriminated union will fail validation for any unrecognized type value |
| Type System |
Cannot mix fields from different block types |
✅ Yes |
❌ No |
Each block must match exactly one schema variant |
| Required Metadata |
BigNumberBlock.metadata.deepnote_big_number_title |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
BigNumberBlock.metadata.deepnote_big_number_value |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
BigNumberBlock.metadata.deepnote_big_number_format |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
All input blocks: metadata.deepnote_variable_name |
✅ Yes - now required string |
✅ Yes - defaults to 'unnamed_variable' |
TS type shows required; parsing provides default |
| Required Metadata |
InputTextBlock.metadata.deepnote_variable_value |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputTextareaBlock.metadata.deepnote_variable_value |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputCheckboxBlock.metadata.deepnote_variable_value |
✅ Yes - now required boolean |
✅ Yes - defaults to false |
TS type shows required; parsing provides default |
| Required Metadata |
InputSelectBlock.metadata.deepnote_variable_value |
✅ Yes - now required |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputSelectBlock.metadata.deepnote_variable_options |
✅ Yes - now required array |
✅ Yes - defaults to [] |
TS type shows required; parsing provides default |
| Required Metadata |
InputSelectBlock.metadata.deepnote_variable_custom_options |
✅ Yes - now required array |
✅ Yes - defaults to [] |
TS type shows required; parsing provides default |
| Required Metadata |
InputSelectBlock.metadata.deepnote_variable_selected_variable |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputSelectBlock.metadata.deepnote_variable_select_type |
✅ Yes - now required enum |
✅ Yes - defaults to 'from-options' |
TS type shows required; parsing provides default |
| Required Metadata |
InputSliderBlock.metadata.deepnote_variable_value |
✅ Yes - now required string |
✅ Yes - defaults to '0' |
TS type shows required; parsing provides default |
| Required Metadata |
InputSliderBlock.metadata.deepnote_slider_min_value |
✅ Yes - now required number |
✅ Yes - defaults to 0 |
TS type shows required; parsing provides default |
| Required Metadata |
InputSliderBlock.metadata.deepnote_slider_max_value |
✅ Yes - now required number |
✅ Yes - defaults to 100 |
TS type shows required; parsing provides default |
| Required Metadata |
InputSliderBlock.metadata.deepnote_slider_step |
✅ Yes - now required number |
✅ Yes - defaults to 1 |
TS type shows required; parsing provides default |
| Required Metadata |
InputDateBlock.metadata.deepnote_variable_value |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputDateRangeBlock.metadata.deepnote_variable_value |
✅ Yes - now required |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
InputFileBlock.metadata.deepnote_variable_value |
✅ Yes - now required string |
✅ Yes - defaults to '' |
TS type shows required; parsing provides default |
| Required Metadata |
NotebookFunctionBlock.metadata.function_notebook_id |
✅ Yes - now required (nullable) |
✅ Yes - defaults to null |
TS type shows required; parsing provides default |
| Required Metadata |
Missing metadata object on any block |
✅ Yes - metadata now required |
✅ Yes - defaults to {} |
All block schemas have .default({}) |
| Validation |
contentHash must match /^(md5|sha256):[a-f0-9]+$/i |
✅ Yes - stricter type |
❌ No |
Old format hashes will fail validation |
| Validation |
executionStartedAt must be ISO datetime string |
✅ Yes - stricter type |
❌ No |
Non-ISO formats will fail validation |
| Validation |
executionFinishedAt must be ISO datetime string |
✅ Yes - stricter type |
❌ No |
Non-ISO formats will fail validation |
| Validation |
execution.startedAt must be ISO datetime string |
✅ Yes - stricter type |
❌ No |
Non-ISO formats will fail validation |
| Validation |
execution.finishedAt must be ISO datetime string |
✅ Yes - stricter type |
❌ No |
Non-ISO formats will fail validation |
| Validation |
ImageBlock.metadata.deepnote_img_width enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'actual', '50%', '75%', '100%' allowed |
| Validation |
ImageBlock.metadata.deepnote_img_alignment enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'left', 'center', 'right' allowed |
| Validation |
TextCellCalloutBlock.metadata.color enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'blue', 'green', 'yellow', 'red', 'purple' allowed |
| Validation |
SqlBlock.metadata.deepnote_return_variable_type enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'dataframe', 'query_preview' allowed |
| Validation |
ButtonBlock.metadata.deepnote_button_color_scheme enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'blue', 'red', 'neutral', 'green', 'yellow' allowed |
| Validation |
ButtonBlock.metadata.deepnote_button_behavior enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'run', 'set_variable' allowed |
| Validation |
InputSelectBlock.metadata.deepnote_variable_select_type enum constraint |
✅ Yes - limited to specific values |
✅ Yes - defaults to 'from-options' |
Only 'from-options', 'from-variable' allowed |
| Validation |
execution.triggeredBy enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'user', 'schedule', 'api', 'ci' allowed |
| Validation |
environment.python.environment enum constraint |
✅ Yes - limited to specific values |
❌ No |
Only 'uv', 'conda', 'venv', 'poetry', 'system' allowed |
| Content Constraints |
ImageBlock.content must be empty |
✅ Yes - typed as literal('') |
✅ Yes - preprocessed to '' |
Non-empty content automatically cleared |
| Content Constraints |
SeparatorBlock.content must be empty |
✅ Yes - typed as literal('') |
✅ Yes - preprocessed to '' |
Non-empty content automatically cleared |
| Content Constraints |
ButtonBlock.content must be empty |
✅ Yes - typed as literal('') |
✅ Yes - preprocessed to '' |
Non-empty content automatically cleared |
| Content Constraints |
VisualizationBlock.content must be empty |
✅ Yes - typed as literal('') |
✅ Yes - preprocessed to '' |
Non-empty content automatically cleared |
| Content Constraints |
NotebookFunctionBlock.content must be empty |
✅ Yes - typed as literal('') |
✅ Yes - preprocessed to '' |
Non-empty content automatically cleared |
| Field Scope |
Execution fields only on executable blocks |
✅ Yes - not present in non-executable types |
❌ No |
executionCount, executionStartedAt, executionFinishedAt, outputs will cause validation failure on non-executable blocks |
| Public API |
Removed BlockMetadata union type export |
✅ Yes - no longer exported |
N/A |
Import from schema instead |
| Public API |
Removed ExecutableBlockMetadata interface export |
✅ Yes - no longer exported |
N/A |
Types now inferred from schema |
| Public API |
Removed individual block metadata type exports |
✅ Yes - no longer exported |
N/A |
Use schema-inferred types instead |
We need to upgrade
@deepnote/blocksdependency to3.x.x. It makes the deepnote file format (block schema to be more specific) much more strict. We need to handle the breaking changes gracefully to not break our customer projects.Breaking Changes in Deepnote File Schema
DeepnoteBlocknow a discriminated uniontypevalueBigNumberBlock.metadata.deepnote_big_number_title''BigNumberBlock.metadata.deepnote_big_number_value''BigNumberBlock.metadata.deepnote_big_number_format''metadata.deepnote_variable_name'unnamed_variable'InputTextBlock.metadata.deepnote_variable_value''InputTextareaBlock.metadata.deepnote_variable_value''InputCheckboxBlock.metadata.deepnote_variable_valuefalseInputSelectBlock.metadata.deepnote_variable_value''InputSelectBlock.metadata.deepnote_variable_options[]InputSelectBlock.metadata.deepnote_variable_custom_options[]InputSelectBlock.metadata.deepnote_variable_selected_variable''InputSelectBlock.metadata.deepnote_variable_select_type'from-options'InputSliderBlock.metadata.deepnote_variable_value'0'InputSliderBlock.metadata.deepnote_slider_min_value0InputSliderBlock.metadata.deepnote_slider_max_value100InputSliderBlock.metadata.deepnote_slider_step1InputDateBlock.metadata.deepnote_variable_value''InputDateRangeBlock.metadata.deepnote_variable_value''InputFileBlock.metadata.deepnote_variable_value''NotebookFunctionBlock.metadata.function_notebook_idnullmetadataobject on any block{}.default({})contentHashmust match/^(md5|sha256):[a-f0-9]+$/iexecutionStartedAtmust be ISO datetime stringexecutionFinishedAtmust be ISO datetime stringexecution.startedAtmust be ISO datetime stringexecution.finishedAtmust be ISO datetime stringImageBlock.metadata.deepnote_img_widthenum constraint'actual','50%','75%','100%'allowedImageBlock.metadata.deepnote_img_alignmentenum constraint'left','center','right'allowedTextCellCalloutBlock.metadata.colorenum constraint'blue','green','yellow','red','purple'allowedSqlBlock.metadata.deepnote_return_variable_typeenum constraint'dataframe','query_preview'allowedButtonBlock.metadata.deepnote_button_color_schemeenum constraint'blue','red','neutral','green','yellow'allowedButtonBlock.metadata.deepnote_button_behaviorenum constraint'run','set_variable'allowedInputSelectBlock.metadata.deepnote_variable_select_typeenum constraint'from-options''from-options','from-variable'allowedexecution.triggeredByenum constraint'user','schedule','api','ci'allowedenvironment.python.environmentenum constraint'uv','conda','venv','poetry','system'allowedImageBlock.contentmust be emptyliteral('')''SeparatorBlock.contentmust be emptyliteral('')''ButtonBlock.contentmust be emptyliteral('')''VisualizationBlock.contentmust be emptyliteral('')''NotebookFunctionBlock.contentmust be emptyliteral('')''executionCount,executionStartedAt,executionFinishedAt,outputswill cause validation failure on non-executable blocksBlockMetadataunion type exportExecutableBlockMetadatainterface exportSummary by Handling Status
✅ Automatically Handled When Parsing (26 items):
❌ Requires Manual Migration (22 items):
contentHashformatN/A - API Changes (4 items):