Vessel Profile and Unified Data Model

The unified data model connects a vessel profile to trips, operational events, source reports, field-level extraction evidence, human review, and immutable audit history.

This guide defines the domain model. The generated API Reference remains authoritative for endpoint request and response schemas.

Entity relationships

Vessel
└── Trip
    └── HaulEvent
        └── SourceReport
            └── ExtractedField
                ├── Confidence
                ├── ReviewStatus
                └── AuditLog

One vessel can have many trips. A trip contains time-ordered haul or operational events. A source report records where imported or generated information came from. Each extracted field keeps its source location, normalized value, confidence, review status, and audit history.

Entity definitions

Vessel

The stable profile for one fishing vessel. It owns identifiers and descriptive attributes that remain valid across trips and reports.

Trip

A bounded voyage for one vessel. A trip links departure and return information to the events and reports produced during that voyage.

HaulEvent

A time-bounded operational event within a trip. eventType distinguishes haul, set, catch, transit, or another controlled event type without changing the common provenance model.

SourceReport

One source document, electronic form, recording group, or machine-generated report used to produce normalized data. It records source type, ownership, time range, version, and processing status.

ExtractedField

One field value extracted or projected from a SourceReport. It retains the original representation, normalized value, source reference, extraction method, confidence, and review decision.

Confidence

The machine or rule-based assessment attached to an extracted value. score is between 0 and 1; level provides the controlled low, medium, or high interpretation used by review workflows.

ReviewStatus

The current human-review state of an extracted value: pending, in_review, accepted, corrected, or rejected. A correction keeps both the extracted and reviewed values.

AuditLog

An append-only record of a material change or review decision. It records what changed, why, when, and which authorized actor or service performed the action without storing credentials.

Field dictionary

Vessel

Field	Type	Required	Description
`vesselId`	string	Yes	Stable Fishtube vessel identifier.
`name`	string	Yes	Vessel display name, unique within an organization.
`registrationNumber`	string or null	No	Official registration when available.
`flagState`	string or null	No	Controlled flag-state code.
`organizationId`	string	Yes	Tenant that owns the vessel profile.
`createdAt`, `updatedAt`	ISO-8601 datetime	Yes	Profile lifecycle timestamps.

Trip

Field	Type	Required	Description
`tripId`	string	Yes	Stable trip identifier.
`vesselId`	string	Yes	Parent vessel.
`tripNumber`	string or null	No	Operator or authority trip reference.
`departedAt`, `returnedAt`	ISO-8601 datetime or null	No	Voyage time boundary.
`departurePort`, `returnPort`	string or null	No	Controlled port references.
`status`	enum	Yes	`planned`, `active`, `completed`, or `cancelled`.

HaulEvent

Field	Type	Required	Description
`eventId`	string	Yes	Stable operational-event identifier.
`tripId`	string	Yes	Parent trip.
`eventType`	enum	Yes	`set`, `haul`, `catch`, `transit`, or another controlled type.
`startedAt`, `endedAt`	ISO-8601 datetime	Yes	Event time boundary.
`location`	object or null	No	Latitude and longitude when available.
`sourceReportIds`	string array	Yes	Reports supporting the event.

SourceReport

Field	Type	Required	Description
`sourceReportId`	string	Yes	Stable source-report identifier.
`tripId`, `eventId`	string or null	No	Related trip and event.
`sourceType`	enum	Yes	`observer_form`, `edge_recording`, `ai_analysis`, or `import`.
`sourceReference`	string	Yes	Non-secret document, segment, or recording-group reference.
`capturedAt`	ISO-8601 datetime	Yes	Time represented by the source.
`version`	string	Yes	Source schema or document version.
`processingStatus`	enum	Yes	`received`, `processing`, `ready`, or `failed`.

ExtractedField

Field	Type	Required	Description
`extractedFieldId`	string	Yes	Stable extracted-value identifier.
`sourceReportId`	string	Yes	Source report that produced the value.
`fieldKey`	string	Yes	Stable field-dictionary key.
`rawValue`	any or null	No	Value as represented by the source.
`normalizedValue`	any or null	No	Value normalized to the field dictionary.
`sourcePointer`	object	Yes	Page, segment, camera, timestamp, or JSON path provenance.
`extractionMethod`	enum	Yes	`manual`, `rule`, `ocr`, or `model`.
`confidence`	Confidence	Yes	Confidence assessment.
`reviewStatus`	ReviewStatus	Yes	Current review state.

Confidence

Field	Type	Required	Description
`score`	number	Yes	Inclusive value from `0` to `1`.
`level`	enum	Yes	`low`, `medium`, or `high`.
`method`	string	Yes	Rule, model, or manual assertion method.
`modelVersion`	string or null	No	Producing model version when applicable.

