Claim evaluation is how IXO decides whether a submitted claim is supported by its evidence under the rules that govern it. A decision oracle turns the evidence into typed facts. The IXO decision engine applies a published rubric to those facts and signs the decision.
Read this page when you are designing an evaluation: the rules, the facts they need, the outcomes you allow and where a person reviews. It explains the model. For exact messages, fields and package names, use the Claims guide, Agent evaluations, Developer workflows and the Product and SDK map.
The question an evaluation answers
A Claim has been submitted.
Does the available evidence satisfy the governed rules,
and what action is allowed next?The answer is a structured record, not a model's free-text reply. It says which claim was evaluated, which evidence was read, which rubric applied, which checks passed or failed or need a person, what was decided, and what the decision allows next.
Some pages call that signed decision record a UDID, a Universal Decision and Impact Determination. It connects the decision to its evidence, its rules, the authority it was made under and its proof.
How a claim is evaluated
A claim is submitted
A person, service, device or agent submits a claim to a claim collection. The claim names its subject, its type and who made it, and references its evidence.
Authority is checked
Only an evaluator the collection has authorised may record a decision. A decision oracle needs a grant from the collection's owner before the chain accepts its evaluation.
Evidence becomes typed facts
The decision oracle reads the evidence and produces the named facts the rubric asks for. Each fact is true or false, a score, or an explicit "could not establish". The rubric is applied to facts, never to raw files or free-form model text.
The engine decides
The IXO decision engine applies the rubric to the facts and signs a receipt. The facts are frozen first, so the same facts always give the same decision, and anyone can replay it.
The decision is recorded and acted on
The decision is recorded on chain. Depending on the collection's settings it can release a payment, lead to a credential, or send the claim to a person for review.
A signed decision shows that the evidence met the stated rules. It does not show that the claim is true or that the outcome is correct. What each record proves is the page that owns this.
Who does what
| Part | Responsible for | Not responsible for |
|---|---|---|
| IXO Protocol | The claim's lifecycle state, grants and on-chain records | Private evidence, or how a model reasoned |
| Decision oracle | Reading the claim and producing the facts | Judging. The engine decides |
| IXO decision engine | Applying the rubric to the facts and signing the decision | Paying anyone for the work that was judged |
| IXO Matrix | Encrypted review rooms and private discussion of evidence | The rubric, or the final decision |
| Agentic oracle | Helping a person prepare or review a claim, within delegated authority | Deciding the claim |
| SDK and API references | Exact package names, methods, endpoints and request shapes | The design of the evaluation |
Facts
Facts are the bridge between messy evidence and a repeatable decision. Evidence can be PDFs, images, sensor logs, API responses, credentials or Matrix events. The rubric should not need to know how each one was parsed. It receives stable facts with their provenance.
The example below is illustrative. It shows the kind of information a fact carries.
{
"id": "field.legalName.reconciliation",
"value": "normalized_match",
"confidence": 0.98,
"producer": "legal-name-reconciler@1.0.0",
"sources": [
{
"type": "claim-jsonld",
"path": "$.assertion.legalName"
},
{
"type": "registry-response",
"path": "$.entity.legalName"
}
]
}A useful fact has a stable identifier, a typed value, the producer and its version, references to its sources, a confidence where that matters, defined behaviour when it cannot be produced, and enough provenance for someone to replay it.
Rubrics
A rubric is the set of rules a claim is judged by. Make it explicit, ordered and reason-coded, so that "send to a person" is as precise as "approve" or "reject". A rubric's id is the hash of its content, so a changed rubric is a different rubric.
The example below is illustrative. It shows one rule.
{
"id": "LEIV-R002",
"description": "Registry extract is mandatory",
"when": {
"fact": "document.registryExtract.present",
"equals": false
},
"then": {
"outcome": "rejected",
"reasonCode": "LEIV-201-MISSING-REGISTRY-EXTRACT"
}
}Order the checks like this:
- admissibility checks
- hard safety vetoes
- missing mandatory evidence
- invalid or conflicting evidence
- manual-review triggers
- partial-success logic
- approval logic
Treat an unclear case as a reason to route, not a reason to force a yes or no. Design an evaluator walks through writing the rules.
Outcome model
When you design an evaluation, define its outcomes in plain operational terms first. The list below is a design vocabulary for rubrics. It is not the set of status values the chain records.
| Outcome | Meaning | What the workflow does next |
|---|---|---|
approved | The evidence satisfies the rubric | Continue to the allowed next step: a payment, a credential or a record update |
rejected | The claim fails a hard rule or lacks mandatory evidence | Record the rejection and its reason code. Take no approval-only action |
manual_review_required | The evidence is unclear, conflicting, or outside what may be decided automatically | Pause and send the claim to a person or a governance review |
partial_success | Part of the claim is supported under a rule | Continue only if the rubric defines what a partial result allows |
disputed | Someone challenges the evaluation or the decision | Send it to the dispute process |
The chain's own values are listed on
What the chain records about a claim.
Only approved and rejected appear in both lists. There is no chain status called
manual_review_required or partial_success. On chain a dispute is a separate record with its own
status, described in How claim disputes work on chain.
If your implementation maps these outcomes to MsgEvaluateClaim fields, service API fields, or SDK
helper methods, use the developer guides and API references for the exact literals.
Human review
Human review is a defined step, not an informal chat. A review request should carry:
- the claim ID and its claim collection
- the claim's subject and type
- the evaluator's DID or service identity
- the rubric ID and version
- the reason code for the proposed outcome
- references to the evidence that was read, redacted where needed
- a summary of the facts that were evaluated
- the proposed outcome
- the questions that need a person's judgement
- the deadline or escalation policy
- the shape the answer must take
Rules can send a claim to a person, and the reviewer's answers become part of the same decision. IXO Matrix can hold encrypted review rooms and notifications, but the decision itself is the signed record, not a chat message.
Design rules
Do not let a model approve a claim
A model may extract, classify, summarise or recommend. Approval comes from the rubric applied to facts.
Do not treat a CID as proof of authenticity
A CID proves the referenced content has not changed. It does not prove that a document is genuine, current, complete, or issued by an authorised source. A CID is not a UDID.
Do not let the evaluator change its own rubric
Change a rubric through proposal, review and a new version. A changed rubric has a new id.
Do not act on unclear evidence
Send an unclear case to a person, to the dispute process, or back for more evidence before any high-value or irreversible action.
Do not publish sensitive traces
When evidence holds personal, commercial or regulated data, keep the full trace encrypted and publish only a redacted one.
Start small
Start with one evaluation that cannot pay, issue credentials or change high-value records on its own. Define one claim type, one claim collection, one rubric, one evidence schema, one set of facts, one evaluator identity, one human review path, one dispute or correction path, and tests for approval, rejection, unclear and adversarial cases. Widen what the evaluation may set in motion only once its results are repeatable and reviewed.
Where to go next
Turn what you know into rules, facts and tests for a decision oracle.
Decision oracleBuild and test the service that produces the facts.
Agent evaluationsDesign evaluation Flows in Qi with UCAN authority, claims, evidence, rubrics and UDID records.
Claims guideSubmit claims and record evaluations from code.