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.
This section is 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.
When publishing the block protocol, we will provide tooling to help validate block type compliance with the block protocol. We may wish to dictate that blocks meet certain standards before they are made available via the Block Hub.
This protocol specifies an interface between blocks and embedding applications, defining how data is referred to when it is communicated between the two, but leaves open:
the particular implementation and composition of block source code
how exactly data is transferred between an application and a block
how exactly blocks are rendered (and re-rendered) by applications
There are various different implementations of embedding applications and blocks which would be compliant with the protocol but not with one another.
Embedding applications can maximise the number of blocks they can render by implementing a number of rendering strategies, which are then chosen depending on the detected or reported block implementation.
Some common web rendering strategies are discussed briefly below.
React lends itself well to block authoring and embedding, given its principles of composable, reusable components.
A block authored in React should express its schema in line with the props of its entrypoint component, e.g.
Block authors should expect the required properties expressed in their schema passed into the component as props, alongside (possibly) the special block protocol functions, and (possibly) any properties not marked as required.
Blocks authored in React should specify React as an external library, i.e. do not bundle React with their package, as the embedding application can provide it as described above via a special
requires, saving on bundle size.
A plain HTML block – i.e. a block that has a HTML entry point, and does not rely on the embedding application running a particular web rendering framework/library – is a valid block.
If it has no data interface requirements, it need not be accompanied by a schema in its package.
Blocks written in templating languages can reference their expected data properties in the template. This offers a solution for versions of blocks authored for Ruby on Rails or Django web servers, for example.