HTML DSL

A survey is authored as HTML with survey-specific tags and attributes. The parser builds the model, validates canonical rules, and preserves only supported compatibility paths.

Minimal question

<question type="single" name="Q1" required>
  <description>Which option do you prefer?</description>
  <options>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </options>
</question>

Naming

Type boundaries

Rendered class contract

Rendered DSL elements receive deterministic classes such as question, question-desc, question-options, option-1, option--2, option-input, question-attributes, and attr-1. Authored class attributes append presentation classes; they do not change logic or answer schema.

Template Expressions

Survey HTML DSL text and non-identity attributes can use JavaScript-style Template Expressions inside {{ ... }}. They are evaluated at Survey Link render time and in Run generate with the same restricted logic context as if expressions.

<script name="helpers">
function answerConvert(value) {
  return String(value || "").trim().toUpperCase();
}
</script>
 
<question type="number" name="BUDGET"
  min="{{ SEGMENT.val() === 1 ? 10 : 5 }}"
  max="{{ SEGMENT.val() === 1 ? 60 : 45 }}"
  step="{{ SEGMENT.val() === 1 ? 5 : 1 }}"
  pre-text="{{ answerConvert(SEGMENT.val()) }}">
  <description>Hello {{ answerConvert(NAME.val()) || "SHOPPER" }}</description>
</question>

Rules:

• Empty {{ }} is a hard authoring error and the exact expression token is highlighted red in Survey HTML Mode and supported GUI fields.
• Non-empty expression tokens receive a lightweight violet authoring highlight. If a fixed enum/dropdown attribute is authored as a Template Expression in HTML Mode, GUI Mode shows the control as disabled EXP and points authors back to HTML Mode.
• Question/option/attribute/group identity attributes such as name, type, and value cannot be dynamic because response storage and export names must stay stable.
• <survey-config> attributes are static-only and cannot use Template Expressions.
• Non-identity attributes can be dynamic, including min, max, step, pre-text, post-text, option-columns, option-columns-min, expanded, hide-group, required, and display attributes.
• Script helper calls are allowed only when the helper is declared in the same Survey HTML DSL <script> as a restricted top-level function or registerSurveyHelper(...).
• Runtime expression errors fail open where possible, are deduplicated, and appear in the TEST console and Run generate diagnostics.

Dynamic numeric/date attributes are validated after evaluation. If a dynamic min / max pair becomes impossible, Survey Link falls back to a responseable state and logs the fallback instead of blocking the respondent.

Groups

<group> can be used inside <options>, <attributes>, <share-list>, and loop <items> to keep nested option/attribute/item structure.

<options order="random" group-order="random">
  <group name="CORE" if="Q1.o1" order="asc" group-order="rotation" fix>
    <label>Core brands</label>
    <option value="1">Brand A</option>
    <option value="2">Brand B</option>
  </group>
</options>

Group attributes:

Container-level order remains the default. Group-level order / group-order override only inside that group. Hidden groups are removed before required validation and auto-punch/skip logic. Inserted share-list groups keep the authored <insert-list> source while runtime expands the reusable group tree.

Quota DSL

Quota source HTML is wrapped by one <quota-source> root and one or more <quota-sheet> children. The sheet id is the canonical quota name used by Workbench tabs, Excel sheet names, import validation, and runtime quota checkpoints.

<quota-source>
  <quota-sheet id="gender_age" title="Gender × Age" flat-view="false">
    <columns>
      <leaf id="male" label="Male" if="Q1.o1" />
      <leaf id="female" label="Female" if="Q1.o2" />
    </columns>
    <rows>
      <leaf id="age_18_34" label="18-34" if="AGE.value &gt;= 18 && AGE.value &lt;= 34" />
      <leaf id="age_35_plus" label="35+" if="AGE.value &gt;= 35" />
    </rows>
  </quota-sheet>
 
  <quota-sheet id="concept_quota" title="Concept quota" priority="true" priority-count="1">
    <rows>
      <leaf id="r1" label="Concept A" if="true" />
      <leaf id="r2" label="Concept B" if="true" />
      <leaf id="r3" label="Concept C" if="true" />
    </rows>
  </quota-sheet>
</quota-source>

Quota rules:

question, code, type, and allocation are not canonical quota leaf attributes. A leaf is counted when its if expression matches, whether the underlying answer came from single or multi selection. if="true" is valid and means every respondent who reaches the quota checkpoint can match that leaf; combine it with priority assignment to auto-balance concepts or cells without asking a visible question. GUI-created manual row leaves use r{num} ids and manual column leaves use c{num} ids; existing imported or picker-derived ids are preserved. Excel import templates are visible-structure only: users may edit Limit values, but label/header/schema edits are rejected instead of changing the HTML DSL.

