FAQs

The Block Protocol provides a specification for the interaction between web blocks and applications using them: how data structures are typed and passed around, and what data operations are available to blocks.

Its ultimate goal in doing so is to enable any blocks to be usable by any web application without any configuration, once both are compliant with the Protocol.

More information on the motivation can be found in the specification overview.

The Block Protocol’s focus is on defining the interface between web blocks and applications using them.

It does not specify what happens to data once it crosses that boundary - it only seeks to standardise application-block interaction.

Existing web protocols do not define standardized interfaces between blocks and applications that might embed them.

Efforts exist to do this for particular ecosystem (e.g. Microsoft Loop Components, and application-specific plugin frameworks) - but none which aim to improve the web as a whole. The Block Protocol is a generic contract which can be implemented by any web application.

Various frontend libraries and technologies provide means of implementing encapsulated blocks (e.g. React, Web Components), but they do not standardize the interface between those blocks and the applications using them (e.g. the operations available to them).

Our focus is on supporting the web first and foremost, as this is the context we expect the Block Protocol to be most useful in, but we believe it will be portable to other environments.

Since version 0.2 of the Block Protocol, messages are passed between blocks and applications by dispatching and listening for events, which is a pattern which can be translated to many non-web contexts. While some implementation details will vary across contexts, the general principles of the Block Protocol in defining a contract between applications and embedded blocks are widely applicable.

In the future we intend to support non-web contexts more directly.

Anybody with web development experience can build a block to add functionality to any application that implements the Block Protocol.

Individuals may be motivated by any of the factors that already motivate people to build open-source software: challenge, competition, fun, reputation, and the desire to contribute to and be part of a community.

Open-sourcing blocks allows other interested users to contribute back to improving those blocks further, enhancing their utility and fixing bugs.

Stephen Walli writes that open-sourcing code isn't always "contributing back out of altruism. It was engineering economics. It was the right thing to do, and contributed back to the hardening of the [product] we were using ourselves. It was what makes well run open source projects work."

Implementing the Block Protocol means that an embedding application can easily add new functionality, increasing its value to users.

Once they are Block Protocol-compliant, applications can easily search for blocks which can visualize or edit any type of data, and add them without any further configuration.

The Block Protocol has been open-sourced by HASH, whose mission is to help everybody make the right decisions. Part of how we'll make a dent in this problem is by clearly separating display, visualization and interaction logic from underlying data, while making it easier to bring data together in a form that can be understood by both humans and machines (e.g. other applications).

HASH started life as a simulation platform, offering insights from modeling the world to anyone with a browser. But this is just one way to get insight from data, and simulation models can be greatly enhanced when built atop the sort of timely, structured information that the Block Protocol makes accessible.

The Block Protocol advances HASH’s mission by encouraging both data itself and the tools that edit and visualize data to be structured and portable. This makes it easier to work with more data in more places, and unlocks more functionality for more users, increasing the ability for people to understand and learn from the world.

Blocks can be published on the Hub to make them browsable on blockprotocol.org, and to make their metadata and source code available via our API.

Entity data can be hosted in any application which implements the Block Protocol (e.g. HASH). If you are developing an embedding application you would like listed here, please get in touch.

Blocks can fetch their own data from external services. For example, a map block might fetch data from a mapping service.

We believe the best blocks will communicate data back and forth with the embedding application, making use of the operations defined in the spec.

For example, a mapping block which persists a user’s choices about map positioning or styling back to the application – all without the application having to know anything about the block, or the block having to know anything about the application.

One aim of the Block Protocol is that blocks can store and retrieve data in an application without awareness of how exactly the data is stored.

Blocks can have their own local state - they might use this to allow users to explore data or draft changes, without saving anything.

To save data beyond the session, blocks should make use of the operations defined in the spec to send updates to the embedding application.

The Block Protocol standardizes how data requests are made between a block and an embedding application.

Web Components (or custom elements) are one way of implementing Block Protocol blocks.

Web Components can describe the events they dispatch programmatically, but each one can be different. This means that you often need to know the details of how of a specific element operates in order to implement it. The goal of the Block Protocol is to make it so that new blocks can be added to an application without any configuration or without having to learn how they handle data.

We believe blocks should provide neutral, minimal styling of their own, and leave it to embedding applications to provide additional styling - this might be in the form of an entire stylesheet for blocks to load, or style variables which can be selectively applied.

There is ongoing discussion on this topic - we welcome your views.

Rich text editing is a core part of many modern block-based applications, but details often vary across applications:

• how rich text is represented in existing applications varies depending on the particular approach used
• applications often provide special functionality inside rich text fields, e.g. being able to @mention or search for things inline

We do not believe it feasible or desirable to impose a single rich text editing experience across applications, and instead have introduced the Hook Service to allow embedding applications to inject their own rich text editing display and input, at blocks' request.

Blocks composed of other blocks is an important feature which we believe the Block Protocol must support, and which we have begun exploring.

A simple example is a ListBlock which is composed of a list of other blocks, and for which it has placeholders within it.

Blocks which are made up of other blocks may be referred to as “compound blocks”. We will be publishing example compound blocks soon.

The goal of the Semantic Web is to make internet data machine-readable.

It involves making sure there is data on web pages which can be parsed by machines, in order to determine the entities described, and their links to other entities elsewhere on the web.

The Block Protocol requires that the data passed between blocks and applications is in the form of entities conforming to a defined structure: a schema.

This structure can then be used to include data on web pages which describes the entities in a machine-readable way.

While the Block Protocol doesn’t require this data to be exposed or made downloadable, we do encourage embedding applications to do this as much as possible.

