⚠ This page is served via a proxy. Original site: https://github.com
This service does not collect credentials or authentication data.
Skip to content

Upgrade @deepnote/blocks to 3.x.x #283

@saltenasl

Description

@saltenasl

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
  • contentHash format
  • 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

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions