form that describes the current step: what to show, what to collect,
and what can be done next. Render it, collect input, and send events back.
Tolerate fields you do not recognize in responses. New ones may be added over
time.
Form
string
The step’s heading.
string[]
Labels for the steps leading to this one, outermost first, with the current
step last.
string[]
Form-wide error messages that are not tied to a single field.
Blocks
A block groups related content. It places no restriction on what it holds, so input, information, and explanatory text can sit side by side.string
A stable identifier for the block.
string
A heading for the block, if it has one.
object[]
Actions scoped to this block, in addition to the form’s own.
Items
Each item in a block has akind: field, data, or text.
Data
Adata item is a labeled, read-only value.
string
The human readable name for the data.
string
The value, already formatted for display, such as
$435.00.string
Secondary information about the value, such as a document’s type and page
count or a party’s role.
Text
Atext item is a paragraph of explanatory text, such as guidance or a note
about what the step does.
string
The text, as plain text with no formatting. Longer text arrives as several
text items, one per paragraph.Fields
Afield item is something to provide. Set a field’s value with a set_field
event that uses its key.
string
The key identifying the field. Use it as
field in set_field and search
events.string
The human readable label.
string
Help text to show with the field.
boolean
Whether the field must be filled before the step can advance.
boolean
Whether the field can currently be edited. A disabled field is usually waiting
on another field in the step.
boolean
Whether the value is a secret, such as a password or a payment detail.
Renderers should mask it, for example with a password input instead of a plain
text one.
string
The representation of the value. One of
string, number, bool, or file.object
Present, instead of
options, when the field takes one of a set of values too
large to send whole. See search.object[]
Rules a value you type should satisfy. See validations.
any
The current value, if there is one. A field that already has a value does not
need to be set again.
string[]
Problems with the current value that the server reported, if any.
string
A hint for browser autofill, as an HTML autofill token such as
cc-number or
billing address-line1. Renderers other than browsers can ignore it.string
A hint for the keyboard to prefer for a text field. One of
text, numeric,
decimal, tel, or email. Renderers other than browsers can ignore it.Options
A field withoptions takes one of a fixed set of values. Each option is an
object with a value, in the field’s ty representation, and a human readable
label. Set the field to an option’s value exactly as given. An empty list
means there is nothing to choose yet.
When a field has no options and no search, any value of its ty is allowed,
subject to its validations.
Search
Some sets of values are too large to send whole, such as the courts in Texas. A field like that hassearch instead of options. At most one of options and
search is present, and a field may use either depending on the court system, so
handle both.
string
The query that
results answer, if a search has been made.object[]
The values that match the query, each a
value and a label like an option.
The server caps how many it returns.object
The field’s current value with its label. This may not be among the
results,
so use it to show what is selected.integer
How many values match the query. When it is larger than the number of
results, the results were cut off. It is absent if the server cannot say.search event with a query. How a query matches is
up to the field. For courts, every word of the query must appear, in any case,
in a court’s name or code, so harris district finds Harris County district
courts. If total exceeds the number of results, make the query more specific
rather than choosing from a partial list. Then set the field to a result’s
value exactly as given, with a set_field event.
Searching does not set the field’s value, and it does change the session’s state
version like any other event. The server keeps the most recent query, so
resuming the session shows the same results.
Validations
Each validation is an object with alabel, the message for a value that breaks
the rule, and a rule with a kind:
rule
The value must match
pattern, a regular expression in JavaScript syntax.rule
The value must be a file whose extension is one of
extensions, lowercase and
without a leading dot, such as pdf.errors. Validations are often empty, and are not used when a field has
options.
Files
A field with aty of file takes a document. Its validations include an
extension rule that lists the accepted extensions. Set it with a set_field
event whose value is an object:
value has only file_name,
content_type, and size_bytes. The content is never returned.
The document travels in the request body, which can be up to 50 MB. Each court
also sets its own maximum attachment size, and a document over it is reported on
the form.
Actions
An action is something the filer can do. Invoke one with anaction event.
string
The ID of the action. Use it as
action_id in an action event.string
The human readable label.
boolean
Whether this is the step’s primary action, usually the one that submits the
step and advances.