Data Contribution Guide
This guide explains how to contribute incident data to Sightline projects.
Before You Begin
Data Requirements
All contributed data must:
- Follow the schema - Match the Data Specification
- Include sources - Every incident needs verifiable source references
- Be accurate - Coordinates, dates, and facts must be verified
- Respect privacy - No personal information without consent
- Be legal - No classified or restricted information
Data Quality Standards
| Field | Standard |
|---|---|
| Coordinates | Accurate within reasonable precision |
| Dates | ISO 8601 format (YYYY-MM-DD) |
| Sources | At least one verifiable reference |
| Summary | Factual, neutral language |
Contribution Methods
Method 1: Static JSON Files
For small to medium datasets (under 1000 incidents).
Create Your Data File
{
"incidents": [
{
"id": "contrib-001",
"status": "published",
"createdAt": "2024-01-15T00:00:00Z",
"updatedAt": "2024-01-15T00:00:00Z",
"temporal": {
"date": "2023-06-15",
"dateCertainty": "exact"
},
"location": {
"name": "Location Name",
"country": "Country",
"latitude": 0.0000,
"longitude": 0.0000,
"siteType": "urban",
"locationSensitivity": "standard"
},
"summary": "Brief description of the incident.",
"sourceData": {
"sources": [
{
"type": "news_article",
"name": "Source Name",
"url": "https://example.com/article",
"accessDate": "2024-01-15"
}
]
}
}
]
}Validate Your Data
Manually verify your data file:
- Valid JSON syntax
- All required fields present
- Coordinates are valid numbers
- Dates are valid ISO format
- Enum values match specification
Submit via Pull Request
- Fork the repository
- Add your file to
public/data/ - Update
map.config.tsto include your source (optional) - Create a PR with description of:
- Data source
- Verification methodology
- Number of incidents
- Any caveats
Method 2: API Integration
For larger datasets or real-time data.
Set Up Your API
Your API should return data in this format:
{
"incidents": [
{ /* Incident objects */ }
],
"meta": {
"total": 150,
"page": 1,
"pageSize": 100
}
}Contact Maintainers
For API integrations, contact maintainers to discuss:
- API stability and availability
- Data refresh frequency
- Authentication requirements
- Terms of use
Method 3: Database Integration
For organizations wanting direct database access.
Supabase Setup
- Create a Supabase project
- Set up the incidents table (see Data Sources Guide)
- Configure Row Level Security
- Share credentials securely with maintainers
Data Schema
Minimum Required Fields
{
id: string; // Unique identifier
status: "published"; // Must be "published" for display
createdAt: string; // ISO timestamp
updatedAt: string; // ISO timestamp
temporal: {
date: string; // YYYY-MM-DD
dateCertainty: string; // "exact" | "approximate" | "estimated"
};
location: {
name: string; // Location description
country: string; // Country name
latitude: number; // -90 to 90
longitude: number; // -180 to 180
siteType: string; // See enum values
locationSensitivity: string; // See enum values
};
}Recommended Additional Fields
{
summary: string; // Brief description
sourceData: {
sources: [{
type: string; // "news_article" | "government_document" | etc.
name: string; // Source name
url?: string; // Link if available
accessDate: string; // When accessed
}]
};
classification: {
incidentType: string; // "sighting" | "encounter" | etc.
};
}Full Schema Reference
See Data Specification for all available fields.
ID Conventions
Use meaningful, unique IDs:
Format: [source]-[region]-[year]-[sequence]
Examples:
- mufon-us-2024-0001
- nuforc-ca-2023-0542
- geipan-fr-2024-0015Source Documentation
Every incident should reference at least one source:
"sourceData": {
"sources": [
{
"type": "government_document",
"name": "AARO Report",
"url": "https://www.aaro.mil/report-123",
"accessDate": "2024-01-15",
"reliability": "official"
},
{
"type": "news_article",
"name": "Local News Coverage",
"url": "https://news.example.com/article",
"accessDate": "2024-01-10",
"reliability": "secondary"
}
],
"primarySource": "government_document"
}Source Types
| Type | Description |
|---|---|
government_document | Official government reports |
news_article | News media coverage |
academic_paper | Peer-reviewed research |
witness_statement | First-hand accounts |
foia_document | FOIA-released documents |
video | Video evidence |
photograph | Photographic evidence |
radar_data | Radar records |
Verification Guidelines
Coordinate Verification
- Use Google Maps or similar to verify locations
- Document coordinate precision in
coordinatePrecisionfield - For sensitive locations, use area-level precision
Date Verification
- Cross-reference multiple sources when possible
- Use
dateCertainty: "approximate"for uncertain dates - Document date range if exact date unknown
Source Verification
- Prefer official/primary sources
- Include multiple sources when available
- Note reliability level of each source
Sensitive Data
Location Sensitivity
Use appropriate sensitivity levels:
| Level | Use For |
|---|---|
critical | Near nuclear/C2 facilities |
high | Near major military bases |
moderate | Near government facilities |
standard | Public locations |
Privacy Considerations
- Remove witness names unless publicly available
- Use general locations for private property
- Obtain consent for any personal information
Submission Checklist
Before submitting:
- JSON validates without errors
- All required fields present
- Coordinates verified
- At least one source per incident
- No personal information without consent
- Enum values match specification
- PR description complete
Review Process
- Automated checks - CI validates JSON and schema
- Maintainer review - Data quality assessment
- Merge - If approved, data is added
- Attribution - Contributors credited in release notes
Questions?
- Open an issue with the
data-contributionlabel - Join community discussions
- Contact maintainers for sensitive data questions