# 4. Register collection metadata schema

## 4. Register collection metadata schema

💡INFO

* <mark style="color:blue;">Asset metadata and how it's used</mark>
* <mark style="color:blue;">Metadata schema</mark>
* <mark style="color:blue;">How to register a collection's metadata schema</mark>

### Asset metadata and how it's used[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#asset-metadata-and-how-its-used) <a href="#asset-metadata-and-how-its-used" id="asset-metadata-and-how-its-used"></a>

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:**[**​**](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#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:**[**​**](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#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[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#metadata-standardization) <a href="#metadata-standardization" id="metadata-standardization"></a>

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 XpansionChain <mark style="color:blue;">Marketplace</mark> uses the following 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 XpansionChain  Marketplace.                                                                                                                                                             | No                                       |
| `image`                   | Alternative field of `image_url`.                                                                                                                                                                                                                                                  | No                                       |
| `animation_url`           | <p>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.<br><br>Applications are required to host their own video assets and expose their location via this URL.</p> | No                                       |
| `animation_url_mime_type` | Mime type of the file that `animation_url` points to. XpansionChain 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 XpansionChain Marketplace, but third party support could be built.                                                                                                                                | No                                       |

### Metadata schema[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#metadata-schema) <a href="#metadata-schema" id="metadata-schema"></a>

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 XpansionChain 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&#x20;**<mark style="color:blue;">**metadata example**</mark>**&#x20;above:**[**​**](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#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
    }
  ]
}
```

🤚PRE-REQUISITES

* <mark style="color:blue;">Registering as a user</mark>
* <mark style="color:blue;">Registering a project</mark>
* <mark style="color:blue;">Registering a collection</mark>

#### Steps:​ <a href="#steps" id="steps"></a>

1. <mark style="color:blue;">Create the metadata schema</mark>
2. <mark style="color:blue;">Add metadata schema to a collection</mark>
3. <mark style="color:blue;">Update metadata schema</mark>

### 1. Create the metadata schema[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#1-create-the-metadata-schema) <a href="#id-1-create-the-metadata-schema" id="id-1-create-the-metadata-schema"></a>

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 <mark style="color:blue;">this table</mark>                                                                                            |
| `filterable` | No (default is `false`) | <p>Boolean<br><br>If set to true, then the particular metadata's name will show up in the filters that are used by marketplaces and other applications</p> |

See <mark style="color:blue;">example metadata schema</mark>.

### 2. Add metadata schema to a collection[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#2-add-metadata-schema-to-a-collection) <a href="#id-2-add-metadata-schema-to-a-collection" id="id-2-add-metadata-schema-to-a-collection"></a>

Follow the <mark style="color:blue;">4. Add metadata schema to your collection</mark> steps in the imx-examples repository.

#### Note:[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#note) <a href="#note" id="note"></a>

* 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[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#3-update-metadata-schema) <a href="#id-3-update-metadata-schema" id="id-3-update-metadata-schema"></a>

To add missing attributes to your collection's metadata schema that were not submitted in the original request, follow <mark style="color:blue;">these instructions</mark>. 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:[​](https://docs.x.immutable.com/docs/x/launch-collection/register-metadata-schema#note-1) <a href="#note-1" id="note-1"></a>

* 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xpansionchain-1.gitbook.io/xpansionchain/launch-a-collection/4.-register-collection-metadata-schema.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.