Add Maple
← All help articles

Using schema files to enhance your data

If you have a separate schema file (often called a "question key" or "data dictionary") that describes your survey questions, you can upload it to AddMaple to automatically apply descriptive labels, group related questions, and organize your columns.

This is useful when your CSV export uses technical column names (like q7_industry or TechEndorse_1) but you have a separate file that contains the full question text and metadata.

What is a schema file?

A schema file is a CSV that maps your data's column names to human-readable information. Common sources include:

  • Question keys from survey platforms (User Interviews, Qualtrics, SurveyMonkey)
  • Data dictionaries from research teams
  • Codebooks from SPSS or statistical packages
  • Schema exports from survey builders

Example schema file

Question,Question Text,Type
screener_1,Which statement reflects your relationship to research?,Multiple Choice
screener_2,What type of research do you primarily conduct?,Multi-select
q1_title,Which is closest to your job title?,Multiple Choice
q7_industry,Which industry category describes your company?,Dropdown

Uploading a schema file

  1. Open Project Settings (More → Settings)
  2. Navigate to the "Manage Project" tab
  3. Scroll to "Upload Schema File"
  4. Click "Upload Schema"

A schema mapper will appear where you can:

  • Upload your schema CSV file
  • Map schema columns to AddMaple fields
  • Preview the mapping before applying

Mapping schema columns

The schema mapper shows your CSV columns and lets you assign each one to a specific field:

Required field

  • Column Name (rawName) — Must match your data's column headers exactly

Recommended fields

  • Display Label — Human-readable name shown in AddMaple
  • Question Text — Full question wording (used for grouping)

Optional fields

  • Group ID — Groups related sub-questions together (matrix questions)
  • Group Label — Display name for the group
  • Short Label — Abbreviated version of the label
  • Semantic Category — Classification or theme
  • Tags — Comma or semicolon-separated keywords
  • Order — Numeric order for sorting within groups
  • Hidden — Set to "true" to hide the column by default

How schema mapping works

After you upload and map a schema file, AddMaple will:

  1. Match columns — Find each data column using the rawName from your schema
  2. Apply labels — Replace technical names with descriptive question text
  3. Create groups — Organize related questions using Group ID and order
  4. Update settings — Regenerate column configuration with schema metadata

The page will reload automatically with your updated column settings.

Example use cases

Use case 1: Survey with question codes

Your data export:

  • Column names: screener_1, screener_2_market_r, q1_title, q7_industry

Your schema file:

Column,Question
screener_1,Which statement reflects your relationship to research?
screener_2,What type of research do you primarily conduct?
q1_title,Which is closest to your job title?
q7_industry,Which industry describes your company?

Mapping:

  • Column Name → "Column"
  • Display Label → "Question"

Result: Columns display with full question text instead of technical codes.

Use case 2: Grouped matrix question

Your data export:

  • Columns: TechEndorse_1, TechEndorse_2, TechEndorse_3, TechEndorse_4

Your schema file:

qname,question,sub,group_id,order
TechEndorse_1,What attracts you to a technology?,AI integration,QID18,1
TechEndorse_2,What attracts you to a technology?,Easy-to-use API,QID18,2
TechEndorse_3,What attracts you to a technology?,Robust API,QID18,3
TechEndorse_4,What attracts you to a technology?,Quality reputation,QID18,4

Mapping:

  • Column Name → "qname"
  • Display Label → "sub"
  • Question Text → "question"
  • Group ID → "group_id"
  • Group Label → "question"
  • Order → "order"

Result: Four sub-questions grouped together under "What attracts you to a technology?" with proper ordering.

Use case 3: Multi-select with option labels

Your data export (double-header format):

  • Row 1: screener_2_market_r, screener_2_user_ux, screener_2_data_science
  • Row 2: Market research, User/UX research, Data science

Your schema file:

Question,Question Text
screener_2,What type of research do you primarily conduct?

Steps:

  1. First, set Header rows to 2 in Project Settings
  2. Then upload schema file
  3. Map: Column Name → "Question", Display Label → "Question Text"

Result: Individual checkbox columns merge into a single multi-select column with:

  • Column name: "What type of research do you primarily conduct?"
  • Values: "Market research", "User/UX research", "Data science" (from Row 2)

Schema file formats

AddMaple supports flexible schema formats. Here are common patterns:

Minimal schema (column names and labels)

column,label
q1,Job title
q2,Years of experience
q3,Industry

Full schema (with grouping)

column_name,display_label,question_text,group_id,group_label,order
TechEndorse_1,AI integration,What attracts you?,QID18,What attracts you?,1
TechEndorse_2,Easy API,What attracts you?,QID18,What attracts you?,2

Question key (simple format)

Question,Question Text
screener_1,Which statement reflects your relationship to research?
q7_industry,Which industry describes your company?

For multi-select questions, the schema typically lists the base question (like screener_2) and AddMaple automatically matches related columns (like screener_2_market_r, screener_2_user_ux) through prefix matching.

Tips for preparing schema files

  • Exact column name match — The rawName field must match your data's column headers exactly (including underscores, capitalization)
  • One row per column — For multi-select questions, you can list either the base question or each individual option column
  • CSV format — Save as CSV (not Excel) for reliable upload
  • Remove blank rows — Empty rows in the schema will be skipped
  • Prefix matching — For multi-select splits like q3_career_change_promotion, list the base q3_career_change and AddMaple will match all related columns

Common schema mappings

Different survey platforms export different schema formats. Here's how to map them:

Simple question key format

Question,Question Text,Notes,Type
screener_1,Which statement reflects your relationship to research?,Select one,Multiple Choice

Mapping: Column Name → "Question", Display Label → "Question Text"

Matrix question format (with grouping)

qid,qname,question,sub,sq_id
QID18,TechEndorse_1,What attracts you to a technology?,AI integration,1

Mapping: Column Name → "qname", Display Label → "sub", Question Text → "question", Group ID → "qid", Order → "sq_id"

Research codebook format

variable,label,category,hide
participant_id,Participant ID,identifier,true
age,Age in years,demographic,false

Mapping: Column Name → "variable", Display Label → "label", Semantic Category → "category", Hidden → "hide"

After applying a schema

Once you apply a schema file:

  • Columns update immediately with new labels and grouping
  • The page reloads to reflect changes
  • Multi-select questions use descriptive option labels instead of column IDs
  • Matrix questions appear as grouped sub-questions
  • You can still edit individual columns manually in Manage Columns if needed

Important: Applying a schema regenerates all column settings. Any manual edits you've made to column names, types, or grouping will be replaced with the schema's definitions.

Troubleshooting

My columns didn't update

  • Verify the rawName in your schema matches the actual column headers in your data exactly
  • Check for extra spaces or different capitalization
  • For multi-select splits, try listing the base column name without suffixes

Some columns are missing

  • Ensure every column in your data has a corresponding row in the schema
  • Columns without schema entries will keep their original auto-detected names

Groups aren't appearing

  • Make sure you mapped both Group ID and Group Label fields
  • Verify all columns in a group share the same Group ID value
  • Add Order values if you want to control the sequence within groups

Multi-select values show column IDs instead of labels

  • If using double headers, set Header rows to 2 first, then apply the schema
  • The second header row provides the descriptive option labels

Related features

  • Header Rows — Configure multi-row headers before uploading schema
  • Manage Columns — Manually edit column settings after schema application
  • Combining Columns — Understand how multi-select merging works
  • Group — Learn about grouped matrix questions