2.15.1 Surveys — Survey Builder — Forms and Responses

The Survey Builder enables teams to create structured, reusable surveys for collecting feedback, confirmations, or structured input across channels. Surveys are treated as first-class entities with explicit schemas, lifecycle states, and response models to ensure consistency, traceability, and reliable analysis.

Survey Structure

A survey consists of a definition and one or more versions. The definition describes intent and scope, while versions capture the exact question structure presented to respondents.

Core structural elements:

Survey identifier and status

Versioned question schema

Distribution context

Response constraints

Versioning ensures that changes to a survey do not invalidate historical responses.

Question Types

The Survey Builder supports a controlled set of question types designed for clarity and analytics compatibility.

Common types:

Single choice

Multiple choice

Rating scale

Free-text response

Boolean confirmation

Each question defines validation rules and optional metadata for analytics.

Example schema fragment:

{ "type": "rating", "label": "How satisfied are you?", "scale": 5, "required": true }

Distribution and Access

Surveys may be distributed through links, embedded contexts, or triggered events. Access is controlled through tokens or scoped identifiers to ensure responses are attributed correctly without exposing internal identifiers.

Distribution guarantees:

Deterministic access control

No session dependency

Optional expiration

Response Model

Each response is stored as an immutable record linked to a specific survey version. Responses capture both the submitted answers and contextual metadata.

Stored attributes:

Survey version reference

Normalized answers

Submission timestamp

Context metadata

Example response creation:

SurveyResponse::create([ 'survey_version_id' => $version->id, 'answers' => $payload, ]);

Validation and Integrity

Responses are validated against the survey schema at submission time. Invalid or incomplete submissions are rejected deterministically.

Integrity guarantees:

Schema-consistent responses

No partial writes

Idempotent submission handling

Analytics and Aggregation

Survey responses are aggregated into analytics-friendly structures without mutating original data. Aggregations may include counts, averages, and distribution summaries depending on question type.

Example aggregation:

SurveyAnalytics::forSurvey($survey)->aggregate();

Lifecycle and Retention

Surveys progress through defined lifecycle states such as draft, active, and closed. Closing a survey prevents new responses without affecting existing data.

Retention of survey responses follows tenant-defined policies and complies with data governance requirements.

Security and Privacy

Survey access and response data are tenant-scoped. Personally identifiable information is collected only when explicitly defined in the survey schema. Access to raw responses is restricted to authorized roles.