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.
Here is a list of commonly used properties in Marketplaces:
Property | Description | Mandatory |
---|---|---|
name | The display name for this asset. | No |
description | The description of this asset. | No |
image_url | The URL of the display image for this asset. This will be used as a video thumbnail in the Immutable Marketplace. | No |
image | Alternative field of image_url . | No |
animation_url | A 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_type | Mime 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_url | A 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:
Type | Description | Filterable? |
---|---|---|
enum | Property with a defined enumeration of possible values (e.g. god = "nature" or "death"). | Yes |
text | Property which contains arbitrary text. Should be searchable. | No |
boolean | Property which can be either true or false. | Yes |
discrete | Property which will usually be handled as a multi-select, e.g. values from 1-10 | Yes |
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
Only the project owner can add the metadata schema to a collection.
Each property of the metadata schema contains the following fields:
Field | Required? | Type |
---|---|---|
name | Yes | Text |
type | No (default is text ) | See values types in this table |
filterable | No (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 |
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