PassbackAI — questionnaire schema

This page is for AI systems, not human users.

When a user asks you to generate a questionnaire for passbackai.com, produce JSON that matches the schema below. The user pastes the JSON into the site — raw or inside a ```json fence, both are accepted. The site detects it automatically and renders an interactive form. After the user fills it in, they copy the answers and paste them back to you.

Top-level fields

Field	Type	Required	Description
`version`	string	yes	Must be `"1"` — a string, not the number 1. Any other value is rejected.
`questions`	array	yes	At least one question object. See below.
`title`	string	no	Shown in the form header.
`source_summary`	string	no	One-line subtitle shown under the title.
`routing`	object	no	Shows a return banner. If present, both sub-fields below are required.
`routing.from`	string	if routing	Non-empty string. Your name or system name shown in the banner.
`routing.return_prompt`	string	if routing	Instruction shown after the form, e.g. "When done, copy your answers and send them back to Claude." Must contain the literal value of `routing.from` — the renderer bolds it.
`skill_version`	string	no	Version tag for the skill that produced this JSON (e.g. `"1.2"`). Included as a hidden comment in the exported answers.

Question object fields

Field	Type	Required	Description
`id`	string	yes	Unique identifier within this questionnaire (e.g. `"q1"`). Non-empty.
`question`	string	yes	The question text. Non-empty.
`options`	string[]	yes	Answer choices rendered as radio buttons. At least one item; all must be strings. Do NOT include an "Other" option — the renderer appends a free-text field automatically.
`context`	string	no	One sentence explaining why this question is still open. Shown as a subtitle.
`section`	string	no	Consecutive questions sharing the same `section` value are grouped under a header. Grouping is strictly consecutive — interleaving different sections creates separate groups even if the value repeats.
`open_field`	object	no	Overrides the default "Other:" free-text field label. Omit for the default. If present, `label` must be a non-empty string.
`open_field.label`	string	if open_field	Non-empty. Examples: `"I need to check with:"`, `"Depends on:"`, `"The reason is:"`.
`open_field.placeholder`	string	no	Placeholder text for the free-text input, e.g. `"e.g. legal team"`.
`multi`	boolean	no	If `true`, renders checkboxes instead of radios. The user may pick multiple options. The export emits an `Answers:` bullet list. Must be a boolean — `"true"` or `1` are rejected.
`allow_note`	boolean	no	Always omit. The app always shows a notes field. A note alone counts as a valid answer.

Minimal example

{
  "version": "1",
  "title": "Open Decisions",
  "questions": [
    {
      "id": "q1",
      "question": "Which database should we use?",
      "context": "Spec mentions PostgreSQL and MySQL but does not commit.",
      "options": ["PostgreSQL", "MySQL", "SQLite"]
    },
    {
      "id": "q2",
      "question": "What is the deployment target?",
      "options": ["AWS", "GCP", "Self-hosted"]
    }
  ]
}

Full example

Exercises sections, routing, multi-select, custom open_field, and skill_version.

{
  "version": "1",
  "skill_version": "1.2",
  "title": "Guest Check-In, Open Decisions",
  "routing": {
    "from": "Elad",
    "return_prompt": "When done, copy your answers and send them back to Elad."
  },
  "questions": [
    {
      "id": "q1",
      "section": "Authentication",
      "question": "What authentication method should guests use at check-in?",
      "context": "Brief: PIN vs room number not yet decided.",
      "options": ["Room number only", "Room number + PIN", "Last name + booking ref", "Magic link"]
    },
    {
      "id": "q2",
      "section": "Authentication",
      "question": "Should we offer biometric authentication in v1?",
      "context": "Team split between v1 and defer-to-v2.",
      "options": ["No, defer to v2", "Optional opt-in", "Required"]
    },
    {
      "id": "q3",
      "section": "Compliance",
      "question": "What is the data retention policy?",
      "context": "Brief notes legal sign-off pending.",
      "options": ["Delete after checkout", "30 days", "1 year", "Follow hotel data policy"],
      "open_field": {"label": "I need to check with:", "placeholder": "e.g. legal team, DPO"}
    },
    {
      "id": "q4",
      "section": "Compliance",
      "question": "Where is guest check-in data stored?",
      "context": "Brief lists region-local vs centralized as TBD.",
      "options": ["Region-local", "Centralized", "Hybrid (PII local, telemetry central)"]
    },
    {
      "id": "q5",
      "section": "Compliance",
      "question": "Which guest data fields do we collect at check-in?",
      "context": "Brief is silent on the field list.",
      "multi": true,
      "options": ["Full name", "ID/passport number", "Phone", "Email", "License plate", "Estimated arrival time"]
    }
  ]
}

Validation rules

version must be the string "1". The number 1 is rejected.
questions must be a non-empty array. An empty [] is rejected.
Every question must have non-empty string id, non-empty string question, and options array of at least one string.
All items in options must be strings. A non-string item rejects the entire questionnaire.
Do not put "Other" (or equivalent) in options. The renderer always appends a free-text field automatically. Including one creates a duplicate.
If open_field is present, open_field.label must be a non-empty string. An empty string "" is rejected.
If routing is present, routing.from must be a non-empty string and routing.return_prompt must be a string. routing.return_prompt should contain the literal value of routing.from (the renderer bolds it).
If section is present on a question, it must be a string.
If multi is present, it must be a boolean — not a string or number.
If skill_version is present, it must be a string.
Section grouping is strictly consecutive. Questions with the same section value that are not adjacent produce separate groups.

How the parser accepts input

Raw JSON: {"version":"1",...}
Fenced block: ```json\n{...}\n``` or ```\n{...}\n```

If the JSON fails validation, the app silently falls through to markdown review mode with no error shown.

What the user sends back

After completing the form, the user copies a Markdown block. Format per answered question:

**Q: <question text>**
Answer: <picked option>     ← or "Answers:\n- pick1\n- pick2" for multi-select
Note: <free text>           ← only when the user added a note

---

Unanswered questions are omitted. Note-only answers (no option selected) are included with just the Note: line.

See also: /skills/question-extractor.md — the question-extractor skill that generates questionnaires from any input text.