Parsing & Validation
This section covers the core functions for reading, parsing, and validating blocklet.yml files. These utilities are the primary entry point for working with blocklet metadata, ensuring that the data is well-formed, complete, and conforms to the official specification before being used by other parts of the system. For a detailed reference on all available fields, please see the Blocklet Specification (blocklet.yml).
parse#
The parse function is the most common and comprehensive utility for loading blocklet metadata. It reads the blocklet.yml (or blocklet.json) file from a specified directory, applies a series of automatic fixes and normalizations, and validates the final object against the blocklet schema.
Process Flow#
The function follows a multi-step process to ensure robust and consistent metadata:
Parameters#
Name | Type | Description |
|---|---|---|
|
| Required. The root directory of the blocklet project containing the |
|
| Optional. An object containing configuration options. |
|
| If |
|
| If |
|
| If |
|
| An object with additional attributes to merge into the metadata before fixing and validation. Useful for registries to inject data. Defaults to |
|
| A URL to be used as the default |
|
| If |
Returns#
A fully validated and normalized TBlockletMeta object. If parsing, fixing, or validation fails, the function throws an Error with a descriptive message.
Example#
import path from 'path';
import { parse } from '@blocklet/meta';
const blockletDir = path.join(__dirname, 'my-blocklet-project');
try {
const meta = parse(blockletDir, { ensureFiles: true });
console.log('Successfully parsed blocklet meta for:', meta.title);
console.log('Version:', meta.version);
} catch (error) {
console.error('Failed to parse blocklet.yml:', error.message);
}validateMeta#
Use validateMeta when you already have a blocklet metadata object in memory (e.g., from an API response or programmatically constructed) and need to validate it against the blocklet schema.
Parameters#
Name | Type | Description |
|---|---|---|
|
| Required. The blocklet metadata object to be validated. |
|
| Optional. An object containing configuration options for validation. |
|
| See |
|
| See |
|
| See |
|
| If |
|
| If |
Returns#
A validated TBlockletMeta object. Throws an Error if the object is invalid.
Example#
import { validateMeta } from '@blocklet/meta';
const myMeta = {
did: 'z8iZqD4F2j4a7b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q', // Must be a valid DID
name: 'z8iZqD4F2j4a7b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q',
version: '1.0.0',
title: 'My Custom Blocklet',
description: 'A programmatically created blocklet meta.',
main: 'dist',
};
try {
const validatedMeta = validateMeta(myMeta);
console.log('Meta is valid:', validatedMeta.title);
} catch (error) {
console.error('Meta validation failed:', error.message);
}fixAndValidateService#
This is a specialized utility for fixing and validating the service configurations within a blocklet's interfaces. It is called internally by parse but can be used standalone if you need to process service definitions separately.
Parameters#
Name | Type | Description |
|---|---|---|
|
| Required. A blocklet metadata object that may contain |
Returns#
The input TBlockletMeta object with its service configurations validated and potentially modified with defaults.
Example#
import { fixAndValidateService } from '@blocklet/meta';
const metaWithService = {
did: 'z8iZqD4F2j4a7b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q',
name: 'z8iZqD4F2j4a7b5c6d7e8f9g0h1i2j3k4l5m6n7o8p9q',
version: '1.0.0',
description: 'A blocklet with a service.',
main: 'dist',
interfaces: [
{
type: 'web',
name: 'publicUrl',
path: '/',
prefix: '*',
protocol: 'http',
services: [
{
name: '@abtnode/auth-service',
config: {
whoCanAccess: 'all',
profileFields: ['fullName', 'email']
}
}
]
}
]
};
try {
const fixedMeta = fixAndValidateService(metaWithService);
console.log('Service config validated:', fixedMeta.interfaces[0].services[0].config);
} catch (error) {
console.error('Service validation failed:', error);
}Automatic Fixes#
The parse function (when fix: true) automatically normalizes several fields to reduce boilerplate and ensure consistency. Key fixes include:
fixRequired: Adds a defaultdescriptionandversion(0.1.0) if they are missing.fixRepository: Converts a stringrepositoryURL into a structured object{ type: 'git', url: '...' }and normalizes the URL.fixPerson: Parses string-basedauthor,contributors, andmaintainers(e.g.,'John Doe <john@example.com> (https://example.com)') into structured objects ({ name, email, url }).fixKeywords/fixTags: Converts a comma-separated string of keywords or tags into an array of strings.fixName: If thedidis valid, it setsnameto the same value asdid.fixInterfaces: Standardizes interface properties, ensuring web interfaces use thehttpprotocol and providing sensible defaults.
Now that you understand how to parse and validate local metadata, continue to the Metadata Helpers section to learn about fetching metadata from remote sources.