Specification

The open-source protocol for creating interactive, data-driven blocks

This document is a working draft

This specification is currently in progress. We’ve drafting it in public to gather feedback and improve the final document. If you have any suggestions or improvements you would like to add, feel free to submit a PR on our Github repo.

Introduction

This document specifies a protocol for defining web ‘blocks’ – discrete components displayed on a web page or other application – and how they communicate with any application embedding them.

It defines how structured data is passed between blocks and embedding applications, enabling any protocol-compliant application to use any protocol-compliant block to make structured data viewable and editable by users.

What’s a specification?

A specification is a document that outlines how a system should be built. They help make applications and websites interoperable.

Overview

A quick note

This section is narrative and guidance which will form part of explanatory material rather than the specification itself. It is included in this preliminary document to aid the reader in understanding the full context, but will be published outside the spec in its final form.

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 requires learning its own particular data interface and 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.

It does this by specifying:

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

Given a catalog of blocks built in this way, 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 would be 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.

Terminology

Entity: an instance of data conforming to a schema, typically with a unique identifier.

Schema: a definition of a data structure, prescribing the shape of an entity. In the context of the protocol, schemas are used both to describe the data a block type accepts (e.g. the schema for a Table block type), as well as the structure of data representing other entities (e.g. the schema for a Person, Movie, or List).

Properties: the fields on a schema, what types of data are permitted as their values, and any other validation rules. Field types may be scalar (integer, string etc.), complex objects, collections (lists/arrays), or refer to another schema.

Block type: a definition and implementation – i.e. code – for a discrete component on a web page, which provides functionality for structured data (rendering it, editing it). A block type specifies the data it accepts via a schema in accordance with the spec.

Block: an instance of a block type inserted into a web page and supplied with data by an embedding application.

Block package: a collection of files making a block type available for use by embedding applications, including its source code and accompanying metadata.

Embedding application: an application which can take a block type and insert it in a web page, supplying the block with the structured data and dependencies it needs in accordance with the specification.

When capitalized, the words ‘MUST’, ‘MUST NOT’, ‘SHOULD’, ‘SHOULD NOT’, and ’MAY’ in this document are to be interpreted as described in IETF RFC 2119.

This document is focused on web software, but the principles of the contract between blocks and embedding applications can also be applied to other software.

Add blocks to your app

Anyone with an existing application who wants to embed semantically-rich, reusable blocks in their product can use the protocol. Improve your app’s utility and tap into a world of structured data with no extra effort, for free.

Build your own blocks

Any developer can build and publish blocks to the global registry for other developers to use. Create blocks that solve real-world problems, and contribute to an open source community changing the landscape of interoperable data.