Core Metadata
Core metadata fields are the fundamental properties that uniquely identify and describe a blocklet. These fields are essential for blocklet registries, development tools, and the ABT Node runtime to manage, display, and execute the blocklet correctly. This section covers the primary identifiers such as did, name, version, and descriptive fields like title, description, and group.
Key Fields#
did#
The did is the blocklet's globally unique, immutable Decentralized Identifier. It serves as its primary key within the Blocklet ecosystem.
Property | Description |
|---|---|
Type |
|
Required | Yes |
Constraints | Must be a valid DID. The DID's type information must specify |
Validation Logic
The system validates that the provided DID is not only structurally correct but also has the correct role type encoded within it, as enforced by the validateNewDid function.
// From src/name.ts
export const validateNewDid = (did: string): void => {
const typeInfo = toTypeInfo(did);
if (typeInfo.role !== types.RoleType.ROLE_BLOCKLET) {
throw new Error("Blocklet DID's type must be ROLE_BLOCKLET");
}
};Example
did: 'z8iZpA84cSmWdcjBf2f2sb9n5zWg62TNK6C1b'version#
This field specifies the version of the blocklet, allowing for proper dependency management and version control.
Property | Description |
|---|---|
Type |
|
Required | Yes |
Constraints | Must be a valid Semantic Versioning (SemVer) string. |
Example
version: '1.2.3'name#
The name is a human-readable identifier. In modern blocklets, the did is the primary identifier. However, the name is still used, especially for backward compatibility with older blocklets where the did was derived from the name.
Property | Description |
|---|---|
Type |
|
Required | Yes (unless a valid |
Constraints | If not a DID, must be a valid npm-package-name and not exceed 32 characters. If the |
Validation Logic
The validation process checks if the name is a valid DID. If not, it falls back to npm package name validation rules. Crucially, it ensures consistency between the name and did if the legacy naming scheme is used.
// Simplified logic from createBlockletSchema
// ...
if (name) {
validateName(name, { checkDid: !skipValidateDidName });
const expectDid = toBlockletDid(name);
if (expectDid !== did) {
// @ts-ignore
return helper.message(`The did of name "${name}" should be "${expectDid}"`);
}
}
// ...Example
name: 'my-first-blocklet'
# The DID below would be derived from the name
did: 'z8ia1mZ433Tj9iYfGeVyB39tU51f58a5jEa5X'description#
A brief, plain-text summary of what the blocklet does.
Property | Description |
|---|---|
Type |
|
Required | Yes |
Constraints | Must be between 3 and 160 characters. |
Example
description: 'A blocklet that demonstrates core metadata configuration.'title#
A user-friendly display name for the blocklet, used in user interfaces like the Blocklet Store and launcher.
Property | Description |
|---|---|
Type |
|
Required | No |
Constraints | The display length, accounting for CJK characters, must not exceed |
Example
title: 'My First Blocklet'group#
Categorizes the blocklet's primary function. This helps users understand its purpose at a glance.
Property | Description |
|---|---|
Type |
|
Required | No |
Constraints | Must be one of the following values: |
Example
group: 'dapp'specVersion#
Indicates the version of the blocklet.yml specification that this metadata file adheres to.
Property | Description |
|---|---|
Type |
|
Required | No |
Constraints | Must be a valid SemVer string greater than or equal to |
Example
specVersion: '1.1.0'Complete Example#
Here is an example of a blocklet.yml file with all the core metadata fields correctly configured.
# Unique identifier for the blocklet
did: 'z8iZpA84cSmWdcjBf2f2sb9n5zWg62TNK6C1b'
# Human-readable name, must be consistent with the DID
name: 'my-awesome-blocklet'
# Version of the blocklet
version: '1.0.0'
# User-friendly display title
title: 'My Awesome Blocklet'
# A concise description of the blocklet's function
description: 'This blocklet serves as a comprehensive example of core metadata fields.'
# The primary category of the blocklet
group: 'dapp'
# The blocklet.yml specification version this file follows
specVersion: '1.2.0'With these core fields correctly defined, you have established the fundamental identity of your blocklet. The next step is to define who created and maintains it. Continue to the People & Ownership section to learn more.