inputs blocks of a rater. Each type, rule and annotation becomes one key. A host is the application that collects the answers: a form, a conversation or an agent.
The contract follows JSON Schema draft 2020-12. The keys that start with x- are additions, and a JSON Schema validator ignores them. The rater’s own check of a request is the authority: the contract publishes each rule that JSON Schema has a keyword for, and lists the other rules as text.
Ask the questions a rater needs writes the annotations that this page reads back.
Get the contract
Save thequestions example and package it:
Rater.inputs shows the same contract as a table, with one row for each field.
Examples on this page
Most fragments on this page come from thequestions example, a renters rater. Examples shows its source.
The contract of the questions example
The contract of the questions example
household, a personal auto rater that imports a shared-facts package. A package is a file of inputs that several raters ask in common.
household/facts.rsl, the package
household/facts.rsl, the package
household/facts.rsl
Make enum reads its members from a CSV file:household/enums/Make.csv
household/rater.rsl, the rater
household/rater.rsl, the rater
household/rater.rsl
Rater.build("household/rater.rsl").input_schema returns its contract.
A third rater, host, carries the annotations that only tell a host how to show a question.
host/rater.rsl
host/rater.rsl
host/rater.rsl
Shape
The root of a contract is an object with these keys:
A request is an object with the root record’s name as its one key.
Rater.rate also takes the root record’s own fields.
Each declaration of the rater has one form in the contract:
A JSON
null means the same as an absent field. A list that may be empty has type: ["array", "null"] and default: []. A list with a minimum length has type: "array".
Required fields
Therequired key of a record lists the fields that every request gives. These fields stay out of it:
- An
Optionfield and a follow-up. - A field with
api_default. - A list that may be empty.
- An input that only a suggestion reads, such as
postal_codein thequestionsexample. It takes the form ofOption. - A shared fact that the rater’s outcomes and rules leave unread. It takes the form of
Optiontoo.
questions example:
Standard keys
An open bound publishes the nearest value inside the range.
where self in (0, 1] at precision: 0.01 publishes minimum: 0.01.
An enum member with a value of its own, such as own = "O", lists that value under enum.
From the questions example:
Type and rule keys
x-rsl-refinements appears on a record, a union record, a field or a list. An entry has code and message when its rule has them. A request that breaks a coded rule gets a refusal with that code.
Name [listed] = Enum lists the members under enum in place of x-rsl-enum.
A follow-up also adds an entry to the x-rsl-refinements of its record. From the questions example:
x-rsl-when is text for a reader. To learn which follow-ups a set of answers owes, rate with missing answers.
From the household example, a follow-up and a coded rule on a shared fact:
Question keys
A JSON object carries its keys in any order, so
x-order states the order of the declarations.
On a choice, x-group holds a part of the coverage screen in place of a section. Choice keys lists the parts.
From the questions example:
host example, the help of one value and a picker:
household example:
Templates
A template is text with placeholders in braces:x-ask, x-help and x-label may hold alternatives separated by |. A host takes the first alternative whose placeholders all have answers.
Date keys
A date expression starts with one of three bases:
today, the date of the conversation.- The name of a
Dateinput of the same record, such asstart. - A path from the root record, such as
Policy.start.
+ 1 year, - 6 months or + 30 days. A base that lacks an answer sets the bound aside.
formatMinimum and formatMaximum still hold the fixed range of the rater. A host applies both, so the narrower bound decides.
From the host example:
List keys
A field with
x-ref may carry x-labels for the values outside the keys of the list, such as 0.
The name that a host collects for x-item-name stays with the host. A request leaves it out.
From the questions example, the keys of the list beside its items:
host example:
household example, the same keys of two lists, and a field that names a driver:
Choice keys
A choice is something the person buys, such as a limit or a deductible.
A request that leaves a choice out buys its default. The shapes
included, tier and term carry x-shape alone, and a host matches them exactly.
Every choice carries x-group. A group that names one of the four parts, in any letter case, is the group. For any other choice, the shape and the record decide:
The
contents_limit of the questions example declares group: "Coverage" and has the shape limit, so its group is liability.
The contents_limit fragment under Standard keys is a limit choice. From the household example, a pair of limits:
Keys for answers a host fills
The rater works a suggestion out when it rates with missing answers. Results describes where a suggestion appears.
x-reduce is a list of parts separated by commas. A part is a position counted from 1, a range of positions such as 1-8, or a quoted character such as '0'. A host keeps those characters of the typed answer, in that order.
x-check has the form at P mod M ten C weights W… values L…:
- Each character has a value. A digit is its own value, and a letter has the value listed after
values, such asA1. - The check digit is the sum of each value times the weight at its position, modulo
M. - The character at position
Pequals the check digit.Cstands for a check digit of ten.
vin_pattern fragment under Question keys carries both keys.
From the questions example:
Document and checklist keys
In
x-documents, label is the kind with spaces for its underscores. when is the path of the root input whose gives names the kind. A kind with when absent is on offer from the start.
From the household example:
host example, a row with words for the person who answers, and an attestation:
Shared-fact keys
A rater that imports a package publishes these forms in its own way:
- A coded
where len(self) in [a, N]publishesx-max-declinein place ofmaxItems. - A coded
where self in [a, b]is an entry ofx-rsl-refinementsin place ofminimumandmaximum. - A shared fact that the rater narrows with
as T [code: …]keeps the range of the package asminimumandmaximum. - A follow-up carries
x-rsl-when-reads, and aCodetype carriesx-rsl-pattern. - A shared fact that the rater leaves unread is optional, in the form of
Option.
minimum and maximum, and a coded length as minItems and maxItems.
From the household example, the keys of a list with a coded maximum, and a Code type: