Field types and schema.

Every form has a JSON Schema. It defines which fields exist, which are required, and how values are validated before a submission is accepted.

A basic schema

The schema is a standard JSON Schema object with a properties map and an optional required array. Field keys must match the input name attributes you send.

{
  "type": "object",
  "required": ["name", "email", "message"],
  "additionalProperties": false,
  "properties": {
    "name":    { "type": "string", "minLength": 1, "maxLength": 120 },
    "email":   { "type": "string", "format": "email" },
    "message": { "type": "string", "minLength": 10, "maxLength": 5000 },
    "topic":   { "type": "string", "enum": ["sales", "support", "other"] },
    "budget":  { "type": "number", "minimum": 0 }
  }
}

Supported types

Common formats

Use format for convenience validation: email, uri, date, date-time, time, and hostname. A field with format: "uri" is treated as a media upload field (see below).

Choice fields

Constrain a value to a fixed set with enum. This is what powers dropdowns, radio groups, and checkbox groups in the form builder.

{ "type": "string", "enum": ["sales", "support", "other"] }

Media fields

Mark a field as a file upload with the x-contact-media keyword. Add maxFiles, maxSizeMB, and allowedTypes to control limits per field. Use type: "array" for multiple files.

{
  "type": "object",
  "required": ["name", "attachment"],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "attachment": {
      "type": "string",
      "x-contact-media": {
        "maxFiles": 1,
        "maxSizeMB": 10,
        "allowedTypes": "image/*,application/pdf"
      }
    },
    "screenshots": {
      "type": "array",
      "items": { "type": "string", "x-contact-media": { "maxFiles": 5 } }
    }
  }
}

The value you send is the uploadId returned by the upload endpoint — not the file itself and not an arbitrary URL. See File uploads for the full flow.

Complexity limits

To keep validation fast and safe, schemas are bounded: at most 16 KB of JSON, roughly 500 nodes, a nesting depth of 12, and simple pattern expressions. Schemas beyond these limits are rejected with 422.

Practical tips

• Set additionalProperties: false to reject unexpected fields.
• Keep maxLength on free-text fields so messages stay within delivery limits.
• Add the hidden _website honeypot field to your HTML, but not to the schema.
• Changing a schema affects future submissions only; stored submissions keep their original data.