Référence de la définition de formulaire

Une définition de formulaire est le JSON qui décrit un formulaire : ses champs, ses étapes, ses conditions, ses limites et ses réglages antipourriel. Le constructeur l’écrit pour vous, et le serveur l’applique à chaque soumission. Utilisez cette page quand vous avez besoin du nom ou de la valeur exacte d’un réglage.

Chaque exemple ci-dessous est un correctif de définition. Chaque clé de premier niveau que vous envoyez remplace toute cette clé, et les clés que vous omettez restent telles quelles. Pour ajouter un champ, envoyez tous les champs existants et le nouveau.

Ces clés de premier niveau peuvent être modifiées : fields, steps, contentBlocks, conditions, visibilityRules, validationRules, limits, spam, verification, settings, allowedOrigins et primaryPublicTarget.

Les destinataires, les expéditeurs et les courriels de notification ne font pas partie de ce correctif. Réglez-les dans les onglets Livraison et Modèles du formulaire. Consultez Premiers pas.

Noms et chemins des champs

fields associe un nom de champ à sa définition. Les noms utilisent des lettres, des chiffres, _ et -.

Les autres réglages désignent un champ par son chemin :

Un chemin qui n’existe pas échoue avec FORM_CONFIG_FIELD_REF_UNKNOWN.

Types de champs

type prend l’une de ces douze valeurs. Toute autre valeur, comme file ou signature, échoue avec FORM_CONFIG_FIELD_TYPE_INVALID.

Les questions d’évaluation et les curseurs du constructeur sont des champs number. Il n’y a pas de champ de téléversement de fichier ni de signature.

Options de tous les champs

{
  "fields": {
    "name": {
      "type": "string",
      "label": "Your name",
      "description": "As it appears on your invoice.",
      "placeholder": "Jane Example",
      "required": true,
      "messages": { "required": "Enter your name." }
    }
  }
}

Une defaultValue doit convenir au champ : un nombre fini sur number, true ou false sur boolean, une vraie date YYYY-MM-DD sur date, et une chaîne sur les autres types de texte. Avec allowedValues, elle doit en faire partie.

Champs de texte

Ces options fonctionnent sur string, textarea, email, url et phone, ainsi que sur date et select là où le tableau l’indique.

{
  "fields": {
    "reference": {
      "type": "string",
      "label": "Reference",
      "min": 4,
      "max": 20,
      "startsWith": "REF-",
      "pattern": "^REF-[0-9]+$"
    },
    "message": {
      "type": "textarea",
      "label": "Message",
      "required": true,
      "max": 5000,
      "trim": true
    }
  }
}

Texte masqué ou caché

Sur string seulement, inputType vaut password ou hidden. Il change l’affichage du champ. La validation le traite quand même comme une chaîne.

{
  "fields": {
    "access_code": { "type": "string", "label": "Access code", "inputType": "password" },
    "campaign": { "type": "string", "inputType": "hidden", "defaultValue": "spring" }
  }
}

Vérifications de format sur le texte

Ces options fonctionnent sur les champs string. countryCode et regionCodeCountry fonctionnent aussi sur select.

{
  "fields": {
    "postal_code": { "type": "string", "label": "Postal code", "postalCodeCountry": "CA" },
    "province": { "type": "select", "label": "Province", "regionCodeCountry": "CA", "allowedValues": ["QC", "ON"] },
    "pickup_time": { "type": "string", "label": "Pickup time", "timeFormat": "HH:mm" }
  }
}

Champs de courriel

Les réponses email sont toujours vérifiées, et échouent avec FIELD_EMAIL_INVALID. normalizeEmail met l’adresse en minuscules avant de la vérifier et de la conserver.

{
  "fields": {
    "email": { "type": "email", "label": "Email", "required": true, "max": 254, "trim": true, "normalizeEmail": true }
  }
}

Champs d’URL

