Working With Types

Introduction

When using the Block Protocol's graph module, data is shared between applications and blocks in the form of 'entities', and each entity has a type, known as an 'entity type'.

This type describes what properties an entity has, what type of value each is expected to be, and the relationship between the entity in question and other entities.

Relationships between entities are known as 'links' and they too are entities, which means they may have properties and relations to other entities.

The system by which types are defined is known as the 'type system'.

The type system

The Block Protocol type system is designed so that types are composed of re-usable, sharable parts, which can be referenced by other users and by other types.

The type system consists of three classes of elements:

  1. Entity types: define what properties an entity may have (which property types), and what relationships (links) it may have with other entities
  2. Property types: define properties that can be referenced by entity types, and their expected values, which may be a reference to data types or objects which are made up of other property types
  3. Data types: primitive data types, e.g. text, numbers, booleans.

Creating types

The easiest way to get started is to visit your dashboard and click 'create an entity type'.

Give your entity type a name and a description, and then click 'create'.

You can now define the properties your entity expects:

  1. Start typing to see if a suitable property already exists (e.g. called 'Name' with an expected data type of 'Text')
  2. Either select an existing property type, or click 'create new' to create a new one
  3. If creating a new one, specify a title, description, and expected value

A basic entity type with a Name property

You can also define the links your entity expects following a similar process:

  1. Start typing to see if a suitable link entity type already exists (e.g. called 'Owner')
  2. Either select an existing link entity type, or click 'create new' to create a new one
  3. When creating a link entity type, you first specify a title and description
  4. Back on your initial entity type, you can select the link entity type as a potential link from your entity, and then constrain the destination entities of those links by defining a selection of entity types. You can also set a minimum number of such links (e.g. to make it so that entities of your type are required to have certain links).

Make sure to click 'publish update' when you're done to release a new version of the entity type.

Using types

Once you have a type which describes the data your block expects, copy the URL from your browser.

You can enter this as the value for schema in the blockprotocol object of your block source's package.json, and run yarn schema to automatically generate TypeScript types from it.

You can also view the raw JSON of any type by a simple fetch or curl:

fetch("https://blockprotocol.org/@blockprotocol/types/entity-type/thing/v/2")
  .then((resp) => resp.json())
  .then(console.log);

curl https://blockprotocol.org/@blockprotocol/types/entity-type/thing/v/2

Previous

Developing Blocks

Next

Using Blocks