Asset Metadata

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.

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.

continuous

Property which will be usually handled as a range e.g. height.

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

proto

continuous

true

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": "rarity",
            "type": "continuous",
            "filterable": true
        },
        {
            "name": "type",
            "type": "discrete",
            "filterable": true
        }
    ]
}

Did this page help you?