Specification

Introduction

Structure

The Block Protocol is split into a core specification and module specifications.

The core specification sets out:

• how blocks should be defined;
• how embedding applications should initialize blocks;
• how applications and blocks communicate;
• how additional modules are defined.

Each module specification defines what applications and blocks communicate (i.e. the contents of the communications themselves). A module is a logical grouping of messages blocks and applications may exchange.

• Graph Module: provides a shared definition of semantic data that blocks and apps should commonly use.
• Hook Module: allows blocks to defer to embedding applications to provide arbitrary interfaces in blocks.
• Service Module: allows blocks to interact with external services without needing to be provided with credentials.

The core specification, and each module specification, are versioned separately, allowing them to evolve independently. Any reference to the ‘protocol version’ should be read as the version of the core specification.

Separate core and module specifications were introduced in version 0.2 of the Block Protocol.

Overview

Many modern content creation systems, such as WordPress and Notion, use a concept of ‘blocks’ to build content pages from. Users typically click on a big + button which allows them to insert one of any number of blocks of different types (e.g. paragraph, list, table, video). Pages built in this modular fashion can be as varied and interactive as the repertoire of available blocks. But these block systems are generally closed ecosystems. It is either (a) impossible for users to create new block types, or (b) impossible to use any block types created in one of these applications in another.

Even outside of content creation systems, web developers make use of a wide range of software libraries which implement web blocks: libraries to display, select, or edit particular types of data. These all have their own definition of what data they accept, how to send data into them, and how they send data back out. Making use of these libraries often requires learning a specific data interface and its idiosyncrasies.

This protocol aims to address both problems by defining a contract for data transfer between blocks and the applications which wish to make use of them, and how blocks describe the data they accept. If you adopt this protocol:

• Any block type from anywhere can be immediately embeddable in any compliant embedding application without any further documentation or configuration.
• Block types and the data they create and consume will not be tied to any specific implementation and may be easily ported between applications.
• Given a particular data structure, embedding applications can determine which block types are suitable for displaying and editing it.

The protocol enables this by specifying:

• the functions which block types should call to request or update data, and which embedding applications should provide to blocks,
• that blocks should express the data they accept in a machine-readable format.

Given a catalog of blocks built in compliance with the protocol, and embedding applications which know how to use them – which we can provide abstractions for – users can more easily find and use blocks to display and edit data structures they are interested in, be that tasks, tweets, or anything else.

A user could take a data structure, and search for blocks which can handle that data structure (or a useful portion of it) – whether they are a developer wanting to bundle a block with an application, or an end user of an embedding application which allows users to find and add new blocks themselves.

Blocks are as customizable as any other current component allows, but with a strong default setup, theme, and a predictable interface governed by this protocol, that provides plug-and-play functionality for data.