Skip to main content

4. Register collection metadata schema

Asset metadata and how it's used

Assets belonging to a collection (tokens that have been minted from a smart contract) can contain metadata that specify attributes about the asset. The aim of metadata is to allow applications to utilize this data.

Examples of how games or applications can use asset metadata:

  • An in-game asset has characteristics that allow its owner to wield certain advantages within the game, like being able to defeat opponents whose assets have lesser characteristics. The game needs to be able to read the attributes of the asset in order to execute the game mechanics accordingly.
  • An NFT marketplace will want to display attributes of an asset that is for sale, like the asset's name, rarity, image (using the URL specified in the asset's metadata), etc.

Metadata is most commonly in JSON format.

Example metadata:

{
"name": "Rufus",
"animation_url": "https://guildofguardians.mypinata.cloud/ipfs/QmQDee8BPDfAH2ykRX375AWJwYZcbbJQa8wHokrSnMLLUC/HLS/Base/CollectionAsset_Hero_Rufus_Base.m3u8",
"animation_url_mime_type": "application/vnd.apple.mpegurl",
"image_url": "https://gog-art-assets.s3-ap-southeast-2.amazonaws.com/Content/Thumbnails/Heroes/Rufus/Thumbnail_Hero_Rufus_Base.png",
"attack": 4,
"collectable": true,
"god": "Ranged",
"element": "Water",
"product": 2,
"rarity": 2,
"type": 3
}

Metadata standardization

One of the most common uses of metadata is for NFT marketplaces to display characteristics of an asset. Many marketplaces have certain formats in which they read metadata from assets. There are also wallets and other NFT tooling that have their own formats. This is something that you must consider when setting your asset's metadata.

The Immutable Marketplace uses the following core properties:

PropertyDescriptionMandatory
nameThe display name for this asset.No
descriptionThe description of this asset.No
image_urlThe URL of the display image for this asset. This will be used as a video thumbnail in the Immutable Marketplace.No
imageAlternative field of image_url.No
animation_urlA URL to a multi-media attachment for the item. We highly recommend the use of the HLS format for streaming video over HTTP. This is generally used for video NFTs.

Applications are required to host their own video assets and expose their location via this URL.
No
animation_url_mime_typeMime type of the file that animation_url points to. Immutable currently only supports these 3 mime types: application/vnd.apple.mpegurl, video/mp4 and video/webm.No, unless animation_url is specified.
youtube_urlA URL to a YouTube video. This playback method is currently not supported in the Immutable Marketplace, but third party support could be built.No

Metadata schema

The metadata schema outlines the names of the metadata object properties and the values that are acceptable for each property.

When registering the metadata schema for an Immutable collection, you can assign the following value types for each property:

TypeDescriptionFilterable?
enumProperty with a defined enumeration of possible values (e.g. god = "nature" or "death").Yes
textProperty which contains arbitrary text. Should be searchable.No
booleanProperty which can be either true or false.Yes
discreteProperty which will usually be handled as a multi-select, e.g. values from 1-10Yes

Additionally, a filterable attribute can be specified for each property in the metadata schema, which allows API consumers to filter assets that are returned by these values. Filterable cannot be true for text parameter types.

Example metadata schema for the metadata example above:

{
"metadata": [
{
"name": "name",
"type": "text"
},
{
"name": "attack",
"type": "discrete",
"filterable": true
},
{
"name": "collectable",
"type": "boolean",
"filterable": true
},
{
"name": "god",
"type": "enum",
"filterable": true
},
{
"name": "element",
"type": "enum",
"filterable": true
},
{
"name": "product",
"type": "discrete",
"filterable": true
},
{
"name": "type",
"type": "discrete",
"filterable": true
}
]
}

Steps:

  1. Create the metadata schema
  2. Add metadata schema to a collection
  3. Update metadata schema

1. Create the metadata schema

Only the project owner can add the metadata schema to a collection.

Each property of the metadata schema contains the following fields:

FieldRequired?Type
nameYesText
typeNo (default is text)See values types in this table
filterableNo (default is false)Boolean

If set to true, then the particular metadata's name will show up in the filters that are used by marketplaces and other applications

See example metadata schema.

2. Add metadata schema to a collection

Follow the 4. Add metadata schema to your collection steps in the imx-examples repository.

Note:

  • When specifying an enum type, you do not have to provide values. This is automatically generated based on the values in the metadata.
  • When specifying the discrete type, a range is automatically generated based on the values provided in the metadata.

3. Update metadata schema

To add missing attributes to your collection's metadata schema that were not submitted in the original request, follow these instructions. Just add the missing attributes and they will be appended.

Submitting the same metadata schema attribute will result in the error:

{
"code": "metadata_key_already_exists",
"message": "Metadata key(s) already exist"
}

Note:

  • You can update the type and filterable attributes of a metadata schema property
  • Updating the filterable attribute of a metadata schema property to true is an expensive API call as it triggers a re-scan of all the assets in the collection to get up-to-date filter values

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us