asset-metadata.mdx

title	slug	sidebar_position
Asset Metadata	/asset-metadata	2

Immutable X allows for projects to specify metadata properties for their assets. These properties allow marketplaces to perform complex filtering queries to help users discover what they want more effectively. :::success Refresh metadata You can contact support to refresh metadata changes that you've made. You will need to identify the tokens that need to be re-crawled, and the updates that have been made to them.\n\nWe aim to process requests within 2 business days (AEST) but this can take longer depending on demand. :::

Core properties

There are several core properties

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 X 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 NFT.	no
animation_url_mime_type	Mime type of the file that animation_url points to. Imx only supports these 3 mime types currently: application/vnd.apple.mpegurl, video/mp4, video/webm	yes* NOTE: When animation_url is specified, this field is mandatory. Otherwise this field is optional like the others.
youtube_url	A URL to a YouTube video. This playback method is currently not supported in the Immutable X Marketplace, but third party support could be built.	no

The above core properties usually don't need to be mapped to a type if you don't want to do filtering on them.

Partners will be required to host their own video assets and exposing their location via the animation_url.

For video NFTs, the individual marketplace can determine whether to loop video, support autoplay, or mute on initial load. The protocol does not define how it should be played in a given marketplace.

Property type mapping

The following is the source of truth specification for how metadata filters function in Immutable X. Metadata filters let API consumers filter returned NFTs by their metadata properties. These filters are applied to a bunch of endpoints.

In the event where the NFT has a metadata key that does not exist yet in our database, that new key and values will be added into our database.

In our database, metadata properties are stored with one of the following types:

Type	Description
enum	Property with a defined enumeration of possible values (e.g. god = nature or death).
text	Property which contains arbitrary text. Should be searchable. Not filterable.
boolean	Property which can be either true or false.
discrete	Property which will usually be handled as a multi-select e.g. mana.

Example mapping in our database

key	data_type	filterable
attack	discrete	true
god	enum	true
health	discrete	false
mana	discrete	false
name	text	false
quality	enum	true
rarity	enum	true
set	enum	true
type	enum	true

Filterable

The filterable parameter is a boolean condition that signals to the marketplace that the metadata attribute should be something the end user can filter assets with. All metadata attributes can still be text-searched but the marketplace could implement specific filters in the marketplace UI tailored to the particular collection.

Please note, the "filterable" parameter can only be true for non-text parameter types.

Filters are only generated for properties at the top-level of the JSON metadata object.

Example metadata

{
  // core fields:
  "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",

  // Add more (non core) properties as long as it's a flat key/value structure 
  // and these values match the schema that the contract was registered with
  "attack": 4,
  "collectable": true,
  "god": "Ranged",
  "element": "Water",
  "product": 2,
  "rarity": 2,
  "type": 3,
}

Example metadata schema

Please note:

• The "filterable" parameter can only be true for non-text parameter types.
• We don't need you to provide us the values for an enum type. We auto-generate the list of values based on what is passed to us through your metadata endpoint
• We don't need the range of values for a discrete type. We auto-generate the range based on the provided list of values

{
    "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
        }
    ]
}