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

# Mappings

> Configurations that define how data from one system (like a sports data provider or other external source) should be transformed and structured for use in your AI agents and workflows. They act as translators between different data formats and schemas.

## Mapping Structure

Mappings in Machina Sports are defined in YAML format with the following structure:

```yaml theme={null}
mappings:
  - type: "mapping"
    title: "Mapping Title"
    name: "mapping-name"
    description: "Description of the mapping purpose"
    outputs:
      output_field: "$.get('source_data', {}).get('path.to.field')"
      calculated_field: "$.get('field1') + ' ' + $.get('field2')"
```

Each mapping uses JSONPath expressions to extract and transform data from the source format to the target format.

## Real-World Examples

### Sports Data Mapping

This example from our samples shows how to map soccer event data:

```yaml theme={null}
- type: "mapping"
  title: "Sportradar Soccer Mapping"
  name: "sportradar-soccer-mapping"
  description: "Mapping data from sportradar soccer data"
  outputs:
    event_code: "$.get('event_selected', {}).get('sport_event', {}).get('id')"
    team_home_name: "$.get('event_selected', {}).get('sport_event', {}).get('competitors', [])[0].get('name')"
    team_away_name: "$.get('event_selected', {}).get('sport_event', {}).get('competitors', [])[1].get('name')"
    team_home_id: "$.get('event_selected', {}).get('sport_event', {}).get('competitors', [])[0].get('id')"
    team_away_id: "$.get('event_selected', {}).get('sport_event', {}).get('competitors', [])[1].get('id')"
    title: "$.get('event_selected', {}).get('title')"
```

### Team Profile Mapping

This example maps NBA team profile data:

```yaml theme={null}
- type: "mapping"
  title: "Sportradar NBA Team Mapping"
  name: "sportradar-nba-team-mapping"
  description: "Mapping data from sportradar nba team data"
  outputs:
    team_id: "$.get('team_profile', {}).get('id')"
    team_name: "$.get('team_profile', {}).get('name')"
    team_alias: "$.get('team_profile', {}).get('alias')"
    team_market: "$.get('team_profile', {}).get('market')"
    team_full_name: "$.get('team_profile', {}).get('market') + ' ' + $.get('team_profile', {}).get('name')"
    conference: "$.get('team_profile', {}).get('conference', {})"
    division: "$.get('team_profile', {}).get('division', {})"
    championships_won: "$.get('team_profile', {}).get('championships_won')"
    championship_seasons: "$.get('team_profile', {}).get('championship_seasons')"
```

## Using Mappings in Workflows

Mappings are used in workflows as tasks to transform data:

```yaml theme={null}
- type: "mapping"
  name: "sportradar-nba-team-mapping"
  description: "Transform the SportRadar NBA team data"
  inputs:
    team_profile: "$.get('team-profile')"
  outputs:
    team_id: "$.get('team_id')"
    team_name: "$.get('team_name')"
    team_full_name: "$.get('team_full_name')"
    championships_won: "$.get('championships_won')"
```

## Common Mapping Patterns

### Nested Data Extraction

Extract values from deeply nested JSON structures using JSONPath expressions.

### Field Renaming

Map fields from source format to differently named fields in the target format.

### Data Combination

Combine multiple source fields into a single target field (e.g., first\_name + last\_name → full\_name).

### Default Values

Provide default values when source fields might be missing.

### Array Processing

Extract and transform elements from arrays in the source data.

## Best Practices

* Use descriptive mapping names that indicate the source and purpose
* Include proper error handling with default values for missing fields
* Keep mappings focused on a single data type or entity
* Test mappings with various data scenarios to ensure robustness
* Document complex transformations with comments

## Next Steps

* Explore [Connectors](/core-components/connectors) to understand available data sources
* Learn about [Workflows](/core-components/workflows) to see how mappings are used in data processing
* Review [Agents](/core-components/agents) to understand how mapped data powers fan interactions