📝 Forms

Spec map

Home: All V2 Specs · Foundation: Data System (UVP) Mode(s): Relationship Mode Related specs: Data System (UVP), Polling Engine

🎯 Goals

What This Product Is

Provide the public-facing UVP acquisition surface that turns strangers into resolved contacts in Relationship Mode. Mode Architecture
Keep Forms as the sole public-web UVP-creation mechanism, exclusive to Relationship Mode with the strictest consent controls. The Core Architectural Idea
Make a form a published UVP write configuration so every input maps cleanly to a single UVP field. The Field Library
Expose a curated, mode-appropriate set of locked global fields and reusable account custom fields as the form-building palette. Creating a Custom Field From Inside the Builder
Let users create clean, deduplicated custom fields inline that feed the field-promotion pipeline. The Three-Tab UI
Provide Forms/Canvas/Submissions navigation that makes building, branding, distributing, and reviewing forms intuitive. The Submission Pipeline
Reliably validate, identity-match, and write every submission to the UVP with full provenance. Form States & Lifecycle
Govern form Draft/Live/Paused/Archived transitions to protect data integrity for ongoing submitters. Versioning
Preserve form version snapshots so historical submissions remain interpretable and precisely provenanced. The Field Deletion Rules
Protect in-use and promoted fields from deletion to preserve data integrity and platform asset value. Distribution & Embedding
Distribute forms via hosted links, iframe/JS embeds, QR codes, and branded social previews. Analytics & Stats
Surface lightweight per-form analytics including submissions over time, conversion, and match rate. Permissions
Apply role-based access so only trusted roles author forms and manage custom fields.

Mode: Relationship Mode Status: Conceptual Spec — V1 Scope Definition Companion specs: vrm-data-system (UVP, field system, exposure controls), vrm-polling-engine (Surveys distinction), politogy-vrm-brand

1. What This Product Is

The Forms feature is the public-facing UVP acquisition surface for Relationship Mode. It is how strangers become contacts. A user builds a form by dragging fields onto a canvas, publishes it as a hosted link or embed, and every submission writes data into the Unified Voter Profile (UVP) database — either updating an existing UVP or creating a new Relationship-sourced UVP record.

Forms are deliberately simple in the UI and deliberately powerful in the backend. The user thinks they are building a contact form. They are actually configuring a structured write operation against the canonical voter data system. Every form submission strengthens the UVP, feeds Aggregate Intelligence, and grows the value of the platform’s underlying data asset.

Product thesis: A campaign or organization should be able to stand up a branded, embed-ready form in five minutes, capture leads anywhere on the web, and have those leads automatically resolved against — or added to — the same UVP database that powers Campaign Mode and Petition Mode. No exports, no syncs, no duplicate contact lists. One profile. One login. Total control.

2. Mode Architecture

Forms live exclusively inside Relationship Mode. This is foundational.

Mode	Audience Source	Voter-Data Tool	Acquisition Tool
Relationship Mode	Opt-in, customer-supplied	Surveys (sent to existing contacts)	Forms
Campaign Mode	State voter file	Polls (representative methodology)	None — audience is the voter roll
Petition Mode	Signers, eligible voters	Petitions (signature capture)	Petition sheets, not Forms

Forms is the only mechanism in VRM where a UVP can be created by a stranger filling in a public web page. Every other UVP creation path is initiated by Politogy (voter file imports), the customer (manual entry, CSV upload), or a structured campaign workflow (canvass, petition).

Because Forms creates UVPs from anonymous web traffic, it carries the strictest consent, anti-abuse, and identity-matching requirements in the platform.

3. Forms vs. Surveys vs. Polls — The Distinction

These three products look similar to a layperson and are completely different system-wide. Honor this throughout the implementation.

	Forms	Surveys	Polls