Les réponses url sont toujours vérifiées, et acceptent http et https par défaut. Utilisez allowedProtocols pour changer cela. javascript, data et vbscript ne sont pas permis. Une mauvaise adresse échoue avec FIELD_URL_INVALID, et un autre protocole avec FIELD_URL_PROTOCOL_NOT_ALLOWED.

{
  "fields": {
    "website": { "type": "url", "label": "Website", "allowedProtocols": ["https"] }
  }
}

Champs de téléphone

Un champ phone accepte n’importe quel texte par défaut. phoneFormat accepte e164, qui exige un numéro comme +15145550123, et échoue avec FIELD_PHONE_INVALID.

{
  "fields": {
    "phone": { "type": "phone", "label": "Phone", "phoneFormat": "e164" }
  }
}

Champs numériques

Une valeur qui ne se lit pas comme un nombre échoue avec FIELD_TYPE_INVALID. min et max ne peuvent pas être négatifs, peu importe le type de champ.

{
  "fields": {
    "rating": { "type": "number", "label": "Your rating", "integer": true, "min": 1, "max": 5 },
    "budget": { "type": "number", "label": "Budget", "maxDecimalPlaces": 2 }
  }
}

Champs de date

Les réponses date doivent être de vraies dates au format YYYY-MM-DD. dateMin et dateMax prennent le même format et incluent la date indiquée.

{
  "fields": {
    "event_date": { "type": "date", "label": "Event date", "dateMin": "2027-01-01", "dateMax": "2027-12-31" }
  }
}

Champs de choix

Utilisez select pour un seul choix. Énumérez les choix dans allowedValues.

{
  "fields": {
    "department": { "type": "select", "label": "Department", "required": true, "allowedValues": ["Sales", "Support"] }
  }
}

Plusieurs choix

Utilisez checkbox avec allowedValues. minSelections et maxSelections fixent l’intervalle, et échouent avec FIELD_SELECTION_TOO_FEW et FIELD_SELECTION_TOO_MANY. defaultValue est une chaîne ou un tableau de chaînes de la liste.

{
  "fields": {
    "interests": {
      "type": "checkbox",
      "label": "Interests",
      "allowedValues": ["Workshops", "Newsletter", "Events"],
      "minSelections": 1,
      "maxSelections": 2,
      "defaultValue": ["Newsletter"]
    }
  }
}

Une seule case à cocher

Sans allowedValues, un checkbox est une seule case à cocher, et boolean fonctionne de la même façon. defaultValue vaut true ou false. Ajoutez accepted quand la case doit être cochée, par exemple pour un consentement. L’échec donne FIELD_ACCEPTED_REQUIRED.

{
  "fields": {
    "consent": { "type": "checkbox", "label": "I agree to the terms", "required": true, "accepted": true },
    "subscribe": { "type": "boolean", "label": "Send me the newsletter", "defaultValue": false }
  }
}

Groupes

type: "object" regroupe des champs sous un même nom. Il accepte label, description, required, messages et fields. Les groupes s’imbriquent sur au plus 8 niveaux. Les réponses arrivent sous forme d’objet, avec des chemins comme contact.email.

{
  "fields": {
    "contact": {
      "type": "object",
      "label": "Contact",
      "fields": {
        "name": { "type": "string", "label": "Name", "required": true },
        "email": { "type": "email", "label": "Email", "required": true }
      }
    }
  }
}

Listes

type: "array" répète un élément. item contient n’importe quel type de champ, y compris un groupe.

{
  "fields": {
    "guests": {
      "type": "array",
      "label": "Guests",
      "minItems": 1,
      "maxItems": 5,
      "item": {
        "type": "object",
        "fields": {
          "name": { "type": "string", "label": "Guest name", "required": true }
        }
      }
    }
  }
}

Nettoyage des réponses

Les traitements nettoient une réponse avant sa validation. Le résultat est la valeur conservée et livrée. Ils fonctionnent sur string, textarea, email, url, phone, date et select, et un champ peut en avoir jusqu’à 25 de chaque sorte.

