Data Specification
Incident Data Specification v1.0
This document defines the comprehensive data schema for incidents in Sightline. The specification is designed to be future-proof and capture all observational, environmental, evidentiary, and metadata aspects.
For TypeScript type definitions, see Types Reference. For migration guidance, see Migration Guide.
Design Principles
- Minimal Required Fields - Only essential fields are required for backward compatibility
- Extensive Optional Fields - Rich optional data organized into logical sub-objects
- Standardized Taxonomies - Enum types for consistent categorization
- Internationalization Ready - Support for multiple countries' classification systems
- Computed Fields - Separate raw observations from analyzed/computed values
Schema Version
Current Version: 1.0.0
Quick Reference
Minimum Required Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
status | enum | Publication status |
createdAt | string | Record creation timestamp |
updatedAt | string | Record update timestamp |
temporal.date | string | Event date (YYYY-MM-DD) |
temporal.dateCertainty | enum | Date certainty level |
location.id | string | Location identifier |
location.name | string | Location name |
location.country | string | Country name |
location.longitude | number | Longitude (WGS84) |
location.latitude | number | Latitude (WGS84) |
Data Structure Overview
Incident
├── id, status, createdAt, updatedAt
├── summary, description
├── temporal (TemporalData)
├── location (LocationData)
├── objectCharacteristics (ObjectCharacteristics)
│ ├── objectCount
│ └── primaryObject (ObservedObject)
├── movement (MovementData)
├── witnesses (WitnessData)
├── sensorEvidence (SensorEvidenceData)
├── responseImpact (ResponseImpactData)
├── investigation (InvestigationData)
├── classification (ClassificationData)
├── sourceData (SourceData)
├── environment (EnvironmentalConditions)
├── media (MediaAttachment[])
└── relations (RelationalData)Sections
Temporal Data
Date, time, duration, and time-related fields
Location Data
Coordinates, site types, and proximity information
Object Characteristics
Shape, size, color, luminosity, and surface features
Movement & Behavior
Flight patterns, maneuvers, and interactions
Witness Information
Observer details and credibility factors
Sensor & Evidence
Detection methods, evidence types, and physical traces
Investigation
Investigation status, bodies, and verification
Classification
Hynek, Vallee, and incident type taxonomies
TypeScript Usage
import type { Incident } from '@disclosureos/sightline-core';
// Creating a new incident with minimum fields
const newIncident: Partial<Incident> = {
id: 'inc-001',
status: 'published',
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
temporal: {
date: '2024-01-15',
dateCertainty: 'exact',
},
location: {
name: 'Phoenix, Arizona',
country: 'United States',
longitude: -112.074,
latitude: 33.4484,
siteType: 'urban',
locationSensitivity: 'standard',
},
};Versioning
This specification uses semantic versioning:
- Major version: Breaking changes to required fields
- Minor version: New optional fields or enums
- Patch version: Documentation updates, typo fixes
Related
- Types Reference — TypeScript type definitions
- Configuration Reference — Config options
- Examples & Recipes — Real-world data examples
- Data Sources Guide — Connecting data sources
- Migration Guide — Upgrading between versions
- Changelog — Version history