Skip to content

Schema API Reference

The schema module defines the core data structures used throughout BlockNote-py.

Classes

Bases: BaseModel

Represents a Blocknote block with content and children.

A Block is the fundamental unit of content in Blocknote. Blocks can contain inline content and can have child blocks, allowing for nested structures like lists and complex documents.

Attributes:

Name Type Description
id str

Unique identifier for the block
type BlockType

The type of block (paragraph, heading, list items, etc.)
props Dict[str, Any]

Block-specific properties including default styling
content Union[str, List[InlineContent]]

The content of the block (text or list of InlineContent)
children List[Block]

List of child blocks
Source code in .venv/lib/python3.11/site-packages/blocknote/schema/types.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class Block(BaseModel):
    """
    Represents a Blocknote block with content and children.

    A Block is the fundamental unit of content in Blocknote. Blocks can contain
    inline content and can have child blocks, allowing for nested structures
    like lists and complex documents.

    Attributes:
        id: Unique identifier for the block
        type: The type of block (paragraph, heading, list items, etc.)
        props: Block-specific properties including default styling
        content: The content of the block (text or list of InlineContent)
        children: List of child blocks
    """

    id: str = Field(..., description="Unique identifier for the block")
    type: BlockType = Field(..., description="The type of block")
    props: Dict[str, Any] = Field(
        default_factory=dict,
        description="Block-specific and styling properties",
    )
    content: Union[str, List[InlineContent]] = Field(
        default_factory=list, description="The content of the block"
    )
    children: List["Block"] = Field(
        default_factory=list, description="Child blocks"
    )

    @validator("content")
    def validate_content(cls, v, values):
        """Validate that content format matches the block type."""
        if "type" in values:
            block_type = values["type"]
            text_block_types = [
                BlockType.HEADING,
                BlockType.PARAGRAPH,
                BlockType.BULLET_LIST_ITEM,
                BlockType.NUMBERED_LIST_ITEM,
                BlockType.CHECK_LIST_ITEM,
                BlockType.TOGGLE_LIST_ITEM,
                BlockType.QUOTE,
            ]
            if block_type in text_block_types:
                if isinstance(v, str):
                    return [
                        InlineContent(type=InlineContentType.TEXT, text=v)
                    ]
                elif not isinstance(v, list):
                    message = (
                        f"Content for {block_type} must be a string or "
                        "list of InlineContent"
                    )
                    raise ValueError(message)
            elif block_type == BlockType.TABLE:
                # Table content is returned as provided
                pass
        return v

    class Config:
        use_enum_values = True

validate_content(v, values)

Validate that content format matches the block type.

Source code in .venv/lib/python3.11/site-packages/blocknote/schema/types.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@validator("content")
def validate_content(cls, v, values):
    """Validate that content format matches the block type."""
    if "type" in values:
        block_type = values["type"]
        text_block_types = [
            BlockType.HEADING,
            BlockType.PARAGRAPH,
            BlockType.BULLET_LIST_ITEM,
            BlockType.NUMBERED_LIST_ITEM,
            BlockType.CHECK_LIST_ITEM,
            BlockType.TOGGLE_LIST_ITEM,
            BlockType.QUOTE,
        ]
        if block_type in text_block_types:
            if isinstance(v, str):
                return [
                    InlineContent(type=InlineContentType.TEXT, text=v)
                ]
            elif not isinstance(v, list):
                message = (
                    f"Content for {block_type} must be a string or "
                    "list of InlineContent"
                )
                raise ValueError(message)
        elif block_type == BlockType.TABLE:
            # Table content is returned as provided
            pass
    return v

Bases: BaseModel

Represents inline content within a block.

Inline content is the text and styling information that makes up the content of a block. Currently only supports text content with optional styling.

Attributes:

Name Type Description
type InlineContentType

The type of inline content (currently only "text")
text str

The actual text content
styles Dict[str, Any]

