Data model rules

The reading rules that hold on every product, so one record format is enough to learn.

View as MarkdownWhole product as one Markdown fileOpenAPI

Normalized and original values

Every record is normalized into one schema per product: names split into parts, dates in ISO form, states as two-letter codes, enums from a closed vocabulary. The source's own text is kept beside it where it adds meaning — for example a charge keeps the source's description and statute verbatim while its severity is normalized — and a Sex Offender record carries its full per-state stateData block by default (exclude: ["stateData"] for a lighter payload), while include: ["sourceData"] (criminal) asks for more of the source's own fields.

Provenance

Every record says where it came from: sources[] with the jurisdiction or public source code, a recordUrl to the source's own page where one exists, and lastCheckedAt. A record merged from several sources lists each. Nothing is presented without its source.

Completeness

status: "complete" means every source in scope was read to the end. "partial" means at least one did not finish; counts.sourcesIncomplete and sourceStatus[] say which and why (incompleteReason).
An empty records[] is an answer only when status is complete. On partial, it is a lower bound.
A record cap or a refused query is said explicitly (capped, 422 query_too_broad); results are never silently truncated.

Missing, null, empty, unknown

You see	It means
Field absent	Not applicable to this record type or product, or not requested (an `include` option controls it). Never infer a value.
`null`	The field applies but the source did not publish it for this record.
`""` (empty string)	A string slot the source does not publish or left blank (Sex Offender: the registry does not publish that field; Criminal: the source gave no text). Different from `null`, which means unknown or not applicable — a typed absence (dates, numbers, nested objects, `matchState` on an unscored record). Render both as empty, but do not collapse one into the other when you store them.
`[]` (empty array)	Searched, and nothing found — for `records[]` only when `status` is `complete`.
`"unknown"` (an enum value)	The source did not say; for example a criminal `currentStatus` of `unknown`.
`notQueried` / `absent` in `matchBasis`	You did not send the field, or the record has none, so it was not scored.
An enum value you do not recognise	A value added after your integration. Treat as "other" and log it.

Dates and timestamps

Timestamps are ISO 8601 with an offset: 2026-10-24T03:10:00+00:00.
Dates of birth carry a precision. Sex offender records: dob (ISO or null), birthYear, and dobPrecision ∈ exact, year, year_month, unknown. Criminal records: a dob object with date, birthYear, birthMonth, age, ageAsOf and dobPrecision ∈ full, month_year, year, age, none. Never compare a year-precision birth date as a full date.
Dates inside criminal cases (filedDate, offenseDate, dispositionDate) are ISO where the source gave a parseable date and otherwise the source's own text; read Understanding charges.