JSON schemas

Exporting form payload metadata for validation or analysis.

Every variant revision is available as a JSON schema (Draft 07), which describes the possible answer payloads that a flow may produce. Exporting this JSON allows you to write validators on your end, or understand the possible payloads that a flow may produce using the many tools that use the JSON Schema format.

Sample form schemas

Each of these examples shows how a form that only collected a single answer would be respresented in a JSON schema

string

{
  '$schema': 'http://json-schema.org/draft-07/schema#',
  'type': 'object',
  'properties': {
    'user_fname': {
      'type': 'string',
      'description': 'The first name of the user'
    }
  }
}

select (single)

{
  '$schema': 'http://json-schema.org/draft-07/schema#',
  'type': 'object',
  'properties': {
    'A choice': {
      'oneOf': [
        {'const': 'Value A'},
        {'const': 'Value B'}
      ]
    }
  }
}

select (multiple)

{
  '$schema': 'http://json-schema.org/draft-07/schema#',
  'type': 'object',
  'properties': {
    'A choice': {
      'type': 'array',
      'items': {
        'oneOf': [
          {'const': 'Value A'},
          {'const': 'Value B'}
        ]
      }
    }
  }
}

address

Note that address is the only current object answer type with a distinct object type definition. Custom object types will be supported in the future.

{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "type":"object",
   "definitions":{
      "address":{
         "type":"object",
         "properties":{
            "raw":{
               "type":"string"
            },
            "address_1":{
               "type":"string"
            },
            "address_2":{
               "type":"string"
            },
            "city":{
               "type":"string"
            },
            "state":{
               "type":"string"
            },
            "postal_code":{
               "type":"string"
            },
            "country":{
               "type":"string"
            }
         },
         "required":[
            "address_1",
            "city",
            "state",
            "postal_code"
         ]
      }
   },
   "properties":{
      "An address":{
         "type":"array",
         "items":{
            "$ref":"#/definitions/address"
         }
      }
   }
}

Note that none of the root object properties are marked required: if you are receiving events with answers on every step, you may receive partial payloads, so you cannot assume the presence of any answer.

Accessing the JSON schema for a flow

The JSON schema for a given flow, variant, and revision combination is available at the following URL:

https://variant.formsort.com/flow-api/client/{CLIENT_ID}/flow/{FLOW_LABEL}/variant/{VARIANT_LABEL}/revision/{VARIANT_REVISION_UUID}/schema.json