Roadmap

Our aim is to develop a new standard for building frontend components, or "blocks", whose styling and logic are cleanly separated from data. Learn more >

Adoption strategy

• Develop valuable new blocks that provide utility to early-adopters. Users of blocks should be attracted by the promise of obtaining new superpowers in their existing block-based applications, not merely out of appreciation for the protocol's technical design.
• Prototype implementations at every step. Battle-testing the specification and proving (or disproving) ideas early saves time, and minimizes arguments about hypotheticals. Multiple diverse prototype environments ensure abstractions generalize across embedding applications.
• Design and build in the open. Our public RFC process is outlined on this page. Our monorepo is publicly accessible to anybody. Our code is open-source and can be hosted, forked, or otherwise evolved by the community without our prior permission.
• Zero reliance on centralized hosted services. Hosted services are provided as a convenience only.

  • Things like the Þ Hub complement the specification by providing a means of discovering blocks, types, services, and hooks, but its use is not required.
  • Similarly, embedding applications can utilize the Block Protocol's hosted middleware to provide fallbacks to users where blocks ask for things that an app itself doesn't natively support — for example, an integration with a particular new external service. But embedders may equally well choose not to fallback to the Þ middleware, and instead limit the selection of blocks their users are shown in the first place to only those which are fully supported locally.
  • In due course, we intend to allow third-party services to "announce" the existence of externally hosted schemas and blocks to the Þ Hub, enabling content published and hosted elsewhere to be easily discovered via the same endpoints. We want to make it easy for people to host their own hubs, whose contents remain discoverable and mappable (where users choose to make them public).

History

• Version 0.1: in January 2022, an early 0.1 draft of the Block Protocol was shared on Joel Spolsky's blog. This outlined the concept of the Block Protocol, and an initial proposed technical specification was shared alongside the source code for an example embedding application, HASH.
• Version 0.2 and Graph Module: in June 2022, version 0.2 of the specification launched at WeAreDevelopers in Berlin. This introduced the modular architecture used by the protocol today, including an initial release of the graph module, improving support for structured data in blocks separated from its logic.
• Hook Module: in October 2022, the hook module was added to the specification, allowing blocks to integrate tightly with the native capabilities of embedding applications, in an application non-specific way. For example, this allowed blocks with text fields to share the shortcuts, commands and text-styling/controls alreay present within their environment.
• Version 0.3: in February 2023, we released the biggest update to the Block Protocol yet, overhauling the graph module, and introducing the new type system.
• Service Module: that month we also introduced "zero-knowledge support" for external services and integrations in blocks. This provided blocks with the ability to communicate with external APIs and services, including those which require API keys, without embedding applications having to specifically support (or even be aware of) those services. This allowed users to access external APIs from services like OpenAI and Mapbox within blocks, without needing to sign up for their own accounts, manage billing separately from the apps they already use, or worry about API keys.
• WordPress support: additionally in February 2023, we launched the Block Protocol for WordPress integration for Wordpress.com and self-hosted WordPress users. This made the Block Protocol accessible to all users of the world's most widely used content management system (CMS).
• HASH launch: our core team are currently focused on readying the open-source HASH application for production. HASH is the most advanced and complete implementation of the Block Protocol today. View its developer roadmap at hash.dev/roadmap

Future Plans

RFCs

The "RFC" (Request For Comment) process provides a consistent and controlled path for new features to enter the protocol's specification. Many changes, including most bug fixes and documentation improvements can be implemented and reviewed without going through this process. However, when changes are considered "substantial" enough, we require that they first take shape as RFCs, are subject to community comment, and are designed in a way that produces broad agreement approved by the Block Protocol core team. This process serves to transparently document in detail the considerations behind major changes, and enables spec evolution to take place in a way that accounts for all community member's interests.

Active RFCs:

Browse here

This link will be replaced with direct links to the RFCs on blockprotocol.org soon

New modules

We expect to introduce the following new modules to the Block Protocol to support additional functionality that requires application-block cooperation. We welcome suggestions for other modules that may be useful, via GitHub discussions or by creating RFCs.

Actions module

A generalized approach to capturing user actions could involve a module whereby a block reports on which elements within it capture actions (e.g. a button), and embedding applications could choose to bind further actions to them as a response.

Comments module

We want to facilitate users leaving comments on elements within blocks. This could be:

