Skip to content

Claim and Decide a Validation Assignment

Before you begin

Roles required: Validator, SME, governance lead.

You must hold the validator role for the Horn type being reviewed. Role assignments are managed by your governance lead. You need a candidate_id for a classified candidate whose ClassificationRecord does not have requires_review: true, or you need explicit governance approval to validate a flagged candidate.

Important: OPEN_ISSUE candidates cannot be approved. If you claim an OPEN_ISSUE assignment, the only valid decisions are ESCALATED or REJECTED. Do not attempt to approve an open issue — the service will reject the request.

Assumed state: The candidate has a ClassificationRecord. See Classify a Candidate Answer.

Steps

1. Create a validation assignment

Send a POST request to /v1/validation/assignments to create an assignment for the candidate. You can assign it directly to yourself or to a shared queue:

curl -s -X POST http://localhost:8000/v1/validation/assignments \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cand_01j2k3l4m5n6p7q8r9t1",
    "assignee": "validator-jane",
    "horn_type": "FACT"
  }'

The response includes an assignment_id and the initial status: PENDING.

{
  "assignment_id": "val_01j2k3l4m5n6p7q8r9v3",
  "candidate_id": "cand_01j2k3l4m5n6p7q8r9t1",
  "status": "PENDING",
  "horn_type": "FACT",
  "assignee": "validator-jane",
  "created_at": "2026-06-07T14:40:00Z"
}

Save the assignment_id for the next steps.

2. Claim the assignment

Claiming an assignment moves its status from PENDING to IN_REVIEW and locks it to you. Only one validator can hold a claim on an assignment at a time.

curl -s -X POST http://localhost:8000/v1/validation/assignments/val_01j2k3l4m5n6p7q8r9v3/claim \
  -H "Content-Type: application/json" \
  -d '{
    "validator_id": "validator-jane"
  }'

If another validator has already claimed the assignment, the service returns 409 Conflict. Check the assignment status and coordinate with your team before attempting to re-claim.

3. Review the candidate before deciding

Before submitting a decision, review all available information:

  • Answer text — from /v1/candidates/{id}/answers — is it complete, accurate, and free from PII that should not be published?
  • Horn type — from /v1/classifications/{candidate_id} — is primary_horn_type the correct classification for this content?
  • Assertion grammar (FACT only) — are subject, predicate, object_value, and scope accurate representations of the claim?
  • Evidence — what is the source artifact? Is it authoritative for this claim?
  • Conflict flags — does the ClassificationRecord or assignment show a ConflictFlag?

Important: If a ConflictFlag is present on the assignment, a different answer in the registry already makes a claim about the same subject + predicate + scope but with a different object_value. This means two validated answers are contradicting each other. Review the existing registry answer at /v1/registry/answers before making your decision. Do not approve a conflicting answer without understanding which claim is correct. The default behavior is to block the assignment from auto-approval; human judgment is required.

4. Submit your decision

Send a POST request to /v1/validation/assignments/{id}/decide with one of the four valid decisions.

Decision: APPROVED

The answer is correct, complete, and ready for publication. No changes required.

curl -s -X POST http://localhost:8000/v1/validation/assignments/val_01j2k3l4m5n6p7q8r9v3/decide \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "rationale": "Answer accurately reflects platform SSO capability per the Zoom call with ACME on 2026-06-01."
  }'

Decision: REVISED

The answer has minor inaccuracies or needs wording correction. Provide the corrected text. The revised text triggers re-classification before re-entering the review queue.

curl -s -X POST http://localhost:8000/v1/validation/assignments/val_01j2k3l4m5n6p7q8r9v3/decide \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "revised",
    "rationale": "Original answer omitted OIDC. Corrected to include both SAML 2.0 and OIDC.",
    "revised_text": "The platform supports SSO via SAML 2.0 and OIDC. Azure AD, Okta, and Ping Identity are supported identity providers."
  }'

Decision: REJECTED

The answer is incorrect, out of scope, or should not be published. The candidate is removed from the publish path but is retained for audit.

curl -s -X POST http://localhost:8000/v1/validation/assignments/val_01j2k3l4m5n6p7q8r9v3/decide \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "rejected",
    "rationale": "Answer contains outdated information from a pre-GA demo call. Not representative of current product behavior."
  }'

Decision: ESCALATED

You cannot make a confident decision. Send the assignment to a specialist queue with a rationale explaining what information is needed.

curl -s -X POST http://localhost:8000/v1/validation/assignments/val_01j2k3l4m5n6p7q8r9v3/decide \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "escalated",
    "rationale": "Conflicting claims in registry. Existing answer says SAML only. New answer claims OIDC also supported. Engineering clarification needed before approving either."
  }'

Note: ValidationRecord objects are immutable once created. A decision cannot be edited or deleted. If a decision was made in error, the correct action is to supersede the published answer (after it reaches the registry) or to create a new validation assignment on a revised candidate. Escalation and rejection decisions persist as permanent audit records.

5. Verify the resulting status

After submitting a decision, check the assignment queue depth to confirm the assignment processed correctly:

curl -s "http://localhost:8000/v1/validation/queue/depth"

This returns the count of assignments in each status bucket. Confirm the IN_REVIEW count decreased by one and the appropriate terminal-state bucket increased.

Validation state transitions

stateDiagram-v2
    [*] --> PENDING : assignment created
    PENDING --> IN_REVIEW : claim
    IN_REVIEW --> APPROVED : decide approved
    IN_REVIEW --> REVISED : decide revised
    IN_REVIEW --> REJECTED : decide rejected
    IN_REVIEW --> ESCALATED : decide escalated
    REVISED --> IN_REVIEW : re-classification complete
    APPROVED --> SUPERSEDED : supersede in registry
    APPROVED --> DISPUTED : dispute in registry
    APPROVED --> RETIRED : retire in registry

Result

The candidate has a ValidationRecord with a terminal decision. Approved candidates carry a validation_record_id that is required for publishing to the registry. Revised candidates re-enter classification and then return to the review queue. Rejected and escalated candidates are retained for audit but do not proceed to the registry.

See also: Publish an Approved Answer to the Registry; Classify a Candidate Answer; Horn Information Types