128 Fields on One Statute: What Rich Legal Metadata Actually Buys You

One search result from our US primary law API carries 128 fields, and not for completeness's sake. Text plus a citation renders a section on a page and supports almost nothing else. Every hard question your product will eventually ask (is this current, what changed, what does it point at, where exactly did it come from) is answered by metadata, and an API that does not carry it leaves you reconstructing it from the text with a regex. That is where wrong answers are born. This post walks all nine field families and, for each, answers the only question worth asking: what can you now build that you could not build before.

TL;DR

• A thin legal API returns text, a citation, and a link. That supports a reader view, not a staleness banner, a citation graph, a change feed, or a checkable provenance claim.
• The 128 fields group into nine families, and each family maps to a product feature rather than a schema aesthetic.
• sourceCharStart and sourceCharEnd are the sleeper fields. They mark the exact span inside the publisher's own stored artifact, which turns "we got this from the state" into something a reader can verify.
• Most fields are null on any given row, by design. A comment close date means something for a Federal Register proposed rule and nothing for a state constitution.
• Amendment history is history, not time travel. Versioning works off the amendment record rather than a date parameter. What exists is a last-amended year, a change feed, and per-section diffs on a watched source.
• The fields parameter prunes a response, always keeps actId and citation, and rejects an unknown name with 422 instead of dropping it quietly.

This is one post in our legal data infrastructure series.

For related coverage, see What a Legal Data API Should Guarantee: The Schema Contract for the tier argument behind these families, Legal Citation Resolution: Turning a Cite Into the Right Section, Every Time, and Amendment History and Point-in-Time Law: What a Legal API Can and Cannot Tell You.

The thin response, and what it costs you

Here is the shape most legal APIs return.

{
  "citation": "42 U.S.C. 1983",
  "title": "Civil action for deprivation of rights",
  "text": "Every person who, under color of any statute...",
  "url": "https://uscode.house.gov/..."
}

You can build a reader view on that. You cannot build anything that has an opinion about the row.

Is this text current, and current through what date? When did it last change? What does it cite, and what cites it? If this section moved, where did it go? Is the comment period still open? The thin response goes quiet on all of it.

So you parse the text: pull a year out of a trailing history note, regex the cross references, guess the hierarchy from the citation string. That works on the corpus you tested and breaks on the next state, which prints its history note in a different shape, or prints none.

The nine families, and the feature each one unlocks

Corpus scale for context: 4,150,839 distinct sections indexed as 12,003,716 retrieval passages across 53 jurisdictions. One search result over that corpus publishes 128 fields, each named in the response field reference.

Identity: 7 fields

What this lets you build: a cache, a dedup key, and a cross reference that survives a rebuild. Real ids look like USC_T42_C21_S1983 and SAL_PL116-136_DVA_TII_S1109 (CARES Act section 1109). They are stable but not guessable, so you store one from a search or resolve response rather than constructing it.

alternateCitations is the underrated one. Two lawyers can cite the same provision three ways, and a matcher that only knows the canonical string treats those as three different provisions.

Hierarchy: 22 fields

Twenty-two fields for "where is this in the code" sounds excessive until you normalize across 53 jurisdictions. Some states nest title, chapter, article, section. Some use subtitle and part, some use subject numbers that map to none of it.

What this lets you build: a browsable code tree and a working "show me the rest of this chapter". With parent and breadcrumb you render the path above a section with no second call. With chapter plus titleNumber you fetch the siblings, and the divisions endpoint (GET /us/statutes/divisions?corpusType=STATE&state=XX) walks the same tree top down.

Concretely: a compliance product showing one regulation can put a "other sections in this subpart" strip under it, because subpart and subpartName are on the row already. Without them you are parsing the citation string and hoping the state's numbering is regular. It is not.

Provenance and format mirrors: 16 fields

The four offset fields are the most important in this post.

A link is a claim. It says "this text came from that page," and the reader either takes your word for it or opens the page and hunts. The offsets replace the claim with an address: this is the artifact we mirrored from the publisher, and this row is the span running from sourceCharStart to sourceCharEnd inside it.

For a PDF source, sourcePageStart and sourcePageEnd do the same job in page units, so a citation checker lands a reviewer on the right page of the publisher's own print rather than the top of a long document.

The format mirrors, documented per corpus, matter for a different reason. A publisher's HTML and PDF of the same rule are not always identical, and the one a court will accept is often the PDF, so your export can attach the authoritative format rather than the convenient one.

Currency and status: 14 fields

What this lets you build: an honest staleness banner. Not "updated recently," which is about you, but "current through January 6, 2025 per the publisher," which is about the law. Only one of those is useful to a lawyer.

goodLawStatus and actStatus carry a design decision worth copying. Statutes at Large items are law as enacted, a record of what Congress passed, so they carry actStatus: "enacted" and goodLawStatus: "unknown" on purpose. Calling an old public law current law would be a lie dressed as a field value.

