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.
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).
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 (runs locally and auto-advances, so it is never the question a respondent submits) or 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.
