How Forma works

Forma turns a request in plain language into an artifact — a chart, a figure — and tells you whether it holds up. Every answer is checked against a versioned set of rules before it is returned to you.

The contract

1. You send an intent to an oracle — a named service for one kind of artifact, such as chart, vector-graphics or coverage-policy: what you want, in plain language.
2. You get back a verdict. valid comes with the artifact. invalid comes with the reason it was refused. error means the failure was ours.
3. A valid answer carries verified_by, which identifies the exact version of the rules it was checked against.

Forma's check accepts an answer only if it follows the oracle's rules. The rules are versioned and not published; verified_by identifies the version that accepted an answer: chart@6baf09f0 is the chart rules at that version.

Most calls come back in about two seconds; allow up to 120 seconds for the slowest. A call is counted in credits rather than requests.

What this buys you

A refusal is a real answer. Most of what an API of this kind can do wrong is return something well-formed and wrong. Here, an answer that does not pass the rules is not handed to you as if it did — you are told. That is the product, which is why a refusal is billable.

The rules are versioned on their own. The rules that accept an answer are separate from whatever produced it, and they carry their own version — see Citations. How answers are produced will change; what your citation points at does not.

You write intent, never rules. There is no endpoint that takes rules. You describe the outcome you want in plain language; deciding what satisfies it is our side of the line, and it stays our side so we can keep making it better without breaking anything you wrote.

What it does not do

It does not check meaning. A valid artifact is well-formed and follows the rules; it is not necessarily the chart you meant — a valid chart of the wrong column is still valid. Look at what you got.

It does not guarantee an answer. Some intents cannot be satisfied and the honest result is invalid.

It does not guarantee the same answer twice. See Determinism.

It does not stream. A call returns when the verdict does.