FormGraph

Agent-native paperwork infrastructure.

FormGraph is an open standard and TypeScript library for representing forms as typed graphs of fields, dependencies, evidence requirements, review gates, and completion receipts.

Existing form projects are good at rendering forms or assembling documents. FormGraph targets the layer above them: making messy paperwork understandable to software agents without losing human review, source evidence, or auditability.

Why

A benefits form PDF field named txt_43, an HTML input labeled Monthly income, an XLSForm field called income_mo, and a FHIR Questionnaire item can all point at the same canonical FormGraph field path:

household.income.monthly

Once the form is represented this way, a tool or agent can answer concrete questions safely:

• Which fields can be filled from known user data?
• Which fields require human review?
• Which evidence documents are missing?
• Which conditional requirements became active?
• Can this packet be prepared, reviewed, or submitted?
• What was filled from which source, with what confidence?

What This Repo Provides

• A canonical FormGraph TypeScript type.
• Validation helpers for graph integrity.
• Completion analysis for required fields, dependency-triggered fields, evidence requirements, and review gates.
• Receipt helpers for recording prepared/reviewed/submitted packet state.
• A CLI for validating and inspecting .formgraph.json files.
• A starter example for hardship/utility assistance paperwork.

Install

npm install @agent-pattern-labs/formgraph

CLI

formgraph validate examples/utility-hardship.formgraph.json
formgraph inspect examples/utility-hardship.formgraph.json

Library

import {
  analyzeCompletion,
  createCompletionReceipt,
  validateFormGraph
} from "@agent-pattern-labs/formgraph";

const validation = validateFormGraph(graph);
if (!validation.ok) {
  throw new Error(validation.errors.join("\n"));
}

const analysis = analyzeCompletion(graph, {
  "applicant.name.full": "Jane Example",
  "household.income.monthly": 1800
});

const receipt = createCompletionReceipt({
  graph,
  analysis,
  actor: { kind: "human", id: "user_123" },
  status: "prepared"
});

Non-Goals

FormGraph is not a legal, medical, or benefits decision engine. It does not decide eligibility or replace professional review. It is a transport and analysis layer for fields, dependencies, evidence, and review state.

FormGraph is also not a replacement for JSON Schema, Docassemble, XLSForm, FHIR Questionnaire, ODK, SurveyJS, or PDF form libraries. It should adapt to and from those ecosystems where possible.

Initial Adapter Targets

• JSON Schema forms
• AcroForm PDFs
• HTML forms
• XLSForm / XForms
• FHIR Questionnaire
• Docassemble interview variables

License

MIT