Mode	Relationship	Relationship	Campaign
Audience	Anyone on the public internet	Existing opt-in contacts	Voter-file sample
Trigger	User clicks a link or sees an embed	User receives an invite (email/SMS)	Methodologically sampled outreach
Purpose	Acquire a contact; capture intent	Re-engage a known contact	Strategic intelligence
UVP Outcome	Create or match a UVP	Update an existing UVP	Score a respondent on the four dimensions
Scoring	None	None	Support / Confidence / Intensity / Volatility
Identity	Self-asserted	Linked via tokenized invite	Tokenized respondent linkage

Forms are the front door. Surveys are the conversation. Polls are the science. A submission from a Form can later be invited to a Survey. A Survey respondent can later be sampled into a Poll. The data flows one direction: Forms feed Surveys feed Polls, all into the same UVP.

This spec covers Forms only. Surveys are an evolution of the form function and share the field-library architecture defined here, but live in their own spec.

4. The Core Architectural Idea: Forms Are a UVP Write Configuration

A form is not a self-contained data object with its own fields. A form is a published configuration that selects which UVP fields to expose for write, in what order, with what branding, with what consent language.

This means:

Fields are not created on a form. Fields live in the account’s Field Library (global fields + account custom fields). A form selects from that library.
Every form input maps to a single UVP field. No orphan data. No “form-only” fields. If it’s in a form, it has a home in the UVP.
Removing a field from a form never deletes the field or the data. It only stops exposing that field on that form.
Two forms using the same custom field write to the same column. A custom field named “Issue Interest” used on three forms produces one consolidated value per UVP, not three.

This is the architectural rule that makes Forms a UVP capture surface rather than a parallel data silo. The Field Library is the bridge between the form-building UI and the underlying data system.

5. The Field Library — User-Facing View of the Field System

The Field Library is the panel the user sees inside the form builder. It is a curated, mode-appropriate surface on top of the field architecture defined in vrm-data-system. It has two sections.

5.1 Global Fields (Politogy-Controlled)

The canonical UVP fields that Politogy has chosen to expose in Relationship Mode. These appear in every account automatically.

Locked definition. The user cannot rename, retype, or delete a global field.
Always selectable. Any user, in any account, can drag a global field onto any form.
Display label is Politogy-controlled. Politogy may adjust labels over time (e.g., “Mobile Phone” → “Cell Phone”). The user sees the current label; they cannot edit it on the form. Per-form caption text (the helper text below the field) is editable by the user — that is form-level copy, not field definition.
Validation is inherited. If the global voter_email field requires email-format validation, every form using it enforces that validation.
Exposure-controlled. A global field that Politogy hides at the data-exposure layer disappears from the Field Library in real time. The user never sees an empty slot or a lock icon.

Examples of Global Fields likely exposed to Relationship Mode forms: First Name, Last Name, Email, Mobile Phone, Mailing Address, City, State, ZIP, Date of Birth, Preferred Name.

Examples of Global Fields likely NOT exposed to Relationship Mode forms: Voter Registration ID, Party Registration, Vote History, Precinct (these are voter-file-derived and not appropriate for self-reported public capture).

The list of Relationship-Mode-exposed global fields is a Politogy configuration. It is not hard-coded.

5.2 My Custom Fields (Account-Scoped)

Fields the account has created for its own campaign-specific data needs. Scoped to the creating account. Invisible to other accounts. Visible to Politogy (per the field promotion architecture).

Created from inside the form builder (see Section 6) and immediately joined to the account’s custom field namespace.
Reusable across forms. Once created, a custom field is available to drag onto any subsequent form.
Cannot be duplicated. The system rejects attempts to create a second custom field with the same name in the same account. The intent is reuse, not proliferation.
Can be removed from a form at any time. This removes the field from this specific form’s canvas but does not delete the field from the Field Library.
Cannot be deleted from the account if it has data. Once any UVP has a value written to a custom field, that field is permanent. (See Section 11 for full deletion rules.)
Can be edited (label, options) under restricted conditions. Label is always editable. Field type cannot change once data exists. Dropdown/radio/checkbox options can be added freely; existing options that have data cannot be deleted, only deactivated.

5.3 What the Library Does NOT Show

The user never sees:

