AI Extraction edit and validation layer - API Contracts

[chetanr25]

Extraction edit + validate

Part of #541

Depends on: Templates CRUD (#549 ), AI extraction (#550)

Contract reference

• path/extraction.yaml#L191-L421
• schemas/extraction-record.yaml#ValidationResult

Endpoints

PATCH /api/v1/extract/{extract_id} (done, #661)

Allows a responder to manually correct any field in the extracted incident data after LLM extraction. Uses JSON Merge Patch (RFC 7396), only send the fields that changed. Server records an audit trail of changes and recalculates completeness scores.

See path/extraction.yaml#L191-L280 for full spec.

GET /api/v1/extract/{extract_id}/readiness

The form selection matrix. Compares the extracted contract against the field list of every active template and reports, per template, whether it can be generated right now and which fields are blocking it. Pure lookup over stored data, no LLM, so it is cheap to refetch after every correction.

This endpoint was added to the contract after the issue was first written. The frontend needs it to decide which forms to show as selectable, so it belongs with the rest of the review work rather than in a separate issue.

See path/extraction.yaml#L282-L355 for full spec.

POST /api/v1/extract/{extract_id}/validate

The single template version of the same check. Answers the question: "can I generate this form with what I have?" Returns whether it is valid, the missing required and recommended fields, warnings, and field coverage. Useful for rechecking just the template the user is looking at instead of recomputing the whole matrix.

The request body takes a template_id, not a form type. Users register their own templates and each one carries its own field list, so the check is scoped to a registered template.

See path/extraction.yaml#L357-L421 for full spec.

Rules both checks follow

Both endpoints run the same engine over one template's field list, so they agree by construction.

• A field is missing when its value is null, an empty string, an empty list or an empty object. A blank box on the review screen is a gap.
• Where the value comes from depends on the field's source. Schema fields read the contract path in incident_mapping. Static fields are always satisfied. Manual and open fields read their key under custom_fields.
• Only active templates appear in the readiness matrix. Drafts and legacy templates stay out of the selection screen.
• Coverage is filled fields over total fields for that template.
• Warnings are built from the recommended fields that have no value. No hand written rule table per form type.

[chetanr25]

Closed as completed in #669