Les sanitizers passent d’abord, puis trim, collapseWhitespace et normalizeEmail, puis les transformers, puis caseTransform.

{
  "fields": {
    "province": {
      "type": "string",
      "label": "Province",
      "sanitizers": [{ "type": "trim" }, { "type": "collapseWhitespace" }],
      "transformers": [{ "type": "case", "mode": "upper" }, { "type": "map", "values": { "QC": "Québec" } }]
    }
  }
}

Options raccourcies

Pipelines

pipeline exécute les nettoyages, les transformations et les validateurs dans une seule liste que vous ordonnez vous-même. Il ne se combine pas avec sanitizers, transformers, validators, trim, collapseWhitespace, normalizeEmail ni caseTransform, échoue alors avec FORM_CONFIG_FIELD_OPTION_CONFLICT, et exige au moins une étape. L’onglet Traitement de l’application affiche un pipeline sans permettre de le modifier : préférez donc les deux listes ci-dessus.

{
  "fields": {
    "code": {
      "type": "string",
      "label": "Code",
      "pipeline": [
        { "step": "sanitizer", "sanitizer": { "type": "trim" } },
        { "step": "validator", "validator": { "type": "startsWith", "value": "A", "code": "CODE_PREFIX", "message": "Start the code with A." } },
        { "step": "transformer", "transformer": { "type": "case", "mode": "lower" } }
      ]
    }
  }
}

Validateurs

Ajoutez des vérifications à un champ de texte avec validators. Chacune exige un type, un code en majuscules comme CUSTOM_POSTAL_CODE, et le message à afficher. Les réponses de validation renvoient votre code et votre message.

{
  "fields": {
    "postal_code": {
      "type": "string",
      "label": "Postal code",
      "validators": [
        { "type": "postalCode", "country": "CA", "code": "CUSTOM_POSTAL_CODE", "message": "Enter a valid postal code." }
      ]
    },
    "sku": {
      "type": "string",
      "label": "Product code",
      "validators": [
        { "type": "regex", "pattern": "^[A-Z]{3}-[0-9]{4}$", "code": "CUSTOM_SKU", "message": "Use a code such as ABC-1234." }
      ]
    }
  }
}

Conditions

Une condition est vraie ou fausse pour un ensemble de réponses. Elle sert aux règles de visibilité, aux règles de validation, aux étapes et aux blocs de contenu.

Combinez les conditions avec all, any et not. Une condition s’imbrique sur au plus 5 niveaux, et un groupe contient au plus 25 conditions. Un groupe vide échoue avec FORM_CONFIG_CONDITION_REQUIRED.

L’exemple suivant est complet. Il affiche details quand type vaut Commercial et que size dépasse 10, ou quand type n’est pas rempli.

{
  "fields": {
    "type": { "type": "select", "label": "Type", "allowedValues": ["Personal", "Commercial"] },
    "size": { "type": "number", "label": "Team size" },
    "details": { "type": "textarea", "label": "Details" }
  },
  "visibilityRules": [
    {
      "id": "show-details",
      "path": "details",
      "default": "hidden",
      "state": "visible",
      "when": {
        "any": [
          { "all": [
            { "path": "type", "operator": "equals", "value": "Commercial" },
            { "path": "size", "operator": "greaterThan", "value": 10 }
          ] },
          { "not": { "path": "type", "operator": "isFilled" } }
        ]
      }
    }
  ]
}

Conditions nommées

conditions conserve jusqu’à 100 conditions par nom, pour les réutiliser dans l’application. Chacune a un id et, au besoin, un label d’au plus 200 caractères, une description d’au plus 2 000 caractères et un when. Une règle garde sa propre copie de la logique : une condition nommée ne change donc pas le comportement d’un formulaire.