Politogy-internal fields (Aggregate Intelligence layer, computed propensity scores, internal flags)
Global fields that Politogy has set to “Internal Only” or “Embargoed” exposure
Custom fields belonging to other accounts
Layered system metadata (provenance, source, timestamp, confidence)

These exist on the UVP but are not appropriate for self-report capture.

6. Creating a Custom Field From Inside the Builder

This is where the user’s workflow most directly touches the foundational data system, so it is specified in detail.

6.1 The “Add Field” Flow

User clicks + Add Custom Field in the Field Library panel.
A modal opens with:
- Field Label (what the form respondent sees, e.g., “Most important issue”)
- Field Type (single-select dropdown: see Section 6.2)
- Internal Name (auto-generated from label, e.g., most_important_issue; user can edit but not duplicate an existing internal name)
- Options (only when type is Dropdown, Radio, or Checkbox — repeatable rows)
- Required? (boolean — this is a per-form setting, not a field-level setting; surfaced here as a default)
- Description / Help Text (optional)
On Save: the field is added to the account’s custom field namespace AND appears on the current form canvas in the position where the user is working.
The system runs a duplicate check against existing custom fields by internal name AND by semantic similarity of label. If a likely duplicate is detected, the user is shown the existing field and prompted to use it instead.

6.2 Supported Field Types (V1)

Type	UI	UVP Storage	Validation
Short Text	Single-line input	string	Max length configurable
Long Text	Multi-line textarea	string	Max length configurable
Email	Single-line input	string	Email format required
Phone	Single-line input with country code	string (E.164 normalized)	Phone format required
Number	Numeric input	number	Min/max optional
Date	Date picker	date (ISO)	None
Dropdown	Single-select dropdown	string (one of options)	Must match an active option
Radio	Single-select radio group	string (one of options)	Must match an active option
Checkbox (single)	Single yes/no checkbox	boolean	None
Checkbox (multi-select)	Multi-checkbox group	array of strings	All values must match active options
Address Block	Composite (street/city/state/zip)	structured address	USPS validation downstream
Hidden	Not rendered	string	Pre-populated via URL parameter or embed config

V2 deferred: File upload, signature capture, conditional logic, multi-page forms, ranking, matrix questions.

6.3 Field Promotion Pathway

Custom fields created via Forms enter the same Politogy field-promotion pipeline defined in vrm-data-system §5.3. If 35 accounts create a custom field labeled “Most important issue” / “Top issue” / “Issue interest,” Politogy can promote it to a global field. After promotion, all newly-built forms in all accounts get the promoted field as a native global option, and the historical custom-field data is migrated.

This is why duplicate prevention and naming hygiene matter at the form-builder level — clean custom-field creation is the input to the AI promotion model.

7. The Three-Tab UI

The Forms feature uses a three-tab navigation, matching Ben’s existing UI pattern.

7.1 Tab 1 — Forms (Live & Draft)

Default landing tab. Two stacked sections:

Live Forms — published forms accepting submissions. Each row shows: form name, publish date, submission count (last 7d / total), conversion indicator, status pill, action menu.
Draft Forms — forms under construction, not yet published. Each row shows: form name, last edited, completeness indicator, action menu.

Each row is clickable. Clicking a Live Form opens the Form Detail View with submission count, recent submissions preview, and quick-stats (submissions over time, top sources, top values for key fields). Clicking a Draft Form opens the Canvas tab loaded with that form.

Actions per row: Edit, Duplicate, View Submissions, Embed Code, Copy Link, Archive, Delete (drafts only).

7.2 Tab 2 — Canvas (Builder)

The form-building workspace. Uses Frames to organize the tools:

Frame A — Form Settings (top, collapsible)

Form name, internal description, status (draft / live), tags. This is the form’s metadata.

Frame B — Field Library (left rail)

Two collapsible sections: Global Fields and My Custom Fields. Drag handles on each field. Search bar at top. + Add Custom Field button at the bottom of the Custom Fields section. Fields already on the current canvas are visually marked as “in use” (not greyed — still draggable, in case the user wants the same field twice for layout reasons; the system de-duplicates on save).

