# Metadata

Metadata elements are custom, client provided key / value pairs that can be forwarded to application instances (e.g. a game server). The main purpose of this is for a Matchmaker to provide game server configuration values to be sent to a game server upon allocation of said game server.

In our system, Metadata elements are part of [ApplicationInstance](/game-hosting/elements/application/applicationinstance.md) elements.

See the chapter about the [matchmaker allocation process](/game-hosting/game-integration/matchmaker-allocation.md) for more information.

## Structure

| Property | Value type | Required | Description                     |
| -------- | ---------- | -------- | ------------------------------- |
| key      | string     | Yes      | The name of the metadata entry  |
| value    | string     | Yes      | The value of the metadata entry |

Table 1: Metadata element structure

## Requirements

A Metadata element has the following constraints:

* allowed characters in the key are a-z 0-9 \_ -
* the key may be no longer than 50 characters
* the value may be no longer than 150 characters

## Manually adding & updating ApplicationInstance metadata

Metadata in the ApplicationInstance elements are stored as an array of Metadata elements:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "metadata": [
    {
      "key": "metadata1",
      "value": "A value"
    },
    {
      "key": "metadata2",
      "value": "Another value"
    }
  ]
}
```

Figure 1: Example metadata for an ApplicationInstance element

When you want to add a new metadata element, you can PUT an element with only that new metadata element. You would submit:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "metadata": [
    {
      "key": "metadata3",
      "value": "A new value"
    }
  ]
}
```

Figure 2: Example of adding new metadata to an ApplicationInstance element

The result will be that the element has 3 metadata elements: `metadata1`, `metadata2` and `metadata3`.

When you want to update metadata, you only have to submit that one metadata element:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "metadata": [
    {
      "key": "metadata2",
      "value": "An updated value"
    }
  ]
}
```

Figure 3: Example of updating an existing metadata element in an ApplicationInstance element

Deleting metadata is done by submitting metadata with a null value:

`PUT /applicationInstance/{applicationInstanceId}`

```
{
  "metadata": [
    {
      "key": "metadata2",
      "value": null
    }
  ]
}
```

Figure 4: Example of deleting metadata from an ApplicationInstance element

After these example mutations, the element ends up with the following metadata:

`GET /applicationInstance/{applicationInstanceId}`

```
{
  "metadata": [
    {
      "key": "metadata1",
      "value": "A value"
    },
    {
      "key": "metadata3",
      "value": "A new value"
    }
  ]
}
```

Figure 5: The resulting metadata for an ApplicationInstance element after applying the examples

## Adding metadata during ApplicationInstance allocation

During an [allocation call](/game-hosting/game-integration/matchmaker-allocation.md) ([API reference](https://www.i3d.net/docs/api/v3/game-publisher#/ApplicationInstance/updateApplicationInstanceGameEmptyAllocate)), you can pass a metadata array. This metadata will then be added to all the ApplicationInstances that are allocated during that request.

`PUT /applicationInstance/game/{applicationId}/empty/allocate`

```
{
  "metadata": [
    {
      "key": "metadata1",
      "value": "E.g. a map name"
    },
    {
      "key": "metadata2",
      "value": "E.g. game duration"
    }
  ]
}
```

Figure 6: Example of passing metadata to ApplicationInstances being allocated

Metadata sent during an allocation request will be merged with the metadata of the ApplicationInstances that are allocated. Merging occurs in the same manner as [manually updating metadata](#manually-adding-updating-applicationinstance-metadata).


---

# 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://docs.i3d.net/game-hosting/elements/application/metadata.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.