Dictionary of styling properties (e.g., {"bold": True})
Source code in .venv/lib/python3.11/site-packages/blocknote/schema/types.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class InlineContent(BaseModel):
    """
    Represents inline content within a block.

    Inline content is the text and styling information that makes up the
    content of a block. Currently only supports text content with optional
    styling.

    Attributes:
        type: The type of inline content (currently only "text")
        text: The actual text content
        styles: Dictionary of styling properties (e.g., {"bold": True})
    """

    type: InlineContentType = Field(
        ..., description="The type of inline content"
    )
    text: str = Field(..., description="The text content")
    styles: Dict[str, Any] = Field(
        default_factory=dict, description="Styling properties"
    )

    class Config:
        use_enum_values = True

Enums

Bases: str, Enum

Enumeration of supported block types in Blocknote.

Source code in .venv/lib/python3.11/site-packages/blocknote/schema/types.py 
30
31
32
33
34
35
36
37
38
39
40
class BlockType(str, Enum):
    """Enumeration of supported block types in Blocknote."""

    PARAGRAPH = "paragraph"
    HEADING = "heading"
    BULLET_LIST_ITEM = "bulletListItem"
    NUMBERED_LIST_ITEM = "numberedListItem"
    CHECK_LIST_ITEM = "checkListItem"
    TOGGLE_LIST_ITEM = "toggleListItem"
    QUOTE = "quote"
    TABLE = "table"

Bases: str, Enum

Enumeration of supported inline content types.

Source code in .venv/lib/python3.11/site-packages/blocknote/schema/types.py 
24
25
26
27
class InlineContentType(str, Enum):
    """Enumeration of supported inline content types."""

    TEXT = "text"

Usage Examples

Creating Blocks

from blocknote.schema import Block, InlineContent, BlockType, InlineContentType

# Simple paragraph
paragraph = Block(
    id="para-1",
    type=BlockType.PARAGRAPH,
    content=[
        InlineContent(
            type=InlineContentType.TEXT,
            text="Hello, World!",
            styles={}
        )
    ]
)

# Heading with styling
heading = Block(
    id="heading-1",
    type=BlockType.HEADING,
    props={"level": 1},
    content=[
        InlineContent(
            type=InlineContentType.TEXT,
            text="Document Title",
            styles={"bold": True}
        )
    ]
)

# List with children
list_item = Block(
    id="list-1",
    type=BlockType.BULLET_LIST_ITEM,
    content=[
        InlineContent(
            type=InlineContentType.TEXT,
            text="Parent item"
        )
    ],
    children=[
        Block(
            id="list-1-1",
            type=BlockType.PARAGRAPH,
            content=[
                InlineContent(
                    type=InlineContentType.TEXT,
                    text="Child item"
                )
            ]
        )
    ]
)

Working with Styles

# Text with multiple styles
styled_content = InlineContent(
    type=InlineContentType.TEXT,
    text="Styled text",
    styles={
        "bold": True,
        "italic": True,
        "textColor": "#ff0000",
        "backgroundColor": "#ffff00"
    }
)

# Block with styled content
styled_block = Block(
    id="styled-1",
    type=BlockType.PARAGRAPH,
    content=[styled_content]
)

Validation

All schema classes use Pydantic for validation:

from pydantic import ValidationError

try:
    # This will raise a validation error
    invalid_block = Block(
        id="invalid",
        type="invalid_type",  # Not a valid BlockType
        content=[]
    )
except ValidationError as e:
    print(f"Validation error: {e}")

Type Definitions

Block Properties

Different block types support different properties:

Block Type Supported Props Example
heading level (1-6) {"level": 2}
checkListItem checked (bool) {"checked": True}
paragraph textAlignment {"textAlignment": "center"}

Style Properties

Inline content supports various styling options:

Style Property Type Description Example
bold bool Bold text {"bold": True}
italic bool Italic text {"italic": True}
underline bool Underlined text {"underline": True}
strike bool Strikethrough text {"strike": True}
code bool Inline code formatting {"code": True}
textColor str Text color (CSS color) {"textColor": "#ff0000"}
backgroundColor str Background color {"backgroundColor": "#ffff00"}