Quota runtime and export behavior

When Survey Link reaches a <quota> checkpoint, the runtime evaluates every configured cell for that source from the persisted quota snapshot, not by querying the database from authored JavaScript. With the default priority="false", every matched non-full cell is assigned and counted; matched full cells are excluded from counting. With priority="true", only the priority-count most underfilled matched non-full cells are assigned. priority-type="count" compares current complete sample counts. priority-type="ratio" compares current/limit fill ratios and is a hard error when any cell limit is blank/null. Ties among equally underfilled eligible cells may be selected randomly. If all matched required cells are already full, the response ends as quotafull. If the checkpoint is active but no cell can be assigned or matched, the response ends as screenout with a quota-generated screenout_status value. These generated statuses start at 901 in first-seen quota source order and use labels like NOT_QUOTA:gender_quota.

Response export adds trusted quota label columns after system columns and before question columns:

QUOTA_SHEET_ is reserved for quota export metadata and cannot be used as an authored question, screen-out, share-list, or raw-control response name. The array is stored as text in tabular exports so CSV, XLSX, and JSON projections keep the same value contract.

Survey config question-name badges

<survey-config /> may control whether Survey Link renders a compact question badge.

<survey-config show-name="none" page-animation="fade" test-back-button="true" />

show-name="index" is evaluated from the currently rendered visible question sequence. Hidden questions do not reserve numbers, so branching paths can show different indices for the same authored question. In TEST Audit Mode, show-name="name" avoids duplicating the question name; none and index still allow Audit Mode to expose the authored question name for QA.

Terminal redirect DSL

<redirect> is an optional Survey Link terminal-routing block. Omit it to keep the built-in end page and save redirectGroup as null.

<redirect>
  <group title="Default Group" default />
  <group name="v2" title="Partner list">
    <route url="https://example.com/complete" if="$status.complete" />
  </group>
</redirect>

Key rules:

• Exactly one group is default when <redirect> exists; a single saved group is automatically serialized with default.
• Group names are optional, but named groups must be unique and programming-style. Only one unnamed group is allowed.
• Route url and if are required; duplicate route conditions inside one group are hard errors.
• Path selection wins over query selection: /s/{surveyId}/v1 beats ?redirectGroup=v2.
• Named default groups canonicalize the bare Survey Link URL to the named path and save that group name.
• Invalid redirect group selection or unsafe final URLs block progression before response persistence.

See Terminal Redirects for the full authoring contract.

Option columns and group display

Supported question types may request a responsive option/attribute grid with option-columns and option-columns-min.

<question type="single" name="REGION" option-columns="3" option-columns-min="2">
  <description>Where do you shop most often?</description>
  <options>
    <option value="1">North</option>
    <option value="2">South</option>
    <option value="3">East</option>
  </options>
</question>

Rules:

• Values must be integers greater than or equal to 1.
• option-columns-min cannot be greater than option-columns when both are present.
• The effective column count cannot exceed the rendered item count.
• For single, multi, and ranking, columns affect option cards; attr-level values override question-level values per row.
• For number, text, and date, columns affect repeated attribute input rows.
• <group> panels always span the full row; the grid is applied inside each group body.

single, multi, and ranking also support grouped option/attribute accordion display:

<question type="ranking" name="FEATURE_RANK" group-display="accordion" expanded="true" option-columns="2">
  <description>Rank the most useful features.</description>
  <options>
    <group name="DISCOVERY" expanded="true">
      <label>Discovery</label>
      <option value="1">Search</option>
      <option value="2">Recommendations</option>
    </group>
    <group name="CHECKOUT">
      <label>Checkout</label>
      <option value="3">Payment speed</option>
      <option value="4">Delivery clarity</option>
    </group>
  </options>
</question>

Group accordion status icons indicate that the group contains a response; they do not change page-level navigation or submit behavior.

Question type attribute matrix

Custom HTML controls

Raw HTML can be used with or without framework <question> blocks. Bindable native controls are input, select, and textarea with a unique name. Unsupported named controls such as output, meter, progress, hidden/file inputs, and unnamed response inputs remain hard errors.

<style>
.custom-card { border: 1px solid #dcd7d3; padding: 1rem; }
</style>
<script name="helpers">
function normalizeLabel(value) { return String(value || '').trim(); }
</script>
<div class="custom-card">
  <label>Email <input type="email" name="RAW_EMAIL" required /></label>
  <label>Channel
    <select name="RAW_CHANNEL"><option value="app">App</option></select>
  </label>
  <label>Feedback <textarea name="RAW_FEEDBACK" minlength="10"></textarea></label>
</div>

Raw <form> tags are allowed for custom HTML survey surfaces, but Vibe Survey still owns final response submission and persistence. Keep response names globally unique across framework questions and raw controls.