RFCs & Roadmap

Planned modules

We will 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

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

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.

Internationalization

A module to provide the user’s preferred locale to blocks. Please see the GitHub discussion.

Location

A module to provide the user’s location to blocks (with appropriate safeguarding).

Styling

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

Much familiar functionality requires a reference to the current user, or being able to select from users in the system. For example:

• reacting to a post (linking the current user to the post via a reaction)
• assigning a user to an action item (linking the current user to the action item)
• searching for users to mention (having user display names to select from and search)

A users module could help expose some of this data to blocks, with appropriate safeguarding and permissions sought.

Versioning

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.

Changes to existing modules

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

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.

Graph

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.