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

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