ReviewStatus

Field	Type	Required	Description
`status`	enum	Yes	`pending`, `in_review`, `accepted`, `corrected`, or `rejected`.
`reviewedValue`	any or null	No	Accepted correction without replacing extracted provenance.
`reasonCode`	string or null	No	Controlled reason for correction or rejection.
`reviewedBy`, `reviewedAt`	string/datetime or null	No	Authorized reviewer and decision time.

AuditLog

Field	Type	Required	Description
`auditLogId`	string	Yes	Stable audit-event identifier.
`entityType`, `entityId`	string	Yes	Changed entity reference.
`action`	string	Yes	Material action such as `field.corrected`.
`actorType`, `actorId`	string	Yes	Authorized user or service reference.
`occurredAt`	ISO-8601 datetime	Yes	Immutable event time.
`reasonCode`	string or null	No	Controlled business reason.
`changes`	object	Yes	Redacted before/after values or changed field names.
`correlationId`	string	Yes	Request or workflow correlation reference.

Sample JSON

{
  "vessel": {
    "vesselId": "vessel_demo_001",
    "name": "Example Vessel 01",
    "registrationNumber": null,
    "flagState": "TW",
    "organizationId": "organization_demo_001",
    "createdAt": "2026-07-01T08:00:00Z",
    "updatedAt": "2026-07-28T04:00:00Z"
  },
  "trip": {
    "tripId": "trip_demo_001",
    "vesselId": "vessel_demo_001",
    "tripNumber": "DEMO-2026-001",
    "departedAt": "2026-07-20T00:00:00Z",
    "returnedAt": null,
    "departurePort": "PORT_DEMO_A",
    "returnPort": null,
    "status": "active"
  },
  "haulEvent": {
    "eventId": "event_demo_001",
    "tripId": "trip_demo_001",
    "eventType": "haul",
    "startedAt": "2026-07-27T02:10:00Z",
    "endedAt": "2026-07-27T02:42:00Z",
    "location": {
      "latitude": 23.5,
      "longitude": 121.0
    },
    "sourceReportIds": ["source_report_demo_001"]
  },
  "sourceReport": {
    "sourceReportId": "source_report_demo_001",
    "tripId": "trip_demo_001",
    "eventId": "event_demo_001",
    "sourceType": "ai_analysis",
    "sourceReference": "recording_group_demo_001",
    "capturedAt": "2026-07-27T02:20:14Z",
    "version": "1.0",
    "processingStatus": "ready"
  },
  "extractedFields": [
    {
      "extractedFieldId": "field_demo_001",
      "sourceReportId": "source_report_demo_001",
      "fieldKey": "catch.species_code",
      "rawValue": "YFT",
      "normalizedValue": "YFT",
      "sourcePointer": {
        "segmentId": "segment_demo_001",
        "cameraId": "camera_demo_01",
        "timestampSeconds": 614
      },
      "extractionMethod": "model",
      "confidence": {
        "score": 0.94,
        "level": "high",
        "method": "object_detection",
        "modelVersion": "demo-model-1.0"
      },
      "reviewStatus": {
        "status": "accepted",
        "reviewedValue": "YFT",
        "reasonCode": null,
        "reviewedBy": "reviewer_demo_001",
        "reviewedAt": "2026-07-28T03:45:00Z"
      }
    }
  ],
  "auditLogs": [
    {
      "auditLogId": "audit_demo_001",
      "entityType": "ExtractedField",
      "entityId": "field_demo_001",
      "action": "field.accepted",
      "actorType": "user",
      "actorId": "reviewer_demo_001",
      "occurredAt": "2026-07-28T03:45:00Z",
      "reasonCode": null,
      "changes": {
        "reviewStatus": {
          "before": "pending",
          "after": "accepted"
        }
      },
      "correlationId": "request_demo_001"
    }
  ]
}

Entity relationships​

Entity definitions​

Vessel​

Trip​

HaulEvent​

SourceReport​

ExtractedField​

Confidence​

ReviewStatus​

AuditLog​

Field dictionary​

Vessel​

Trip​

HaulEvent​

SourceReport​

ExtractedField​

Confidence​

ReviewStatus​

AuditLog​

Sample JSON​

Entity relationships

Entity definitions

Vessel

Trip

HaulEvent

SourceReport

ExtractedField

Confidence

ReviewStatus

AuditLog

Field dictionary

Vessel

Trip

HaulEvent

SourceReport

ExtractedField

Confidence

ReviewStatus

AuditLog

Sample JSON