-
Notifications
You must be signed in to change notification settings - Fork 7
Open
Description
We need to upgrade @deepnote/blocks dependency to 3.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
| Category | Breaking Change | TypeScript Impact | Auto-Handled When Parsing | Notes |
|---|---|---|---|---|
| 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 |
Summary by Handling Status
✅ Automatically Handled When Parsing (26 items):
- All required metadata fields with defaults
- Empty content constraints (5 blocks)
- Missing metadata object
❌ Requires Manual Migration (22 items):
- Unknown block types
- Field mixing validation
contentHashformat- All datetime validations (5 fields)
- All enum constraints (10 fields)
- Execution fields on non-executable blocks
N/A - API Changes (4 items):
- Discriminated union type narrowing requirement
- Removed public type exports
Metadata
Metadata
Assignees
Labels
No labels