Mappings

Mapping Structure

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

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 outputs value is a Python expression evaluated against the run context, where $ is a plain dict — not JSONPath. Use .get() chains, indexing, and normal Python operators; $.event.competitors[0].name will not work. See Workflows → Expressions are Python, not JSONPath.

Real-World Examples

Sports Data Mapping

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

- 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:

- 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:

- 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 by chaining .get() calls, passing a default at each level so a missing branch yields {} instead of failing the task.

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 to understand available data sources
• Learn about Workflows to see how mappings are used in data processing
• Review Agents to understand how mapped data powers fan interactions