Frame C — Canvas (center, primary workspace)

The drag-and-drop construction area. Renders the form roughly as it will appear when published. Each placed field shows a handle for reordering, an edit handle for per-form caption text and required/optional toggle, and a remove button (which removes from form, never deletes the field). Submit button is always present at the bottom. A “Form Header” element (title + subtitle) sits at the top by default.

Frame D — Style & Branding (right rail, collapsible)

Brand color (defaults to account’s accent color)
Logo (account default or upload)
Background style (solid, image, gradient)
Font (account default or override)
Button style
Confirmation message
Redirect URL (post-submit)
Custom CSS (advanced — collapsed by default)

Frame E — Publish & Distribute (right rail, separate frame)

Public link (copy button, optional vanity slug)
Embed code (copy button, iframe + optional script)
QR code (download button)
Open Graph preview (image, title, description for social sharing)
Status toggle (Draft / Live)

Frame F — Anti-Abuse (right rail, advanced, collapsed by default)

CAPTCHA (on / off / threshold)
Honeypot field (auto, hidden)
Rate limiting (submissions per IP per hour)
Geo restrictions (optional)

Consent line (editable; defaults to a Politogy-provided template)
Privacy policy URL (required)
TCPA disclosure (required if a Phone field is on the form)
Opt-in mechanism (single opt-in / double opt-in)

Consent capture is non-negotiable. A form cannot be set to Live without consent configuration complete.

7.3 Tab 3 — Submissions

The data view. Shows submissions across all forms (filterable by form), in a table:

Submission date / time
Form name
Submitter name / email (or “Anonymous” if not captured)
Match status (matched to existing UVP / new UVP created / pending review)
Per-field values (configurable columns)
Source URL (where the form was embedded or referred from)
Actions: View detail, Open UVP, Flag, Delete (submission only, with audit log)

The submissions table is filterable, searchable, exportable to CSV (subject to data exposure rules), and click-through to the source UVP. The single most important interaction in this tab is click any submission → open the resulting UVP record in the standard UVP detail view. This is what makes Forms feel like part of the platform and not a bolt-on tool.

8. The Submission Pipeline — From Web Submit to UVP Write

This is the backbone of the feature. It happens on every submission, in this order.

Step 1 — Capture

Form is rendered (hosted page or embed). User completes fields. Client-side validation runs. User clicks Submit. Honeypot and CAPTCHA evaluated. Submission payload is transmitted to VRM.

Step 2 — Validate

Server re-validates every field against its definition (global field rules + custom field rules). Consent confirmed. Required fields confirmed. If validation fails: submission rejected with a user-facing error. No partial writes.

Step 3 — Identity Match

The system attempts to resolve the submission to an existing UVP using a priority chain:

Email match (exact, case-insensitive)
Phone match (E.164 normalized)
Name + address match (fuzzy on name, exact on address)
Name + DOB match (if both present)

If a unique match is found → match outcome. If multiple plausible matches → pending review outcome (flagged for user adjudication; submission held in a quarantine state). If no match → new UVP outcome (a Relationship-sourced UVP record is created).

Step 4 — Write

The submission data is written to the UVP per the priority rules in vrm-data-system §2.2:

User-submitted data takes priority over voter-file and enrichment for the same fields.
Previous values are preserved as alternates with full provenance.
Provenance metadata recorded: form ID, submission ID, IP address, timestamp, source URL, consent record.

Step 5 — Tag & Notify

The new submission is automatically tagged with the form’s tags.
Account users with notification subscriptions are alerted.
If integration webhooks are configured, the submission payload is pushed (V2 — webhooks deferred from V1).

Step 6 — Confirm

The submitter sees the form’s confirmation message (or is redirected to a configured URL). Double opt-in: a confirmation email is dispatched and the UVP carries an “unconfirmed” flag until the confirmation link is clicked.

8.1 The “New UVP Outcome” Detail