{
  "fields": {
    "type": { "type": "select", "label": "Type", "allowedValues": ["Personal", "Commercial"] }
  },
  "conditions": [
    {
      "id": "is-commercial",
      "label": "Commercial project",
      "when": { "path": "type", "operator": "equals", "value": "Commercial" }
    }
  ]
}

Règles de visibilité

Une règle de visibilité affiche ou masque un champ ou un groupe. Quand when est vrai, le champ prend state. Sinon, il prend default, qui vaut visible si vous l’omettez. Un formulaire peut avoir jusqu’à 100 règles, à raison d’une règle par champ.

Le serveur applique aussi ces règles. Les réponses à un champ masqué sont abandonnées, et ses vérifications ne s’exécutent pas.

{
  "fields": {
    "meal": { "type": "select", "label": "Meal", "allowedValues": ["Standard", "Other"] },
    "meal_details": { "type": "string", "label": "Tell us more" }
  },
  "visibilityRules": [
    {
      "id": "show-meal-details",
      "path": "meal_details",
      "default": "hidden",
      "state": "visible",
      "when": { "path": "meal", "operator": "equals", "value": "Other" }
    }
  ]
}

Règles de validation

Une règle de validation vérifie un champ seulement quand une condition est vraie. then contient jusqu’à 25 actions, chacune avec un path et un validator. Un formulaire peut avoir jusqu’à 100 règles.

Le validator est n’importe quel type de la section Validateurs, ou l’un de ceux-ci :

Chacun exige un code et un message. Les listes allOf et anyOf contiennent jusqu’à 25 validateurs et s’imbriquent sur au plus 3 niveaux.

{
  "fields": {
    "type": { "type": "select", "label": "Type", "allowedValues": ["Personal", "Commercial"] },
    "company": { "type": "string", "label": "Company" }
  },
  "validationRules": [
    {
      "id": "company-if-commercial",
      "when": { "path": "type", "operator": "equals", "value": "Commercial" },
      "then": [
        {
          "path": "company",
          "validator": { "type": "required", "code": "COMPANY_REQUIRED", "message": "Enter the company name." }
        }
      ]
    }
  ]
}

Étapes

steps regroupe les champs en pages. À partir de deux, les pages hébergées et les intégrations par script en affichent une à la fois, avec Suivant, Précédent et un compteur. Un formulaire peut avoir jusqu’à 50 étapes.

La soumission vérifie toujours tout le formulaire. Consultez Sections et formulaires à étapes.

{
  "fields": {
    "name": { "type": "string", "label": "Name", "required": true },
    "email": { "type": "email", "label": "Email", "required": true },
    "attending": { "type": "boolean", "label": "Will you attend?" },
    "meal": { "type": "select", "label": "Meal", "allowedValues": ["Standard", "Vegetarian"] }
  },
  "steps": [
    { "id": "about", "label": "About you", "summary": "How to reach you.", "fields": ["name", "email", "attending"], "validateOn": "stepSubmit" },
    {
      "id": "seat",
      "label": "Your seat",
      "fields": ["meal"],
      "visibleWhen": { "path": "attending", "operator": "equals", "value": true }
    }
  ]
}

Blocs de contenu

Un bloc de contenu place du texte ou un séparateur parmi les champs. Il ne contient aucune réponse : il n’atteint donc jamais la validation, les soumissions ni les courriels. Un formulaire peut en avoir jusqu’à 100.

{
  "fields": {
    "name": { "type": "string", "label": "Name" },
    "seats": { "type": "number", "label": "Seats", "integer": true, "min": 1 }
  },
  "contentBlocks": [
    { "id": "intro", "type": "text", "title": "Seats are limited", "body": "Register early to save your spot.", "before": "name" },
    { "id": "divider", "type": "separator", "after": "name" },
    {
      "id": "group-note",
      "type": "text",
      "body": "We'll contact you about group rates.",
      "after": "seats",
      "visibleWhen": { "path": "seats", "operator": "greaterThan", "value": 5 }
    }
  ]
}

