CHIRPdb Data Guide
CHIRPdb Data Guide
CHIRP Maritime · CHIRPdb
CHIRPdb takes published maritime incident reports - PDF documents - and turns them into structured, searchable data. This page explains what the database holds, how the pieces fit together, and the principles that keep the data trustworthy.
Every report goes through the same journey, and the database is organised around it.
The PDF is read and broken down: who published it, what incident it describes, which vessels and people were involved, and its full text - sentence by sentence, in reading order.
PDFs are messy - broken lines, headers bleeding into text. An AI pass cleans up the extracted text so the analysis that follows works from an accurate version of the report.
Findings are extracted: safety issues, recommendations, causal-factor codes from CHIRP's SHIELD taxonomy, and the people, vessels and places named in the narrative.
Each report carries a status so you always know how far it has progressed and how much to trust its data:
Provisional means the automated pipeline has finished; Verified means an analyst has confirmed the results. If the AI correction ever fails, the report is kept with its original extracted text and flagged for attention - a document is never lost.
This is the complete entity-relationship diagram - every table in the database and every connection between them. It's dense by design; the sections that follow break it into readable pieces.
The factual record: each report, who published it (MAIB and other investigating bodies), and the incident it describes - what happened, when, where, how severe. Each incident links to the vessels involved, and each vessel to the people affected aboard it.
The full text of every report, stored sentence by sentence in original reading order, with headings preserved. Sentences are grouped into passages for analysis, and every person, vessel or place named in the narrative is recognised and recorded - including when the same thing is referred to in different ways ("the Master", "Captain Smith").
What the analysis extracts and what analysts verify: safety issues, recommendations (and which organisations they're directed at, with implementation tracked over time), and SHIELD causal-factor codes - the shared vocabulary that makes incidents comparable and countable across thousands of reports.
Information many reports point at but none owns: the SHIELD taxonomy itself, legislation that safety issues cite, and the organisations recommendations are addressed to. Stored once, referenced everywhere - so "all recommendations directed at organisation X" is one question, not a search through every report.
Four kinds of finding come out of the analysis stage. They all share one
anchor: the
passage (a group of consecutive sentences, called a
chunk in the schema). Whatever the finding, you can follow
it back to the passage, and from the passage to the exact sentences of
the original report.
The most general finding: a typed note about a passage - a summary, an interpretation, a classification. Each note records what kind of analysis it is and its content, so different analytical passes can sit side by side on the same text without interfering.
SHIELD is CHIRP's taxonomy of human factors in maritime incidents. It's seeded into the database as reference data: 96 codes in 20 categories under three top-level groups. Because the codes are a controlled vocabulary - not free text - "how many incidents involved fatigue?" is a count, not a judgement call.
5 categories · 19 codes
12 categories · 62 codes
3 categories · 15 codes
Each code has a short identifier, a title, and a full definition - for example PPC2Fatigue: "diminished mental capability due to fatigue, restricted or shortened sleep… degrades operator performance."
A named safety concern the report raises - each one anchored to the passage it came from, carrying its own verification flag, and optionally linked to the legislation it relates to. The legislation register is shared reference data, so every issue citing the same regulation points at the same record.
safety_issue_legislation) also stores the passage of
text that made the connection - so the citation itself is traceable.
The actions a report calls for. Each recommendation records the action in the report's own words and which organisations it is directed at. Because one recommendation can address several organisations - and each may act on it at a different time - implementation is tracked per organisation, with the date stamped automatically when it's marked implemented.
recommendation_organisations)
carries
is_implemented and implemented_at - so
"which recommendations to organisation X are still open?" is a direct
query.
Beyond findings, the analysis tracks who and what each report is about. A typical report mentions a master, a chief officer, one or more named vessels, an operating company, a port, specific equipment. The narrative entity model records each of these as a first-class thing - not just words in a sentence - so questions like "every report involving this vessel" or "every sentence that mentions the chief engineer" become directly answerable.
Entity types are a controlled vocabulary, seeded into the database. New types can be added by inserting a row - no engineering work - but the analysis can only ever use types from this list, which keeps the data countable and consistent.
| Type | What it covers |
|---|---|
| person | Individual person - e.g. master, chief officer, pilot, crew member |
| vessel | Ship or vessel - e.g. named ship or vessel class reference |
| organisation | Organisation or body - e.g. port authority, flag state, operator, classification society |
| location | Geographic location - e.g. port, anchorage, waterway, country |
| equipment | Equipment, instruments, or systems - e.g. life jacket, radar, VHF radio, fire suppression system |
The model separates the thing from the places it appears. An entity is one real-world thing within a report, with a single canonical name. A mention is one occurrence of it in one sentence - recording the exact words used and precisely where in the sentence they sit (the character positions). That's what lets "the Master", "Captain Smith" and "he" all resolve to the same person while every individual reference stays findable.
person - with two
mentions: "The Master" and "Captain Smith", each stored with its
exact character positions in the sentence.
vessel - with one mention.
The schema follows a database standard called Third Normal Form: each piece of information lives in exactly one place, and everything else refers to it. No copies drifting out of date - correct a vessel's name once and every report reflects it. In the few cases where a value is deliberately duplicated for speed, the database itself enforces that the copies always agree.
Classifications - SHIELD codes, entity types - come from managed lists, not typed-in text. "Fatigue" is always the same code, so counting and comparing across reports actually works. New codes can be added without engineering work.
Rules live in the database itself, not just in the application. When an analyst verifies a finding, the timestamp is recorded automatically; when data is written, its consistency is checked at the door. Nothing depends on software remembering to do the right thing.
AI-extracted findings start unverified. Analyst confirmation is an explicit, timestamped step - so you can always distinguish "the machine suggested this" from "a person confirmed this", and report on either.