When a form submission creates a new UVP, it is tagged at the source level as Relationship-Sourced (as distinct from Voter-File-Sourced). This matters because:

These UVPs do not have Identity Core data from the state voter file. They have only what the submitter provided.
They are eligible for future voter-file matching. If a later voter file import finds a record matching the submission’s name + address + DOB, the records merge per the data merge rules.
They are full-fledged UVPs from day one — they participate in segmentation, Surveys, Relationship Mode workflows, and (if the account upgrades) Campaign Mode where applicable.

9. Form States & Lifecycle

A form moves through a defined state machine.

State	Meaning	Accepts Submissions	Editable
Draft	Under construction	No	Fully
Live	Published, accepting submissions	Yes	Restricted (see below)
Paused	Was Live, temporarily off	No	Fully
Archived	Retired, kept for historical reference	No	No

9.1 Editing a Live Form

Once a form has accepted at least one submission, certain edits are restricted to protect data integrity:

Cannot change the type of a field that has been submitted against (e.g., dropdown → text).
Cannot remove a custom field from a form if doing so would orphan the only place it is being collected. (Soft warning — user may proceed, but is told the field will be deactivated for new collection.)
Cannot delete options from a dropdown/radio/checkbox if any submission has used that option. (Options may be deactivated — hidden from new submissions, retained for historical data.)
Can rename labels and captions freely.
Can add new fields freely.
Can reorder fields freely.
Can restyle and rebrand freely.

The intent: published forms behave predictably for ongoing submitters and for downstream data consumers, while still being responsive to campaign needs.

9.2 Archiving vs. Deletion

A form can be Archived (soft retirement, all data retained, can be unarchived) but cannot be hard-deleted once it has submissions. The form record is permanent because the submissions reference it as a provenance source on the UVP.

A form with zero submissions can be hard-deleted from the Draft state.

10. Versioning

When a Live form is edited, the system stores a version snapshot. Every submission carries a reference to the form version it was submitted under. This means:

Historical submissions remain interpretable even if the form is later restructured.
Reports and exports can be filtered by form version.
Provenance on the UVP is precise: “Captured via Form X, version 3, on 2026-04-12.”

V1: lightweight version log (timestamps + diff summary). V2: full visual version comparison.

11. The Field Deletion Rules (Stated Plainly)

This is one of the points Ben specifically called out, so it gets its own section.

11.1 Global Fields

A user cannot delete a global field. Ever.
A user can remove a global field from a specific form’s canvas. The field continues to exist in the Field Library and on every UVP.

11.2 Custom Fields — Three Conditions

Condition	Can Delete From Account?	Can Remove From Form?
Field has zero data on any UVP	Yes	Yes
Field has data on one or more UVPs	No	Yes
Field has been promoted to a global field	No (now a global field, see 11.1)	Yes

11.3 Why Field-In-Use Is Undeleteable

Three reasons, in priority order:

Data integrity. Deleting a field with data orphans values on UVPs, breaks export integrity, and corrupts the audit log.
UVP value preservation. Custom-collected data is high-signal user-generated data, the highest-value layer in the system. Letting users delete it is letting them delete the platform’s asset.
Promotion feedstock. Politogy’s AI watches custom field usage across accounts to find promotion candidates. A field that disappears from an account is a missing data point in the promotion model.

What the user CAN do:

Stop collecting the field by removing it from all forms.
Rename the field label (does not affect underlying data column).
Deactivate dropdown options without losing historical responses.
Request Politogy assistance for a true data deletion (a support workflow, not a self-serve action — and only for compliance reasons like a verified GDPR-style erasure request, which is handled at the UVP level, not the field level).

12. Branding, Styling & Templates

12.1 Account-Level Defaults

Each account has a default brand kit: logo, primary color, font, button style, confirmation message template. New forms inherit these defaults automatically. Most users never touch the Style frame — defaults just work.

12.2 Per-Form Overrides

