Data Models
Schemas
TypeScript interfaces for the Passport data model
These schemas define the structure of passports and events. All data follows append-only principles — events can be added but never modified or removed.
Design Principles
Append-Only
Once data is written, it cannot be changed. Corrections are new events.
Minimal PII
No personal data in schemas. References only for custody/ownership.
Type-Safe
Discriminated unions and strict typing prevent invalid states.
Schema Definitions
Passport
Core passport record structure
Passport Interface
typescript
interface Passport {
passportId: string // Unique identifier (non-personal)
assetType: string // "diamond" | "vehicle" | "machinery" | etc.
schemaVersion: string // Schema version for forward compatibility
status: PassportStatus // "active" | "flagged" | "retired" | "revoked"
mintedAt: string // ISO 8601 timestamp
mintedBy: string // Issuer node reference
attributeHash: string // Hash of bound attributes
}
type PassportStatus = "active" | "flagged" | "retired" | "revoked"PassportEvent
Base event structure for all event types
PassportEvent Interface
typescript
interface PassportEvent {
eventId: string // Unique event identifier
passportId: string // Reference to parent passport
eventType: EventType // Type of event
timestamp: string // ISO 8601 timestamp
data?: Record<string, any> // Event-specific data
signature?: string // Cryptographic signature (if signed)
appendedBy: string // Node that appended the event
}
type EventType =
| "provenance"
| "verification"
| "custody_transfer"
| "status_change"
| "service"
| "incident"
| "dispute"
| "external_integration"VerificationEvent
Signed attestation from a verifier
VerificationEvent Interface
typescript
interface VerificationEvent extends PassportEvent {
eventType: "verification"
verifier: {
nodeId: string // Verifier node identifier
type: "verifier_node" | "cer_institute"
name?: string // Optional display name
}
attestation: {
verified: boolean // Did verification pass?
grade?: string // Optional grade/rating
notes?: string // Optional notes
expiresAt?: string // Optional expiration
}
signature: string // Required: cryptographic signature
}TransferEvent
Custody change record
TransferEvent Interface
typescript
interface TransferEvent extends PassportEvent {
eventType: "custody_transfer"
from: {
nodeRef: string // Reference only, no PII
}
to: {
nodeRef: string // Reference only, no PII
}
notes?: string // Optional transfer notes
consentProof: string // Proof of consent from current custodian
}StatusEvent
Status change record
StatusEvent Interface
typescript
interface StatusEvent extends PassportEvent {
eventType: "status_change"
previousStatus: PassportStatus
newStatus: PassportStatus
reason: string // Required: reason for change
changedBy: string // Admin/operator node reference
reversible: boolean // Can this be undone?
}Implementation Notes
Event Inheritance
All event types extend PassportEvent. Use the eventType field as a discriminator for type narrowing in TypeScript.
Signature Requirements
VerificationEvent MUST include a signature. Other event types may optionally include signatures depending on security requirements.
Schema Versioning
The schemaVersion field in Passport enables forward compatibility. When schemas evolve, older passports remain valid under their original version.