• managed entirely outside the block, e.g. by a wrapper around the block which provides a context menu to users for adding comments on blocks – which avoids blocks having to have any knowledge of commenting, but could interfere with how the block wants to respond to user input, or
• managed by providing a new module whereby blocks could send messages requesting that comments be attached to specific elements in blocks – which allows blocks to have control over how and to what element the user is able to attach comments.

Browser Permissions module

We want to enable blocks to access certain browser-provided information about users, in a securely permissioned fashion.

• Blocks should be able to specify what permissions they want to ask users for.
• Apps should be able to selectively choose whether or not to ask users for these (e.g. camera/microphone access, clipboard access, location information, etc).
• Users should be able to choose on a block-by-block basis which blocks have the ability to utilize browser permissions they have shared with a given embedding application

Styling module

The styling module would involve the embedding application to communicate styling or theming data to blocks, to allow blocks to apply styling to make them appear more visually consistent with the application embedding them.

Please see the GitHub discussion for a discussion of what data might be transported as part of a styling module (e.g. a styleObject, or a CSS file).

Users module

Versioning module

While embedding applications can handle displaying an interface for reloading blocks at particular earlier versions, we will specify a way of communicating to blocks that (a) an earlier version is being displayed, and (b) the difference with the current version would allow blocks to implement visual diffs.

Updating modules

The below changes to existing modules are currently being considered.

Core

Block definition

Block entry point: we currently provide that blocks can be exposed to applications in three different ways: as custom elements, HTML files, or React components. We may wish to reduce this to a single entry point. Please see the discussion for more.

Module permissions / requirements

Problem:

• Applications may implement some modules only, or implement part of a module only (e.g. allowing createEntity but not createEntityType).
• Many blocks will require certain modules, and parts of modules.
• Blocks will not work in applications that do not implement the modules they require, and the parts of modules they require. If there is a mismatch which is not identified prior to a block being selected for use, they may crash or be non-functional at the point of use.

Proposal:

In order to predict in advance whether a given block will work in a given application, it would be helpful for blocks to be able to indicate which modules and parts of modules they require.

The most detailed version of this would be for blocks to be able to:

• express requirements/support at a module level (e.g. requires: "graph"), and
• express finer-grained detail, e.g.

  • which specific messages from a module they require/support
  • any additional detail on what they require from a message, which might be a particular scope, e.g. access to retrieve or create particular types of entities.

Service module

Block-user authentication: we will be providing a mechanism for users to insert their own secrets for use when connecting to external services which require them to individually authenticate, in order to access their own private information within blocks (e.g. Coda).

Generic callback handler: we will be removing service/provider specific references from the specification and making the service module more readily extensible, in anticipation of allowing third-party providers to self-register additional services.

Graph module

Entity type extension and duplication

Currently, if a user wants to add additional information to an existing entity type, their only option is to make a brand new one and manually copy the structure. We'd like to add support for users to be able to "extend" types in a way that doesn't break existing entity types and allows for reusability across embedding applications and blocks. To allow for situations where a user wants to customize an entity type in a way that a non-compatible fashion, we want a mechanism to "duplicate" or "fork" an existing entity type. For in-depth motivation, a proposed implementation plan, and the wide-reaching implications please see the RFC.

Non-primitive data types

We define six primitive data types in the Graph type system. These data types define value spaces for the inner properties of entities, and currently are limited to basic primitives such as "text" or "number". Building robust data models will require the ability to define constraints and define validation mechanisms (think maximum/minimum lengths on properties, or applying regular expressions to define the pattern of a string). We are thinking about implementing this through allowing the creation of non-primitive data types, built off the composition and extension of other data types coupled with a suite of supported constraints. You can read more about this in this RFC.

Pagination

We intend to move to a cursor-based method for paginating results of querying entities, likely based on the Connections specification.

Schema mapping

The Block Protocol does not seek to describe or prescribe the shape of particular entities (e.g. what fields a Person has).

Instead, it seeks to define the block-application interface.

This does, however, mean there is a possibility of competing schemas attempting to describe the same entities, which different blocks using different schema - reducing the portability of blocks.

The ability to translate between schemas would help - e.g. some way expressing an equivalence relationship between properties in different schema. This might be a keyword such as sameAs or equivalentTo mapping between schemas and their properties. Then, either blocks or embedding applications could programmatically translate between schemas.

Note that this is about translating between different JSON Schemas, and is not to be confused with the process of translating JSON schema to schema.org (and equivalent) types, which has an established technical approach mentioned here.