For example, where a page contains a block displaying a movie, machine-readable data would also be included describing the various properties of the movie (e.g. releaseDate), as well as linking to other pages which describe entities linked to it - e.g. its director.

One way of representing entities in a machine-readable way is in JSON-LD which describes entities and their link to other entities). Here’s an example of such a representation, taken from the JSON-LD homepage:

{
  "@context": "https://json-ld.org/contexts/person.jsonld",
  "@id": "http://dbpedia.org/resource/John_Lennon",
  "name": "John Lennon",
  "born": "1940-10-09",
  "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}

The structure of entities in the Block Protocol are described by JSON schema, and we encourage these to be mapped to terms which can be used to construct a JSON-LD representation of the entity, which embedding applications can include in the page's markup.

No, and for the most part the Block Protocol itself does not define the structure of entities passed between blocks and applications. Instead it specifies how entities should be defined, transmitted and updated.

The Block Protocol specifies that JSON Schema should be used to describe the properties of an entity and expected types of property values - not what those properties should be.

You can use existing schema.org schemas, or can create new schemas through the Block Protocol website, once logged in. The schema creator on the Block Protocol website aims to make it easier for users to define the different types of data structures that their blocks will work with.

We don’t prescribe canonical types for any thing, but do recommend that users link their schemas and properties to schema.org types and properties where possible, to help in making the pages that use their schemas machine-readable. We have included a way of doing so in our schema editor. Mapping different schemas and their properties to one another is a process known as ‘crosswalking’.

schema.org defines a collection of schemas for use in making the data on web pages machine-readable.

The Block Protocol does not define the structure of entities passed between blocks and applications - it only specifies how they are transmitted and updated.

Implementers of the Block Protocol could use the structure of entities as defined by schema.org, if they wished (e.g. a block could be built to render or edit a schema.org Event).

We recommend that users link their schemas and their properties to schema.org types and properties where possible, and have included a way of doing so in our schema editor.

A semantic type system is central to our vision for the Block Protocol.

We don’t believe that a single set of schemas provided by any one standards organization (even Schema.org) can ever perfectly fit all use cases, and as such the ability to create new schemas is important. When doing this, we want to make them as accessible to machines (and people) as possible.

schema.org provides a great base ontology for defining lots of types of ‘things’ out there in the world.

1. Many times, certain ‘properties’ or data won’t be relevant to your use case, resulting in bloated entity type definitions.
2. On other occasions you’ll want to store information differently than how it’s set out in the Schema.org definition. For example, schema.org/Person defines a person as having a givenName and a familyName and yet in various cultures this isn’t guaranteed. HASH uses preferredName and legalName instead - in communications and billing contexts respectively. You can view the HASH ‘Person’ schema at https://blockprotocol.org/@hash/types/Person and see how it crosswalks with the canonical definition of a person provided by Schema.org. This is just one example of how custom schemas can be made to relate back to the core ontology provided by Schema.org.
3. The Schema.org ontology is slow to change. This is by design, similar to how most standards organizations operate. And while it can move fast when clear universal impetus exists (evidenced by its excellent response to COVID) it ultimately represents a pseudo-centralized model of maintaining a schema registry. The Block Protocol provides the permissionless ability to build atop and extend Schema.org, unbounded by the processing constraints and imagination of any single working group or organization.
4. Not everything is included in the Schema.org ontology. For example, although animal shelters and pet stores exist, animals and pets themselves are missing entirely. This arguably reflects the priorities of schema.org’s maintainers (notably corporates, and search engines at that).

Moving beyond a single set of constrained schemas that rarely change introduces a number of issues. However, we believe that all of these can be mitigated and that the benefits of an open ecosystem of well-described, discoverable, and end-user definable types greatly outweigh any potential drawbacks.

1. Reusability of types: the type system supports a high degree of composability, with data types and property types indvidually definable and addressable from within different entity types and contexts.
2. Convergence on types: the type editors developed by HASH as part of their ontology manager include functionality to encourage users — where possible — to utilize and extend, or otherwise crosswalk, to existing types. These best-practice editors are open-source and are free to use within any other embedding application that builds upon the Block Protocol. We will be replacing the schema designer found within the Hub with these new type editors shortly.
3. Machine-resolvable relationships between types: we are planning to introduce an improved ability for types to declare themselves to be structurally or literally the same as other types, as well as conceptually the same.

JSON Schema has a rich vocabulary for validating data. We designed the Block Protocol with content management systems and collaborative workspaces in mind, and being able to define precise constraints for data is important for those applications.

We expect to have to add custom keywords to cover relationships which JSON Schema does not have in its core vocabulary (e.g. that a property is inverseOf another), but believe it will be easiest to start with JSON Schema and add keywords, rather than start with another vocabulary and add the required validation to it.

We encourage applications to include JSON-LD describing entities on their public pages to make them machine-readable.

In theory, the Block Protocol could use JSON-LD as the format in which entities are passed between applications and blocks. We did not pursue this because we believe it will be easier and more scalable to handle links between entities outside the JSON for the entity itself, as described here. We have also taken a different approach to identifying entities, which may not have a public URI and may require a combination of fields to identify.

GraphQL provides a “syntax and system for describing [application] data requirements and interactions”, whereas the Block Protocol is specifying a particular set of interactions: those between a block and any application embedding it.

It would be possible to define the operations specified in the Block Protocol in GraphQL - e.g. createEntity - or to extend the GraphQL spec to include them.

We do not yet believe it necessary to specify block-application requests in GraphQL syntax nor require that they be executed by the embedding application according to the GraphQL specification, although we are open to the idea. It may become more attractive as operations evolve to include more features already covered by GraphQL (e.g. subscriptions, selection sets).