The universal schema for government correspondence.
Every year, government agencies send hundreds of millions of notices to employers, businesses, and individuals — tax bills, unemployment determinations, OSHA citations, workers comp audits. Each agency uses its own format, its own delivery method, its own terminology.
Patra is the Rosetta Stone. One schema. Every notice. Every agency.
Patra is open source. Anyone can build against it. Kreto Systems builds the reference implementation — the adapters, the AI parser, the CPA delivery platform. The schema belongs to everyone.
पत्र (patra) — Sanskrit for letter, document, correspondence.
The gap between government agencies and the businesses they regulate is the last unsolved integration problem in compliance software. Every vendor ends up rebuilding the same thing — a scraper for this portal, a parser for that PDF, a mapper for that XML. None of them talk to each other. None of them reuse each other's work.
UGCS — the Universal Government Correspondence Schema — is the contract that lets them.
- Adapters (scrapers, parsers, API clients) produce UGCS-shaped output.
- Consumers (CPA platforms, payroll systems, compliance tools) accept UGCS-shaped input.
- Everyone wins because the interop surface is stable.
npm install @kreto/patraPatra ships both CommonJS and ESM builds and is 100% TypeScript. Zero
runtime dependencies beyond ajv (schema validation) and zod
(helper runtime guards).
import { PatraValidator } from "@kreto/patra";
const validator = new PatraValidator();
const result = validator.validate(someNoticeJson);
if (!result.valid) {
console.error("Invalid UGCS notice:", result.errors);
} else {
console.log(`Notice passed validation. Confidence: ${result.confidence_score}`);
}import { deadlineCalculator } from "@kreto/patra";
const res = deadlineCalculator.computeFromRegistry({
jurisdiction: "OH",
ugcsCode: "TAX-STATE-BILL-001",
issuedDate: "2026-03-15",
receivedDate: "2026-03-18T14:22:00Z",
});
console.log(res?.deadline); // "2026-05-14"
console.log(res?.basis); // "60 calendar days from issue_date..."import { getAgency, getNoticeType, classifyAgencyCode } from "@kreto/patra";
getAgency("OH-ODT")?.name; // "Ohio Department of Taxation"
getNoticeType("TAX-FED-AUDIT-001"); // { payload_type: "IRS_UNDERREPORTER", ... }
classifyAgencyCode("CP2000"); // "TAX-FED-AUDIT-001"Adapters extend BaseSchemaMapper. The base class handles UUID
generation, priority scoring, schema version pinning, and validation —
you only implement the parse-and-map step.
import { BaseSchemaMapper, type MapperResult } from "@kreto/patra";
class OhioOdtMapper extends BaseSchemaMapper<OdtRawInput> {
map(input: OdtRawInput): MapperResult {
const notice = this.buildNotice({
issuing_agency: {
level: "state",
name: "Ohio Department of Taxation",
code: "OH-ODT",
jurisdiction: "OH",
},
correspondence_domain: "TAXATION_STATE",
// ...fill in the rest of the envelope
payload: {
type: "STATE_TAX_BILLING",
ugcs_code: "TAX-STATE-BILL-001",
// ...notice-specific fields
},
audit_trail: [],
delivery: { status: "PENDING" },
});
return this.finalize(notice);
}
}See docs/adapters.md for the full guide.
UGCS has two layers:
The envelope is identical for every notice from every agency. Every adapter produces it. Every consumer parses it. It never changes for a new notice type.
A discriminated union keyed on payload.type. Each notice type has
its own payload with only the fields that actually appear on that
kind of notice. Adding a new notice type does not change the envelope.
See SCHEMA.md for the full field reference.
Patra ships with type definitions, registry entries, and fixtures for the following categories. Adapters can cover any agency; these are the notice types Patra's schema and registries know about.
| UGCS Code | Description |
|---|---|
UI-RATE-001 |
Annual SUI tax rate determination |
UI-CLAIM-001 |
Monetary determination / base-period employer |
UI-CHARGE-001 |
Statement of benefit charges |
UI-OVERPAY-001 |
Overpayment notice / repayment demand |
UI-APPEAL-001 |
Appeal hearing notice or decision |
| UGCS Code | Description |
|---|---|
TAX-FED-BILL-001 |
Balance due / CP501, CP503, CP504 |
TAX-FED-AUDIT-001 |
CP2000 underreporter |
TAX-FED-LEVY-001 |
Final notice of intent to levy / CP90, LT11 |
TAX-FED-ACA-001 |
ACA employer shared responsibility / Letter 226J |
TAX-FED-LOCK-001 |
Lock-in letter / 2800C, 2801C |
TAX-FED-LIEN-001 |
Notice of Federal Tax Lien |
TAX-FED-AUDIT-002 |
Examination / audit initiation |
| UGCS Code | Description |
|---|---|
TAX-STATE-BILL-001 |
State tax balance due |
TAX-STATE-WHLD-001 |
Withholding discrepancy |
TAX-STATE-SALES-001 |
Sales / use tax assessment |
TAX-STATE-ASSESS-001 |
Formal assessment (proposed / final) |
TAX-STATE-AUDIT-001 |
Audit initiation / document request |
TAX-STATE-LIEN-001 |
State tax lien |
| UGCS Code | Description |
|---|---|
WC-PREM-001 |
Premium invoice |
WC-RATE-001 |
Experience modification |
WC-AUDIT-001 |
Payroll audit / true-up |
WC-CLAIM-001 |
Claim notification / status |
WC-COMP-001 |
Coverage lapse / delinquent |
| UGCS Code | Description |
|---|---|
LABOR-FED-OSHA-001 |
OSHA citation |
LABOR-FED-EEOC-001 |
EEOC charge of discrimination |
LABOR-FED-WHD-001 |
DOL Wage and Hour investigation |
| UGCS Code | Description |
|---|---|
IMM-I9-001 |
ICE I-9 Notice of Inspection |
IMM-EVERIFY-001 |
E-Verify Tentative Non-Confirmation |
IMM-SSA-001 |
SSA Employer Correction Request |
| UGCS Code | Description |
|---|---|
DIS-RATE-001 |
SDI / TDI annual rate |
DIS-DELIN-001 |
Delinquent contribution |
| UGCS Code | Description |
|---|---|
ENTITY-SOS-001 |
Secretary of State annual report |
ENTITY-SOS-002 |
Registered agent change / delinquency |
LIC-BUS-001 |
Business license renewal / issue |
| UGCS Code | Description |
|---|---|
GENERIC-001 |
Unclassified — requires human triage |
Patra's registry covers all 50 states + DC. For each jurisdiction we provide entries for the state tax authority, state unemployment agency, and state workers comp body (where those are separate agencies). Federal agencies covered: IRS, DOL / DOL-WHD, EEOC, OSHA, USCIS, ICE, SSA.
See docs/notice-types.md for the complete taxonomy and docs/adapters.md for how to extend the registry.
Every UGCS notice carries a priority_score (0–100) computed from:
| Factor | Weight |
|---|---|
| Urgency (CRITICAL) | 40 |
| Urgency (TIME_SENSITIVE) | 30 |
| Urgency (ROUTINE) | 10 |
| Urgency (INFORMATIONAL) | 0 |
| Deadline < 3 days | 40 |
| Deadline < 7 days | 25 |
| Deadline < 14 days | 15 |
| Deadline < 30 days | 5 |
| Action = PAY or APPEAR | 10 |
| Action = RESPOND / FILE / APPEAL | 8 |
| Action = CORRECT / PROVIDE_DOCS | 5 |
| Action = REVIEW | 3 |
| amount_due > $10,000 | 10 |
| amount_due > $1,000 | 5 |
Scores are clamped to [0, 100]. Adapters don't need to compute this —
BaseSchemaMapper.buildNotice does it automatically.
UGCS follows semantic versioning.
- Major bumps — removing or renaming a field
- Minor bumps — adding a new field, new notice type, new agency
- Patch bumps — documentation, registry additions that don't affect the schema
Every notice carries schema_version so consumers can negotiate
compatibility.
See CONTRIBUTING.md. We especially welcome:
- New state agency entries for the registry
- New notice-type payload definitions with real-world fixtures
- Statute references for state-specific deadline rules
- Holiday calendars for states beyond Ohio
MIT. See LICENSE.
Patra is maintained by Kreto Systems Inc., a compliance-intelligence company for CPA firms. Kreto builds the commercial layer on top of UGCS — adapters, AI parser, CPA delivery platform. The schema itself is MIT and always will be. Governance is collaborative; the long-term goal is moving Patra to a neutral foundation once there's an ecosystem of adapters and consumers.