> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Specifying attributes with your tickets

> Learn how to attach player and ticket attributes to PlayFab matchmaking tickets so queue rules can evaluate skill, latency, and other criteria.

Rules determine which tickets are matched, based on the attributes specified by players. These attributes can be specified in two ways, either:

1. Within the create ticket request
2. In the player's entity

This tutorial describes how to specify those attributes.

## Specifying within the create ticket request

For rules configured with the attribute type "User", attributes are specified in
a `CreateMatchmakingTicket` request, alongside the player entity inside of an attributes `DataObject`.

```json theme={null}
POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "nestExample": {
                    "exp": 1500
                }
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "SkillRuleQueue"
}
```

Below is an example queue configuration with a `DifferenceRule`. This rule
contains an attribute path and source that will pick up the value 16.0,
specified by the `CreateMatchmakingTicket` request above.

```json theme={null}
"MatchmakingQueue": {
    "Name": "SkillRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 3,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "mu",
                "Source": "User"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}
```

<Note>
  Rules can navigate through the `DataObject` with a JSON Path. Replacing the Path field with "nestExample.exp" would cause the rule to use the value 1500 for the ticket created above.
</Note>

## Specifying through player entities

For rules with the attribute type "Player Entity", attributes are specified through a separate call to the `SetObjects` API.

This allows data to be stored for a user, rather than the title needing to specify it on each create ticket call.
This may make more sense for values that persist for a user, or that users cannot be trusted to submit. An example of this `SetObjects` call is shown below.

```json theme={null}
POST https://{{TitleID}}.playfabapi.com/Object/SetObjects
{
    "Objects": [
        {
            "ObjectName": "playerSkill",
            "DataObject": {
                "skillDetail": {
                    "mu": 16.0,
                    "sigma": 2.0
                }
            }
        }
    ],
    "Entity": {
        "Id": "A8140AB9109712B",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
```

A queue with the following configuration would retrieve the value 16.0 for use in its `DifferenceRule` rule, when a ticket is created with this player.

<Note>
  In the `Path` field, the first item after the root is the `ObjectName`, allowing you to choose which stored object to reference.
</Note>

```json theme={null}
"MatchmakingQueue": {
    "Name": "PlayerEntityRuleQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": false,
    "Rules": [
        {
            "Type": "DifferenceRule",
            "Difference": 1,
            "MergeFunction": "Average",
            "Attribute": {
                "Path": "$.playerSkill.skillDetail.mu",
                "Source": "PlayerEntity"
            },
            "AttributeNotSpecifiedBehavior": "MatchAny",
            "Weight": 1,
            "Name": "SkillRule",
            "SecondsUntilOptional": 10
        }
    ]
}
```

## Special formats

Most rules use attributes that are either strings or numeric, and are simply those values in JSON format. Rules that require more complex attributes to be passed in are listed below.

### Region Selection rule

A Region Selection rule requires an array of latency measurements with the specified schema. The following example is the expected attribute format for a region selection rule, shown alongside the two attributes used in the `CreateMatchmakingTicket` request example for comparison.

```json theme={null}
POST https://{{TitleId}}.playfabapi.com/Match/CreateMatchmakingTicket
{
    "Creator": {
        "Entity": {
            "Id": "A8140AB9109712B",
            "Type": "title_player_account",
            "TypeString": "title_player_account"
        },
        "Attributes": {
            "DataObject": {
                "mu": 16.0,
                "sigma": 1.8,
                "Latencies": [
                    {
                        "region": "EastUs",
                        "latency": 150
                    },
                    {
                        "region": "WestUs",
                        "latency": 400
                    }
                ]
            }
        }
    },
    "MembersToMatchWith": [],
    "GiveUpAfterSeconds": 2,
    "QueueName": "ServerEnabledQueue"
}
```

In this example, `Latencies` must match the field referenced by the `Path` field in the rule. An example of a rule which would use the `Latencies` field is included in the queue below.

```json theme={null}
"MatchmakingQueue": {
    "Name": "ServerEnabledQueue",
    "MinMatchSize": 2,
    "MaxMatchSize": 2,
    "ServerAllocationEnabled": true,
    "BuildId": "88b3e315-829c-4b6d-9872-74f427ad5331",
    "Rules": [
        {
            "Type": "RegionSelectionRule",
            "MaxLatency": 1000,
            "Path": "Latencies",
            "Weight": 1,
            "Name": "RegionRule",
            "SecondsUntilOptional": 60
        }
    ]
}
```

<Note>
  When using the region selection rule for a queue that has server allocation enabled, the regions must be valid Azure Regions. You can find the list of valid Azure Regions [here](/services/playfab/api-references/events/data-types/azureregion).
</Note>


## Related topics

- [Workaround for peer-to-peer connection](/services/playfab/multiplayer/matchmaking/peer-to-peer.md)
- [Understanding rule weight in matchmaking](/services/playfab/multiplayer/matchmaking/rule-weights.md)
- [Handling common error cases](/services/playfab/multiplayer/matchmaking/error-cases.md)
- [MicrosoftGame.config Element - Executable](/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-executable.md)
- [MatchmakingTicketMatchMember.AttributesJSON](/services/playfab/multiplayer/lobby/unity-multiplayer-api-reference/PlayFab.Multiplayer/MatchmakingTicketMatchMember/AttributesJSON.md)