Validating flow schemas

Ensure form variants stay conformant to a defined schema.

Flow schemas allow you to define sets of answers that must appear within a flow. If any of the answers are missing, or are of the wrong type, content authors will be prevented from deploying.

As an example, if you have an onboarding flow, it is likely that a downstream consumer of the flow's information would consume a specific set of required fields, such as user_name, email, date_of_birth, etc. A flow schema for this object can be made, capturing that external dependency.

This gives developers working with teams that use Formsort confidence that less-tech savvy content authors do not accidentally remove critical information from a form flow while they make changes and run experiments. Roles and permissions can be further used to enforce that users don't make changes they should not be able to make.

Defining flow schemas

To add a schema, first, go to the SCHEMAS tab within a flow:

Then, name your schema. Here we create a schema that will contain all the information that we need to create an account:

Once a schema is created, a new revision can be made. Here, the properties that the schema requires can be defined:

At this point, the schema has been defined, and is enabled by default.

Here, it's possible to view the schema in Typescript...

interface AccountInfo {
  first_name: string;
}

... as well as JSON schema formats.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AccountInfo",
  "description": "Everything needed to create an account",
  "type": "object",
  "required": [
    "first_name"
  ],
  "properties": {
    "first_name": {
      "type": "string"
    }
  }
}

Verifying that a flow conforms to a schema

Once a schema has been defined and is enabled, any attempt to publish any variant within the flow must conform to all schemas defined within.

Missing values

If a flow does not collect an answer, deployment will be prevented:

Incorrectly-typed values

If a flow contains an answer keyed with one of the schema properties, but the answer is not of the correct type, deployment will be blocked:

Keep in mind that partials of the schema values may be sent as the responder completes the flow - since questions collecting the answers can be spread across multiple steps.

Updating a flow schema

To help with schemas that evolve over time, schema revisions are versioned using semantic versioning.

Since deployment of Formsort revisions cannot be precisely timed with the deployment of downstream services that consume data from Formsort, for maximum safety, the process of updating a schema should proceed as follows:

• Define a new revision of the schema.

• Deploy all variants compliant to the new schema.

  • These variants should be compliant with both new and old revisions of the schema. Use calculated variables if you need to alias any fields.

• Remove support for the previous revision of the schema from downstream services.

• Disable the previous revision of the schema.

• Republish any variants

Additive changes

Adding a property to an existing schema is a non-breaking change: existing consumers will be happy, since they can be unaware of the new property.

Changes like this represent minor version updates (0.1 -> 0.2)

Breaking changes

Removing a property, or changing its type, is a breaking change: existing consumers may break, since they expect the value to be present or typed a certain wait.

Changes like this represent major version updates (0.1 -> 1.0)

Schema events

Coming soon!

In the future, we will emit events whenever a schema's fields become completed, change, or become incomplete.

Disabling a flow schema

If you no longer need to enforce a schema, disable each of the schema's revisions.