Publication metadata

The metadata standards for Lens publications can be logically split into 2:

Primary publications metadata - describes content and operational informations such as originating app, language, etc.
Mirror metadata - describe operational aspects of a Mirror that are in support of the on-chain informations.

Primary publications metadata

By "primary publication" we mean Lens publications holding the actual content: Posts, Comments, and Quotes.

The the Publication Metadata Standard is a collection of several standards.

The intent is to give builders a tool to capture the user's original intent so that, when the same publication surfaces on other part of the Lens ecosystem, such intent is carried over in those user experiences.

The standard currently covers the following type of publications:

3D - a 3D digital asset
Article - for blog article, news, medium-alike
Audio - for publication where audio file(s) is the main focus
Checking In - to notify your community of your presence in a given plae
Embed - to share embeddable resources such as games, mini-apps
Event - for events, physical or virtual
Image - for publications where image(s) is the main focus
Link - for sharing a link
LiveStream - for planning a Live Stream event
Mint - for sharing a link to mint an NFT
Space - for planning a social space
Story - for sharing an audio, image, or video in an Instagram-like fashion
Text Only - for purely textual publications (e.g. most comments)
Transaction - for sharing an interesting on-chain transaction
Video - for publications where video(s) is the main focus

Build compliant metadata objects

The @lens-protocol/metadata offers a set of helpers that help you create metadata for the aforementioned publication types. They are in the shape of TS/JS helper functions.

With these helpers creating a compliant metadata object is as simples as:

import { image, MediaImageMimeType } from '@lens-protocol/metadata';

const metadata = image({
  image: {
    item: "ipfs://...",
    type: MediaImageMimeType.JPEG
  }
});

Or for a comment-like metadata

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

const metadata = textOnly({
  content: "GM!"
});

See reference docs for details and examples:

Parse and validate

You can parse any publication metadata object via the bespoke Zod PublicationMetadataSchema:

import { PublicationMetadataSchema, PublicationMetadata } 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 }

Once parsed you can use the type-safe PublicationMetadata, a discriminated union of all publication metadata types.

The @lens-protocol/metadata package includes useful types to navigate the parsed data structure. See a non-comprehensive list below:

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

JSON Schemas describing compliant JSON for each of the publication types mentioned above are also available from the @lens-protocol/metadata package.

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

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

The JSON Schemas are also published under their respective Schema ID URIs.

Although not meant for direct consumption, you can see a list of all metadata schemas in the repository: https://github.com/lens-protocol/metadata/tree/main/jsonschemas/publications

In due course these JSON Schemas will also be hosted and served from a static location for long term usage.

Mirror metadata

Mirror metadata is a recent addition to the Lens standards. To not be confused with Quote, the Mirror metadata is meant to include operational details in support of the mirror publication once indexed.

The Mirror metadata JSON file can be referenced at the time of creating a Mirror via the metadataURI property.

At this point in time it's only possible to optionally describe the app originating a given Mirror. You can do that with the mirror helper as follows:

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

const metadata = mirror({
  appId: "my-app-id"
});

See reference documentation here.

Although this is mostly something that the Lens API Indexer takes care of, you can parse Mirror metadata object via the bespoke Zod MirrorMetadataSchema:

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

MirrorMetadataSchema.parse(valid); // => MirrorMetadata
MirrorMetadataSchema.parse(invalid); // => throws ZodError

// OR

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

The JSON Schema for Mirror metadata is also available under:

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

or under its Schema ID URI: Mirror v1

For reference only under: https://github.com/lens-protocol/metadata/tree/main/jsonschemas/publications/mirror