Publication metadata
Lens Protocol Publication Metadata v3
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:
article(input): ArticleMetadata
audio(input): AudioMetadata
checkingIn(input): CheckingInMetadata
embed(input): EmbedMetadata
event(input): EventMetadata
image(input): ImageMetadata
link(input): LinkMetadata
liveStream(input): LiveStreamMetadata
mint(input): MintMetadata
space(input): SpaceMetadata
story(input): StoryMetadata
textOnly(input): TextOnlyMetadata
threeD(input): ThreeDMetadata
transaction(input): TransactionMetadata
video(input): VideoMetadata
shortVideo(input): VideoMetadata
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.
- Article v3
- Audio v3
- CheckingIn v3
- Embed v3
- Event v3
- Image v3
- Link v3
- LiveStream v3
- Mint v3
- Space v3
- Story v3
- TextOnly v3
- 3d v3
- Transaction v3
- Video v3
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
Updated 2 days ago