The Style frame allows per-form override of any default. Overrides are isolated to that form. A form can be themed for a specific campaign (e.g., dark mode for a late-night event signup) without disturbing the account defaults.

12.3 Templates (V1)

A small Politogy-curated set of starter templates, each pre-configured for a common Relationship Mode use case:

Contact Form (name, email, message)
Event RSVP (name, email, phone, attending count)
Newsletter Signup (name, email)
Volunteer Signup (name, email, phone, skills, availability)
Donation Lead (name, email, phone, suggested donation tier)

Each template is built from global fields only; the user can extend with custom fields after starting from a template.

12.4 White-Label and Cross-Account Templates (V2)

Account-saved templates (a user saves their own form as a template for re-use across the account) and white-label theming for agencies managing many accounts are V2.

13. Distribution & Embedding

13.1 Hosted Public Link

Every form gets a URL on the Politogy VRM forms domain (e.g., forms.politogyvrm.com/<account>/<slug>). Slug is editable. Politogy-hosted; respects the account’s brand.

13.2 Embed Code

Two embed flavors:

iframe embed — drop-in, isolated from host page CSS, works on any platform. Default.
JavaScript embed — inherits host page styles, can be positioned more flexibly, supports event callbacks for analytics. For more sophisticated implementations.

Both embeds support URL parameter pass-through into Hidden fields (e.g., ?source=newsletter populates a hidden source field on the submission).

13.3 QR Code

Auto-generated QR code per form, downloadable as PNG and SVG, with optional logo overlay using the account brand kit.

13.4 Open Graph Metadata

Per-form OG image, title, and description so that when a form link is shared on social platforms, the preview is branded and contextual.

14. Analytics & Stats

The Form Detail View (Section 7.1) and the Tab 1 row-level stats surface a core analytics set:

Submissions over time (daily / weekly / monthly bars)
Conversion rate (where measurable — requires JS embed for view counting)
Top sources (referring URL or source parameter)
Field completion rates (which fields users abandon on)
Match rate (of submissions, % matched to existing UVPs vs. created new)
Top values for low-cardinality fields (e.g., top 5 issue selections)

V1 keeps this lightweight and on-page. Cross-form analytics, funnels, and cohort analysis are V2.

15. Permissions

Form access follows the standard role matrix from vrm-data-system §12, applied to form objects.

Role	Create Form	Edit Form	View Submissions	Export Submissions	Manage Custom Fields
Account Admin	Yes	All	All	Yes	Yes
Account Manager	Yes (within scope)	Own + assigned	Within scope	Within scope	Yes
Field User	No	No	Assigned forms	No	No
Viewer	No	No	Read-only	No	No

Custom field creation specifically is gated to Admin and Manager roles. This prevents low-trust users from polluting the account’s custom field namespace.

16. V1 / V2 Scope Summary

V1 (Ship)

Three-tab UI (Forms / Canvas / Submissions)
Drag-and-drop builder with frames
Global field selection from Politogy-controlled Relationship Mode whitelist
Custom field creation with all V1 types (Section 6.2)
Identity matching (4-step priority chain)
Form versioning (lightweight)
Templates (5 starter)
Hosted link + iframe embed + JS embed + QR
CAPTCHA + honeypot + rate limiting
Consent capture (single + double opt-in)
Submission table with UVP click-through
Per-form analytics
Standard permissions

V2 (Defer)

Conditional logic (show/hide based on prior answers)
Multi-page forms
File upload, signature capture, ranking, matrix questions
Webhooks and outbound integrations
Account-saved templates
White-label theming
Cross-form analytics & funnels
Visual version comparison

V3+ (Aspirational)

A/B testing of form variants
AI-suggested field additions (“75% of similar campaigns also collect Mobile Phone — add it?“)
Auto-translation for multi-language forms
Voice-to-form (submit by phone IVR)

Developer Open Questions

These are real architectural decisions that need to be made before the engineering team can fully scope V1. Each is genuinely open.