Four publication date fields looks redundant until you notice that a Federal Register document has a publication date, agency guidance has an issue date, and a court rules compilation has a release date. Collapsing them destroys a distinction the user needs.

Amendment history: 8 fields

What this lets you build: a change timeline per section, and a currency filter that tracks the law instead of your own rebuild date. The yearFrom and yearTo search parameters filter on the last amendment year the publisher credits, so "show me everything in this chapter touched since 2020" is a query rather than a project.

Read this family precisely, because it is where vendors oversell. It is an amendment record, not point-in-time retrieval. One citation maps to one stored text, the current one, and the version information sits in the amendment credits around it rather than in a date parameter. You can see every amendment year the publisher credits on a section. You cannot ask this API what the text said between two of them, and what a legal API can and cannot tell you about point-in-time law goes through that boundary in full.

Three causes, and only one is a wrong answer: the note was never captured, the note was captured but never parsed into a year, or something on the page that is not the history got read as if it were. A missing year is often a publisher property rather than a pipeline failure, because some state publishers print no amendment credit at all. Delaware is the clean case: no printed year, so the year is derived from a volume-to-year table, and Delaware reads as almost entirely unsupported while being correct.

That is also why yearFrom and yearTo drop about a fifth of sections once either bound is set. A section with no credited year cannot honestly sit inside a year range.

Relationships between provisions: 13 fields, plus 2

What this lets you build: a citation graph, and a regulation-to-statute jump. statutoryAuthority and lawImplemented let a user reading a rule click through to the statute that authorized it in one hop, with no hand-maintained lookup table. Run it the other way with implementingRegulations and a statute page lists the rules built on it.

renumberedTo and transferredTo solve a problem that silently corrupts legal products. A provision that moved is not gone, but to a system keyed only on the old citation it looks identical to a repeal. The saved search breaks, the alert stops firing, and nothing errors.

Worked example: a policy team tracks a statute and wants every regulation that names it as authority. With statutoryAuthority populated that is a filter. Without it, it is a string search across roughly 1.46M state regulation sections that misses every rule citing the statute in a form you did not anticipate.

The Federal Register block: 13 fields

What this lets you build: comment-deadline monitoring that does not need a human reading the FR. A regulatory affairs product filters documentType=proposed with frCommentsCloseOn inside a chosen window, groups by frDocketIds, and emails the team a queue with a direct frRegulationsDotGovUrl for each item. One feature, four fields.

frEffectiveOn feeds a different surface: a compliance calendar that shows when obligations actually start rather than when the rule was published. Those two dates are often months apart, and confusing them is an incident.

frCorrections and frCorrectionOf catch the agency fix. A monitor without them shows the uncorrected text and never mentions the correction exists. The corpus behind this block is Federal Register agency rules, final and proposed, 1994 to present, 202,526 sections, refreshed weekly.

Agency and executive: 9 fields

What this lets you build: an agency-scoped feed, and an executive order status page. agencySlugs makes the first one real, because agency names are printed inconsistently and slugs are not. Filter on the slug, render the name.

rescindedOn and president give you the executive order surface people want: every EO signed by a given president, with the rescinded ones marked rather than deleted. That corpus runs 2015 to present, 3,788 sections, refreshed daily.

documentSubtype and documentTypeLabel are a small lesson in schema honesty. One is for your code and one is for your UI, and merging them forces every consumer to display a slug or maintain a display map.

Corpus-specific odds and ends

The rest exist because one corpus needed them and nothing else does.

topics and audience answer a question statutes never raise: who was this written for. A compliance officer filtering OCC Bulletins wants the ones addressed to banks, not to examiners, and that distinction is printed on the document.

languageCode exists for one reason. Puerto Rico's insurance bulletins are served in Spanish, the enacted language, and Puerto Rico is the largest jurisdiction in that corpus at 1,641 sections. A row that does not declare its language will get fed to an English-only pipeline and quietly produce nonsense.

Most of these are null, and that is the correct design

Any given row uses a fraction of the 128. A state constitution has no frCommentsCloseOn, a Federal Register proposed rule has no committeeNote, an executive order has no chapter. That is not a data gap. US primary law is about a dozen document types, and a superset with a documented per-corpus population is the honest way to model that in one object. The tier-by-tier version of the argument, and the three API behaviors that make it testable, are in what a legal data API should guarantee.

The wrong fix is inventing values so the shape looks full. A currencyYear derived from your ingest date rather than the publisher's statement is worse than a null, because null is checkable and a plausible wrong year is not.

Pruning with fields, worked

A 128-field object is right for a detail view and wasteful for a list. The fields parameter cuts it down. Before, a default POST /us/statutes/search:

{
  "query": "notice requirements for policy cancellation",
  "corpusType": "STATE_AGENCY_GUIDANCE",
  "limit": 50
}

