Getting started with the Block Protocol


The Block Protocol is a global standard for building interactive blocks connected to structured data.

The following pages provide a practical introduction for developers who want to:

For the full technical details, read the Block Protocol specification.

If you have any questions, please open or contribute to a discussion. You can also chat to us on Discord.

Why is structured data useful?

Structured data makes it much easier for computers to understand the information we give them.

Most of the data on the web is unstructured. When we write webpages in HTML, it's easily readable by humans, but not by computers. The computer only knows you've added a bunch of <p> tags to a page, but doesn't understand the contents or shape of what you've written inside (at least without any fancy natural language processing).

Unlike plain HTML, blocks created with the Block Protocol have types, such as Person, Company, and Date that help computers understand what they actually contain.

Imagine you are creating a webpage to announce a book signing event with a well-known author. You could add an Author block, a Location block, and a Time block to this page. Instead of being some mystery HTML, your information is now readable by computers. It would be much easier to automatically pass this information to other websites and applications, such as a calendar application, or the author's personal website.

We are trying to fulfil the vision of the Semantic Web (aka. the OG Web3, before all the NFTs took over!), transforming the web's randomly formatted, human-readable pages into structured troves of connected knowledge, improving both user and developer experiences as we go.

What is a block?

Blocks are the basic units we use to build pages on the modern web. They are rectangular sections that contain a set of features and functions. They are sometimes also called components or widgets.

Each block has a type that determines the kind of data it can display and edit. You're probably familiar with the most common block types such as paragraph, header, image, list, and table. Some block types have more advanced interactive features such as filtering, search, and sorting.

There are an infinite number of possible block types. One goal of the Block Protocol is to encourage developers to build and share brand new types of blocks that haven't been seen before, and for applications to offer users far more blocks than any one team could imagine or build.

Blocks can be added to webpages using plain HTML and/or JavaScript. Some modern content management systems (eg. WordPress, Squarespace) and applications (eg. Notion, Coda) allow you to add blocks to a page using a visual interface. With these block-based editors you can usually rearrange the order of blocks on a page using drag and drop. Blocks can be stacked on top of one another, arranged in columns, or embedded inside other blocks.

From a developer perspective, blocks encapsulate a set of specific functionality. Building a block is no different to writing a React, Vue, or Web Component – in fact, these are all ways you might implement a block. They are reusable elements that expect certain data to be passed to them (what we refer to as a block’s ‘schema’). For example, an image block might only accept an image URL in its src property, not a number.

What is a Block Protocol block?

Any block can become a Block Protocol block by meeting the requirements defined in the BP specification. These requirements define what data a block can accept and how they're allowed to edit that data.

Following these requirements allows BP blocks to do more than regular web blocks. This standardized way of handling data makes it possible to embed BP blocks across different web applications. BP blocks can read and write data to the applications they're embedded within without any extra setup or custom integrations (as long as both the block and embedding application adhere to the specification).

BP blocks can also be published to the Block Hub – an open-source registry where anyone can publish their blocks for other people to discover and use.

Any application can accept BP blocks, as long as they follow the requirements for embedding applications.

Demo applications

You can find the source code for one example embedding application, HASH, on GitHub. This is a work-in-progress environment which illustrates how both blocks and an application using them can be implemented.

If you support the Block Protocol in your open-source application, contact us to appear here.

We're hiring full-stack TypeScript/React and PHP plugin developers to help grow theBlock ProtocolWordPress ecosystem.Learn more