Submission storage shape. Do we store submissions as a normalized event log (one row per field per submission) or a denormalized JSON blob per submission? The event log makes analytics and field-level reporting natural; the blob makes versioning and replay simpler. Recommendation needed.
Identity match adjudication UX. When a submission matches multiple existing UVPs (“pending review” outcome), where does the user see this? A queue in Submissions tab? A separate “Needs Attention” surface in Relationship Mode? Inline notification on the UVP? This shapes both the data model and the navigation.
Custom field type immutability — true or soft? The spec says you cannot change a field’s type once data exists. Should this be a hard system constraint, or a soft warning that lets the user proceed and dual-stores legacy values? Soft is more flexible; hard is cleaner. Recommend hard for V1.
Per-form required vs. field-level required. The spec treats “required” as a per-form setting (the same field can be required on Form A and optional on Form B). Confirm this is the desired behavior; the alternative is a field-level default with per-form override.
Politogy’s Relationship-Mode global-field whitelist. What is the actual starter list of global fields exposed to the Forms Field Library? Must be defined before V1 ships. Likely: First Name, Last Name, Preferred Name, Email, Mobile Phone, Mailing Address (composite), City, State, ZIP, Date of Birth. Confirm or revise.
New-UVP creation gate. Should creating a new UVP from a form submission require any threshold of provided data (e.g., must include at least Email OR Phone OR Name+Address)? Or is any submission with any field enough to create a record? Recommend a minimum threshold to prevent junk records.
TCPA / consent jurisdiction. Forms collecting phone numbers require TCPA disclosure. Are we localizing this by ZIP / state at submission time, or showing a universal disclosure? Legal recommendation needed.
Embed analytics requirement. Conversion rate analytics require view counting, which is only possible via the JS embed. Do we tell iframe-only users they cannot see conversion rate, or do we approximate via referrer logs? Affects what we promise in V1.
Anti-abuse defaults. CAPTCHA off by default with optional toggle, or CAPTCHA on by default with optional toggle? On-by-default is safer; off-by-default is friendlier. Recommend on-by-default with one-click disable for testing.
Form-level vs. field-level provenance on the UVP. When five forms write to the same Email field on the same UVP over time, the UVP provenance chain needs to record all five sources or only the most recent? Recommend all five, as a chain — every write preserved as an alternate with timestamp, latest is primary.
Hidden field abuse prevention. Hidden fields populated via URL parameter are useful but spoofable. Should hidden fields be signature-verified (e.g., HMAC of the parameter set) to prevent forgery? Adds friction for marketers; adds integrity for data.
Versioning depth. How many form versions do we retain? Forever (storage cost) or rolling N (loss of deep history)? Recommend forever, given that the storage cost is minor and the data integrity value is high.
Cross-form custom field reuse confirmation UX. When a user creates a custom field that semantically matches an existing one, the spec says they are prompted to use the existing one. What is the exact UX of that prompt? Modal? Inline suggestion? Hard block? Recommend a soft prompt with a “use existing” button and a “create anyway” override.
Submission edit / correction. Can an account user manually edit a submission after the fact (e.g., to fix a typo in a name)? If yes, does that re-trigger identity matching? Recommend: yes, edit allowed with audit log; re-trigger match if identity fields change.
Multi-form same-UVP behavior. If the same person submits the same form three times in a week, do we get three submission records or one updated submission? Recommend: three submission records (each is a distinct event), but one UVP with the latest values primary and prior values as alternates. Same applies across different forms by the same person.
Subscriber tier gating. Does the Forms feature have a free tier limit (e.g., 1 live form, 100 submissions/month on free; unlimited on paid)? Pricing model affects what we build for billing / usage tracking in V1.

End of Spec

This document is the V1 conceptual specification for VRM Forms in Relationship Mode. It is intentionally pared down to the conceptual layer; data model details, API surface, and UI specifications follow in implementation specs derived from this document.

The North Star: forms feel simple to the user, are powerful in the backend, and every submission strengthens the UVP. If a proposed feature does not serve that triad, defer it.

🗳️ Politogy VRM — V2 Specs

Explorer