# Markdown forms

> Collect autosaved answers in a document, with one row per person.

Kind: reference · ~8 min · Verified v0.260.0 · Next: [SDKs overview](https://pr-2379-stg.superartifacts.app/docs/sdks.md)

## How answers work

Valid changes autosave to one row per identity. `required="true"` marks incomplete drafts; other valid answers still save. Invalid values show errors.

Autosave sends `revision` as `If-Match`. Stale saves return `409 response_changed`; reload and retry. Everyone prefills with `scope=own`.

## Needs

Connect an agent (`superartifacts.app/mcp`); decide privacy and retention.

## Prompt

**Make a feedback form.** Publish a private autosaving form.

```prompt
Add an autosaving feedback form, with a required rating and optional comment. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

## Field types

Fields need a bracket label and quoted `name`. Attributes: `help`, `required`, `placeholder`, `pii` (none/contact/sensitive/secret). Only listed attributes are accepted. Labels: 80 characters; help: 160; placeholder: 200. Names: snake_case, letter first, at most 40 characters. Separate choices with pipes.

| Directive | Control and limit | Attributes |
| --- | --- | --- |
| `field-text` | Text input; 500 characters | `name`, `help`, `required`, `placeholder`, `pii`, `minLength`, `maxLength`, `pattern`, `identity` |
| `field-long_text` | Textarea; 20,000 characters | `name`, `help`, `required`, `placeholder`, `pii`, `minLength`, `maxLength`, `rows` |
| `field-rich_text` | Markdown textarea and preview; 20,000 characters | `name`, `help`, `required`, `placeholder`, `pii`, `minLength`, `maxLength`, `rows` |
| `field-email` | Email input; valid email | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-url` | URL input; HTTP(S) | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-phone` | Telephone input; 6–24 characters | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-color` | Picker and hex input; #RGB or #RRGGBB | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-integer` | Number input; safe integer | `name`, `help`, `required`, `placeholder`, `pii`, `min`, `max` |
| `field-decimal` | Number input; precision 0–8 | `name`, `help`, `required`, `placeholder`, `pii`, `min`, `max`, `step`, `precision` |
| `field-rating` | Radio scale; 2–10, default 5 | `name`, `help`, `required`, `placeholder`, `pii`, `scale` |
| `field-measurement` | Amount and fixed unit; known measure/unit | `name`, `help`, `required`, `placeholder`, `pii`, `measure`, `unit`, `min`, `max`, `step` |
| `field-boolean` | Checkbox; unanswered until chosen | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-date` | Date input; after/before bounds | `name`, `help`, `required`, `placeholder`, `pii`, `after`, `before` |
| `field-datetime` | Date/time input; ISO instant with timezone | `name`, `help`, `required`, `placeholder`, `pii`, `after`, `before` |
| `field-time` | Time input; HH:mm[:ss] | `name`, `help`, `required`, `placeholder`, `pii` |
| `field-choice` | Select; 2–48 choices, 80 characters each | `name`, `help`, `required`, `placeholder`, `pii`, `choices` |
| `field-multi_choice` | Checkboxes; up to 48 choices | `name`, `help`, `required`, `placeholder`, `pii`, `choices`, `minChoices`, `maxChoices` |
| `field-json` | JSON textarea; 16,384 bytes | `name`, `help`, `required`, `placeholder`, `pii`, `maxBytes` |
| `field-image` | Upload; 10 MiB | `name`, `help`, `required`, `placeholder`, `pii`, `accept`, `maxBytes` |
| `field-video` | Upload; 100 MiB | `name`, `help`, `required`, `placeholder`, `pii`, `accept`, `maxBytes` |
| `field-file` | Upload; 25 MiB | `name`, `help`, `required`, `placeholder`, `pii`, `accept`, `maxBytes` |
| `field-reference` | Entry selector; published collection entry | `name`, `help`, `required`, `placeholder`, `pii`, `collection` |
| `field-reference_list` | Multiple entries; at most 100 | `name`, `help`, `required`, `placeholder`, `pii`, `collection`, `minItems`, `maxItems` |

## Examples

Each example is a separate document. Combined form sections must share one dataset.

### Quick survey

```markdown
:::form[Quick survey]{dataset="answers"}
::field-rating[How useful?]{name="useful" scale="5" required="true"}
________
::field-multi_choice[Topics]{name="topics" choices="Design|Engineering|Writing"}
________
:::
```

### Registration

```markdown
:::form[Registration]{dataset="registration"}
::field-text[Name]{name="name" identity="true" maxLength="120" pii="contact"}
________
::field-email[Email]{name="email" required="true"}
________
::field-file[Resume]{name="resume" accept="application/pdf" maxBytes="26214400"}
________
:::
```

### Profile

```markdown
:::form[Profile]{dataset="profile"}
::field-reference[Programme]{name="programme" collection="program"}
________
::field-measurement[Working weight]{name="weight" measure="load" unit="kg" min="0" step="0.5"}
________
::answers[Your saved profile]{fields="programme,weight"}
:::
```

Reference entries must exist and be published for visitor access; the agent confirms
the authorized collection first. Forms derive those read grants, never CMS write access.

## Privacy, identity and retention

| Topic | Behaviour |
| --- | --- |
| Identity | “One person” means one platform identity. An anonymous artifact cookie lasts a year; clearing cookies or signing in after answering can create another row. Signed-in identity is stable across devices. Names and `identity="true"` label Who; they do not authenticate or deduplicate people. |
| Access and retention | Defaults: own-row reads, upsert, one row per identity, 30-day retention and 10,000 rows per artifact. Owners/Editors inspect responses in the dashboard artifact's **Data** tab; readers see only their own row. Contact data is masked for non-owners; sensitive values are encrypted; secrets stay write-only except audited owner reveal. Email, phone, media and free text above 280 characters are at least contact data. Only text/long_text can be secret, with finite retention at most 730 days. Media cannot be sealed. Ask the owner before collecting sensitive information or widening access. |

## Read responses

`::answers[Your answers]{fields="programme,weight"}` reads the current identity only.
An owner response view uses `::data-table[Responses]{dataset="profile" fields="programme,weight" audience="owner"}`.
Owner scope is enforced.

**Review my responses.** Read owner-authorized answers without publishing them.

```prompt
Read my Markdown form responses as the owner with super_data. Ask which artifact; keep contact masking and secret protections, summarize drafts and completeness, and do not publish or share answers.
```

CSV exports decode choices, references and file links; JSON includes decoded values and stored values. Secrets remain hidden.

## Offline and exports

| Topic | Behaviour |
| --- | --- |
| Recovery | Wait for Saved before leaving. Offline changes stay in this tab's memory; reload or close can lose them. Retry after reconnecting. Upload bytes are never queued durably. If the row changed elsewhere, the form reloads your row and asks before overwriting the same field. No browser-unload save is guaranteed. Do not repeatedly retry invalid fields. |
| Exports and Listen | Listen reads labels and help, excluding answers. Tiles make no data calls. Print, PDF and Word show blank forms; saved answers are never included. |

References must point to published entries in their declared collection. Missing, draft and foreign entries are refused.

## Limits and changes

| Topic | Behaviour |
| --- | --- |
| Limits | At most 24 fields, four reference collections, 6,144 policy bytes and 128 KiB per response. Fields share the aggregate ceiling. Forms cannot nest; directives allow four levels and 65,536 bytes each. All attribute values are quoted. Fenced examples do not become forms. Duplicate names and conflicting datasets fail publication. Removed fields stay in historical data; removing a form does not delete responses. Use a new name for a changed type or reference collection; choices may grow. New forms default to 30-day retention; republishing preserves your stored privacy, retention and row limits. |
| Unavailable | No conditional fields, public response tables, durable offline drafts, cross-identity merging or multiple datasets. |

## Check it worked

Data lists saved answers; Details opens each row; Last answered shows its latest update. Choices use chips, ratings use stars, measurements show units. Expand long answers/JSON. Removed fields stay marked. Two identities should show two rows.

Invalid source is saved with a warning. Correct and save to activate it.
