Metadata

This section details the metadata fields in blocklet.yml. These fields define your Blocklet's core identity, descriptive information, and associated links. Properly configured metadata is essential for discoverability and presentation in environments like the Blocklet Server dashboard and the Blocklet Store.

For a high-level overview of the blocklet.yml file, please see the Overview documentation.

Core Identity#

Every Blocklet requires a unique identity, established through a combination of its name, decentralized identifier (DID), and version. These fields are fundamental for the Blocklet Server to manage and differentiate between Blocklets.

The Blocklet's did is deterministically generated from its name. The following diagram illustrates this relationship:

Field	Type	Description	Required
did	string	The Blocklet's Decentralized Identifier (DID). It must be a valid DID and correspond to the name field.	Yes
name	string	The blocklet's unique, human-readable identifier. It is used to generate the did and must follow specific naming conventions (e.g., no special characters, kebab-case).	Yes
version	string	The semantic version number of the Blocklet (e.g., 1.2.3).	Yes
specVersion	string	The version of the Blocklet Specification this file adheres to. Should be a semantic version >='1.0.0'.	No

Example:

Descriptive Information#

These fields provide the primary content used to describe your Blocklet in user interfaces.

Field	Type	Description	Required
title	string	A short, descriptive title for the Blocklet. It has a maximum length of 120 characters.	Yes
description	string	A brief summary of the Blocklet's purpose and functionality. It must be between 3 and 160 characters.	Yes
logo	string	A relative path or a public URL to the Blocklet's logo image.	No
group	string	The category the Blocklet belongs to. Valid options include dapp, static, service, component, contract, library.	No

Example:

People & Ownership#

This group of fields credits the individuals and entities behind the Blocklet and provides copyright information.

The author, contributors, and maintainers fields all use a Person object with the following structure:

Key	Type	Description	Required
name	string	The person's full name.	Yes
email	string	The person's email address.	No
url	string	A URL to the person's website or profile.	No

Field	Type	Description	Required
author	Person	The primary author of the Blocklet.	No
contributors	Person[]	An array of people who have contributed to the Blocklet.	No
maintainers	Person[]	An array of people who currently maintain the Blocklet.	No
copyright	object	Copyright information, with owner (string) and year (string/number) keys.	No

Example:

Associated Links#

Provide links to external resources where users can find more information, get help, or engage with the community.

Field	Type	Description	Required
homepage	string	The URL of the Blocklet's official homepage.	No
documentation	string	The URL of the Blocklet's documentation.	No
community	string	The URL of the community forum, chat, or discussion group.	No
support	string	A support URL or email address.	No
license	string	The license under which the Blocklet is distributed (e.g., 'MIT', 'GPL-3.0-or-later').	No

Example:

Categorization & Keywords#

Help users find your Blocklet by providing relevant keywords and tags.

Field	Type	Description	Required
keywords	string[]	An array of keywords that describe the Blocklet's functionality.	No
tags	string[]	An array of tags for filtering and categorization, often used interchangeably with keywords.	No

Example:

With the metadata defined, the next step is to configure how your Blocklet runs. Proceed to the Execution section to learn about defining the runtime engine, lifecycle scripts, and environment variables.