Comment on page
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.
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;
}
{
"$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"
}
}
}
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.
If a flow does not collect an answer, deployment will be prevented:
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.
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
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)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)Coming soon!
In the future, we will emit events whenever a schema's fields become completed, change, or become incomplete.
If you no longer need to enforce a schema, disable each of the schema's revisions.
Last modified 1yr ago