Package Exports

@lens-protocol/metadata
@lens-protocol/metadata/dist/index.cjs
@lens-protocol/metadata/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@lens-protocol/metadata) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Lens Protocol Metadata Standards

Schema vaidation and TS types for LIP-2 Lens Protocol Metadata Standards.

Features

Zod schema definitions
JSON Schema definitions
TypeScript type definitions

Installation

# npm:
npm install @lens-protocol/metadata zod

# yarn:
yarn add @lens-protocol/metadata zod

# pnpm:
pnpm add @lens-protocol/metadata zod

[!NOTE]
zod is marked as optional peer dependency, so if you all you need is the JSON Schema definitions, you can install @lens-protocol/metadata without zod.

Usage

Assuming we have 2 JS objects:

const valid = {
  /** example of valid metadata **/
};
const invalid = {
  /** example of invalid metadata **/
};

Publication metadata

import { PublicationMetadataSchema } from '@lens-protocol/metadata';

PublicationMetadataSchema.parse(valid); // => PublicationMetadata
PublicationMetadataSchema.parse(invalid); // => throws ZodError

// OR

PublicationMetadataSchema.safeParse(valid);
// => { success: true, data: PublicationMetadata }
PublicationMetadataSchema.safeParse(invalid);
// => { success: false, error: ZodError }

Profile metadata

import { ProfileMetadataSchema } from '@lens-protocol/metadata';

ProfileMetadataSchema.parse(valid); // => ProfileMetadata
ProfileMetadataSchema.parse(invalid); // => throws ZodError

// OR

ProfileMetadataSchema.safeParse(valid);
// => { success: true, data: ProfileMetadata }
ProfileMetadataSchema.safeParse(invalid);
// => { success: false, error: ZodError }

Format validation error

ZodError contains all the information needed to inform you about the validation error, but it's not very user friendly. You can use formatZodError to get a more readable error message.

import { PublicationMetadataSchema, formatZodError } from '@lens-protocol/metadata';

const result = PublicationMetadataSchema.safeParse(invalid);

if (!result.success) {
  console.log(formatZodError(result.error));
}

Narrowing types

Every time you have a discriminated union, you can use the discriminant to narrow the type. See few examples below.

PublicationMetadata

import {
  PublicationMetadata,
  PublicationMetadataSchema,
  PublicationSchemaId,
} from '@lens-protocol/metadata';

const publicationMetadata = PublicationMetadataSchema.parse(valid);

switch (publicationMetadata.$schema) {
  case PublicationSchemaId.ARTICLE:
    // publicationMetadata is ArticleMetadata
    break;
  case PublicationSchemaId.AUDIO:
    // publicationMetadata is AudioMetadata
    break;
  case PublicationSchemaId.IMAGE:
    // publicationMetadata is ImageMetadata
    break;
  case PublicationSchemaId.TEXT_ONLY:
    // publicationMetadata is TextOnlyMetadata
    break;

  // ...
}

MetadataAttribute

import { MetadataAttribute, MetadataAttributeType } from '@lens-protocol/metadata';

switch (attribute.type) {
  case MetadataAttributeType.BOOLEAN:
    // attribute is BooleanAttribute
    // value is a string "true" or "false"
    break;
  case MetadataAttributeType.DATE:
    // attribute is DateAttribute
    // value is a string in ISO 8601 format
    break;
  case MetadataAttributeType.NUMBER:
    // attribute is NumberAttribute
    // value is a string containing a valid JS number
    break;
  case MetadataAttributeType.STRING:
    // attribute is StringAttribute
    // value is a string
    break;
  case MetadataAttributeType.JSON:
    // attribute is JSONAttribute
    // value is a string allegedly containing a valid JSON, consumers should validate it
    break;
}
```

### Useful types

The package also exports all enums and types that you might need to work with the metadata.

Use your IDE's autocomplete to explore the available types.

Some examples:

```typescript
import {
  // enums
  MediaAudioKind,
  MediaAudioMimeType,
  MediaImageMimeType,
  MediaVideoMimeType,
  MetadataAttributeType
  PublicationMainFocus,
  ThreeDFormat,

  // main types
  ArticleMetadata,
  AudioMetadata,
  CheckingInMetadata,
  EmbedMetadata,
  EventMetadata,
  ImageMetadata,
  LinkMetadata,
  LivestreamMetadata,
  MintMetadata,
  ProfileMetadata,
  PublicationMetadata,
  SpaceMetadata,
  StoryMetadata,
  TextOnlyMetadata,
  ThreeDMetadata,
  TransactionMetadata,
  VideoMetadata,

  // others
  MetadataAttribute,
  MediaAudio,
  MediaImage,
  MediaVideo,
  AnyMedia,
  GeoLocation,
  BooleanAttribute,
  DateAttribute,
  NumberAttribute,
  StringAttribute,
  JSONAttribute,

  // branded aliases
  Locale,
  Markdown,
  Signature,
  URI,
  AppId,
  Datetime,
} from '@lens-protocol/metadata';

JSON schemas

Importing JSON schema in TypeScript is a simple as:

import audio from '@lens-protocol/metadata/jsonschemas/publications/audio/1.0.0.json' assert { type: 'json' };

import audio from '@lens-protocol/metadata/jsonschemas/publications/article/1.0.0.json' assert { type: 'json' };

import embed from '@lens-protocol/metadata/jsonschemas/profile/1.0.0.json' assert { type: 'json' };

You can the use them in your JSON Schema validator of choice, for example ajv.

Contributing

To contribute to the Lens Protocol Metadata Standards, please fork this repository and submit a pull request with your changes.

To build the project, run:

pnpm build

Add changeset with:

pnpm changeset add

Use keepachangelog format for the changeset message.

Releasing

Release flow is managed by changesets.

To release a new version follow the steps below:

Create a new branch from main with the name release/<version>
Build the project

pnpm install && pnpm build

Update relevant package.json's versions and update CHANGELOG.md for each package:

pnpm changeset version

Review, commit and push the changes
Create a PR from release/<version> to main
Once approved, publish with (you need to be logged in to npm authorized to publish under @lens-protocol):

pnpm changeset publish

Push the tags

git push origin release/<version> --follow-tags

Merge the PR with a merge commit

License

Lens Protocol Metadata Standards is MIT licensed

Support

See the Lens API and SDK channel on our Discord