Limites

limits accepte duplicateWindowSeconds, rateLimits et quotas. Toute autre clé fait échouer toute la requête avec BAD_REQUEST. Consultez Limites et protection antipourriel pour ce que fait chacune.

{
  "limits": {
    "duplicateWindowSeconds": 300,
    "rateLimits": [
      { "id": "per-visitor", "scope": "ipHash", "windowSeconds": 600, "max": 10 },
      { "id": "whole-form", "scope": "form", "windowSeconds": 3600, "max": 300 }
    ],
    "quotas": [
      { "id": "cap", "scope": "form", "period": "lifetime", "maxAccepted": 200, "message": "Registration is full." }
    ]
  }
}

Le code de réponse reste RATE_LIMITED ou FORM_QUOTA_REACHED, peu importe le contenu de message.

Les dates d’ouverture et de fermeture ne font pas partie de limits. Réglez-les sous Fenêtre de réponse, dans l’onglet Publication.

Vérifications antipourriel

{
  "spam": {
    "honeypotField": "_formerie_hp",
    "minSubmitTimeMs": 1000,
    "maxLinks": 3
  }
}

Vérification humaine

{
  "verification": {
    "provider": "turnstile",
    "mode": "managed",
    "required": true
  }
}

Avec vos propres clés, saisissez la clé secrète dans l’application, sous Vérification humaine, dans les Paramètres du formulaire. Elle est chiffrée, et elle reste en place quand vous changez le reste de verification avec le même fournisseur. Tant qu’aucune clé n’est enregistrée, required doit rester à false, comme dans cet exemple, sinon le changement échoue avec FORM_CONFIG_VERIFICATION_SECRET_REQUIRED.

{
  "verification": {
    "provider": "recaptcha-v3",
    "mode": "custom",
    "required": false,
    "siteKey": "your-public-site-key",
    "minScore": 0.5,
    "expectedAction": "contact"
  }
}

Origines autorisées

allowedOrigins énumère les sites dont le code de navigateur peut appeler directement le formulaire. Chaque entrée est une origine exacte, sans chemin ni caractère générique. Consultez Origines autorisées pour savoir quand elles sont nécessaires.

{
  "allowedOrigins": ["https://www.example.com", "https://example.com", "http://localhost:5173"]
}

Adresse publique

primaryPublicTarget fixe l’adresse principale du formulaire.

{
  "primaryPublicTarget": {
    "kind": "runtimeHostname",
    "hostname": "forms.example.com",
    "bindingKind": "workspace"
  }
}

Comportement du formulaire

settings.behavior contient ce qui se passe autour des champs. settings se remplace au complet : envoyez donc behavior, branding et layout ensemble.

Image de marque

settings.branding donne son style à la page hébergée et à l’intégration par script.

Chaque thème accepte accentColor, accentTextColor, backgroundColor, borderColor, errorColor, errorTextColor, fieldBackgroundColor, mutedTextColor, surfaceColor et textColor.

Le CSS personnalisé n’est pas appliqué aux pages hébergées.

Mise en page

settings.layout fixe la largeur de la page hébergée.

{
  "settings": {
    "behavior": {
      "language": "fr-CA",
      "submitButtonLabel": "Envoyer",
      "successMessage": "Merci, nous vous répondrons sous peu."
    },
    "branding": {
      "brandName": "Example",
      "density": "comfortable",
      "fontPreset": "inter",
      "previewTheme": "light",
      "radius": "soft",
      "themes": { "light": { "accentColor": "#007c72" } }
    },
    "layout": { "containerWidthMode": "custom", "containerMaxWidth": "44rem" }
  }
}

Limites de taille

Lire les erreurs de définition

Une définition refusée renvoie VALIDATION_FAILED avec issues, et chaque problème a un path, un code stable et un message. Corrigez ces chemins et envoyez de nouveau le correctif.