Reference for the humanize schema: a dict that configures how survey questions are presented in web surveys with human respondents.
When creating a human survey or preview (e.g. survey.humanize() or survey.preview()), you can pass a humanize schema to control styling and optionality per question. The schema is validated against your survey before use.
steps only. The steps, in order. At least two are required.A step is a boundary, not a bucket: it covers every survey item from the end of the previous step through its complete_after. Questions can be added or removed inside a step without touching this config, and items a respondent skips past inside a step don’t move the marker.Each step is an object with:
label (string, optional) — the word under the marker, 1–60 characters. Omit or set to null to render the marker alone.
complete_after (string, optional) — the name of the survey item (question or instruction) after which this step is complete. Only the final step may omit it, which runs that step to the end of the survey; every earlier step must name an item. The same item must not be named by two steps.
Whether the question is optional. Default is false when omitted.Supported question types:free_text, budget, checkbox, checkbox_with_other, file_upload, interview, likert_five, linear_scale, list, matrix, multiple_choice, multiple_choice_with_other, numerical, rank, top_k, yes_no.Note: optional currently has no effect for interview and rank.
MC-style (likert_five, linear_scale, multiple_choice, yes_no): "radio" (list of radio buttons) or "dropdown" (single <select>). Default is "radio". Use {"type": "radio"} or {"type": "dropdown"}.
Numerical (numerical): "input" (number input field) or "slider" (range slider). Default is "input". Use {"type": "input"} or {"type": "slider", "min": 0, "max": 100, "step": 1}. For slider, min must be less than max, step must be positive and not exceed (max - min).
Matrix (matrix): "table" (the whole grid at once) or "carousel" (one item at a time). Default is "table". Use {"type": "table"} or {"type": "carousel"}.
carousel only. Whether answering an item moves to the next one on its own, rather than waiting for the respondent to click Next.Every answer advances, corrections included — the same rule respondents will have met in Qualtrics. Set to false when respondents are expected to revise as they go, since under true a correction costs the way back as well.
Matrix only (matrix). Cells checked before the respondent touches the grid. Omit or set to null for an empty grid, which is what matrices render by default.A preselection changes what the question measures: it puts an answer in front of the respondent and asks them to disagree with it, so the answers lean toward the preselected column. It also removes the blank — a row left alone is recorded as the preselected option and cannot be told apart from a considered answer. Both are usually the point (a long grid where most rows are expected to be neutral is far cheaper to finish), but they are worth deciding before fielding rather than after.
The rules, in order. At least one is required.Rules are tried in order and the first match wins, so the list reads like a routing table: the specific rows first, the catch-all last. A rule that matches every item must therefore be last — anything behind it could never be reached, and a list in the wrong order raises a validation error rather than silently dropping the rules it shadows.Each rule is an object with:
match (dict, required) — which rows the rule fills. Must be {"type": "all"}, every row of the grid.
option (dict, required) — which column those rows are set to. Must be {"type": "text", "value": "<option text>"}, naming an option by its exact text in the question’s question_options. Matching is literal, so surrounding whitespace is not trimmed for you.
If the option you name is not in the list as served, the rule fills nothing. It does not raise, and the survey still runs. A matrix’s columns can be piped from an earlier answer, so the text you name may not exist until the question reaches the respondent — and a preselection must not be the thing that breaks a survey in front of them. Where the columns are a literal list, a name that matches none of them is caught when the survey is saved, while you can still fix it.Those rows are then left empty; they do not fall through to the next rule. A row belongs to the first rule that matches it whether or not that rule finds its option, so a row singled out by an early rule cannot quietly pick up the catch-all that rule was written to override.
If set, the human survey will require the respondent to select this exact option. Use for attention checks or forcing a particular choice. Omit or set to null to allow any selection.
Checkbox only (checkbox, checkbox_with_other). Options that stand alone: checking one clears every other selection — including any other exclusive option, and for checkbox_with_other the respondent’s “other” entries — and selecting anything else clears it. Use for options like "None of the above" or "Prefer not to say".Each entry must be the exact text of an option in the question’s question_options — matching is literal, so surrounding whitespace is not trimmed for you. Entries must be non-empty and unique. Because an exclusive option is an ordinary member of the option list, the submitted answer looks like any other selection. Defaults to an empty list, meaning no option is exclusive.
Interview only (interview). The intro screen shown to the respondent before the interview begins. The intro screen is always shown; this field customizes its text. Omit or set to null to use the default text ("This will be a conversation with an AI agent.").
The spoken language for the voice interview. A lowercase language id from the supported set below. Case and surrounding whitespace are normalized (e.g. " French " becomes "french"); omit or set to null to use the default ("english"). An unsupported value raises a validation error.Supported languages:english, french, german, spanish, portuguese, chinese, japanese, hindi, italian, korean, dutch, polish, russian, swedish, turkish, tagalog, bulgarian, romanian, arabic, czech, greek, finnish, croatian, malay, slovak, danish, tamil, ukrainian, hungarian, norwegian, vietnamese, bangla, thai, hebrew, georgian, indonesian, telugu, gujarati, kannada, malayalam, marathi, punjabi, multilingual.
The language for the text interview. A lowercase language id from the supported set below. Case and surrounding whitespace are normalized (e.g. " French " becomes "french"); omit or set to null to use the default ("english"). An unsupported value raises a validation error.Supported languages:english, french, german, spanish, portuguese, chinese, japanese, hindi, italian, korean, dutch, polish, russian, swedish, turkish, tagalog, bulgarian, romanian, arabic, czech, greek, finnish, croatian, malay, slovak, danish, tamil, ukrainian, hungarian, norwegian, vietnamese, bangla, thai, hebrew, georgian, indonesian, telugu, gujarati, kannada, malayalam, marathi, punjabi, multilingual.
Label shown above the interviewer’s messages. Must be between 1 and 200 characters. Defaults to "AI Interviewer". Omit or set to null to use the default.
Message shown to respondents when the interview ends. Must be between 1 and 2500 characters. Defaults to "Thank you for your time. This interview has been ended. Your responses have been recorded and will be valuable for our research." Omit or set to null to use the default.
The list of checklist items. Each item is an object with:
id (string, required) — a unique identifier, 1–64 characters, restricted to letters, digits, underscores, and hyphens (regex pattern ^[A-Za-z0-9_\-]+$). Item ids must be unique within the checklist.
label (string, required) — participant-facing text shown in the checklist UI, 1–200 characters.
instructions (string, required) — model-facing text describing the condition under which the model should check the item off, 1–2000 characters.
Lets the interviewer ask multiple-choice and numerical questions mid-interview, rendered as input widgets rather than prose. Omit or set to null to disable structured questions.
Which question types the model may use. Each entry must be "multiple_choice" or "numerical". Defaults to both. Narrowing this restricts the model to the listed types. Must be non-empty (omit structured_questions instead of passing an empty list) and must not contain duplicates.
"respondent" — the participant can end at any time; the End Interview button is always available (default). No other fields apply.
"interviewer_gated" — the End Interview button is hidden until the model has signalled that its goals are met; only then can the participant end. This mode also accepts interview_marked_complete_message and participant_chat_after_complete.
interviewer_gated only. A message to surface on the turn the interviewer first marks the interview complete. If omitted or set to null, the LLM will generate text for that turn instead.
interviewer_gated only. Whether the participant can keep sending messages after the interviewer has marked the interview complete.
"open" — the message composer stays live; marking the interview complete only unlocks the End Interview button (default).
"locked" — the composer closes as well, so the marking turn is the last thing the participant reads and ending the interview is their only remaining action.
Optional indicator shown after the respondent clicks Next, while the following question runs. Omit or set to null for no indicator.Supported question types:free_text, budget, checkbox, checkbox_with_other, file_upload, likert_five, linear_scale, list, matrix, multiple_choice, multiple_choice_with_other, numerical, rank, top_k, yes_no.Note: not supported for compute or image_generation (both run in the background and auto-advance, so neither is ever the question a respondent submits), or for interview.
How the indicator is rendered. Must be "callout" — a callout box shown while the next question runs, with the subtitle "We'll continue automatically when it's ready."
If the schema is invalid, Expected Parrot raises HumanizeSchemaValidationError. Common causes:
A key in questions is not a question name in the survey, or is an instruction.
A question’s type is not supported for humanize schema (e.g. demand, dropdown).
A question’s entry has the wrong shape for its type (e.g. wrong field types or extra fields that aren’t allowed).
Top-level structure is invalid (e.g. questions not a dict, or an entry not a dict).
You can also pass the schema to survey.preview(humanize_schema=...) to get a preview URL.Ensure your humanize schema matches the parameters above for each question type in your survey.
⌘I
Assistant
Responses are generated using AI and may contain mistakes.