Fifty rows, each carrying the full object: 50 x 128, or 6,400 field slots on the wire, of which the list view paints four. After, pruned:

{
  "query": "notice requirements for policy cancellation",
  "corpusType": "STATE_AGENCY_GUIDANCE",
  "limit": 50,
  "fields": ["state", "issueDate", "sectionTitle", "excerpt"]
}

Each row now carries six: the four you named plus actId and citation. That is 300 field slots instead of 6,400, a 21x cut in fields on the wire for a list that looks identical to the user.

Two behaviors make this safe to depend on: actId and citation come back whether you named them or not, and an unknown field name such as sectionTtile is rejected with 422, in the shape the error reference documents, rather than dropped quietly while your UI renders a blank column. Both are part of the enforceable schema contract rather than conveniences.

Then call GET /us/statutes/section/{actId} for the full object when a user opens a row. The pattern is wide on detail, narrow on lists, and you page the list under the pagination rules.

The check to run against any legal data vendor

Ask for one raw JSON response body from a real query, not a docs page and not a schema diagram. Count the fields, then check whether that body can tell you where exactly the text came from inside the source document, what it is current through in the publisher's own words, when it was last amended and on what credit, what the provision references and what references it, and where it went if it moved. Each of those maps to one of the families above, and a "no" on any of them is work that lands on you.

A vendor that answers all of them in one response body is selling infrastructure. One that answers two is selling a text feed, which is fine if a text feed is what you need and expensive if you find out after shipping. The longer questionnaire, including the paging and error-behavior tests, is in the vendor questions in the schema contract post.

One more check costs nothing: ask whether an unknown filter value returns an error or an empty result set. Silent empty results are the worst failure mode here, because a typo and a real zero-result query look identical, and you will trust the wrong one.

FAQ

How many fields does a legal API response actually need?

Fewer than 128 for a reader view, and all of them for a product with opinions about the data. The number matters less than the coverage. Identity, hierarchy, provenance, currency, amendment history, and relationships are the six families a real product will need, and a response missing any of them pushes that work onto you.

What are sourceCharStart and sourceCharEnd for?

They mark the exact character span inside the publisher's stored artifact that a section's text came from. A URL tells you which document, and the offsets tell you which characters, which is the difference between a provenance claim and a checkable one. For PDF sources, sourcePageStart and sourcePageEnd do the same job in page units.

Can I query what a statute said on a specific past date?

Versioning here runs off the amendment record rather than a date parameter. Each citation maps to one stored text, the one currently in force, with no as_of=DATE parameter, no per-section version list, and no arbitrary-date diff. What exists is amendment history and a last-amended year per section, a yearFrom/yearTo currency filter, change events captured per refresh, and per-section diffs on a watched board.

Why are so many fields null?

Because a field that means something for one corpus means nothing for another. A Federal Register proposed rule has a comment close date and a state constitution does not, so a superset schema with documented per-corpus population is more honest than forcing every corpus into a shared shape. Null is a fact, and a fabricated value to fill it would be worse.

What does the fields parameter do?

It prunes a search response to only the fields you name, which cuts a 50-row list from 6,400 field slots to a few hundred. actId and citation come back regardless, because a row without an identifier cannot be re-fetched and a row without a citation cannot be attributed. An unknown field name returns 422 rather than being ignored.

How do I follow a statute section that was renumbered?

Read renumberedTo and transferredTo. Those two pointers carry the citation from its old number to its new one, which matters because a system keyed on the old citation cannot tell a moved provision from a repealed one. The supersedes, supersededBy, and supersessionActions fields cover the cases where a provision was replaced rather than moved.

What metadata do I need to monitor rulemaking comment deadlines?

Four fields do most of the work: frCommentsCloseOn for the deadline, frDocketIds for grouping, frEffectiveOn for the compliance calendar, and frRegulationsDotGovUrl so the user can file. Add frCorrections and frCorrectionOf so an agency correction does not slip past your monitor.

Why does a US legal API carry a languageCode field?

Puerto Rico's insurance bulletins are issued in Spanish, the enacted language there, and Puerto Rico is the largest jurisdiction in that corpus at 1,641 sections. Without a language field on the row, those documents get processed by English-only tooling and produce quiet garbage.

How much amendment history coverage should I expect from a state law corpus?

Less than a vendor's headline number suggests, and the reason matters more than the number. In our 2026-08-30 census of 3,518,180 state sections, 912,388 (25.9%) carried no amendment year at all, and a missing year is often a publisher property rather than a pipeline failure. Ask any vendor to split their coverage figure into captured-and-parsed, captured-but-unparsed, and never-captured before comparing it to anyone else's.

Priyansh Khodiyar

Co-Founder & CTO

Priyansh leads engineering and AI at Vaquill, from the matter workbench to drafting, document comparison, document matrix, and citation-verified research.