Field Mapping Reference
Common source columns and where they map in a DisclosureOS Observation
A quick-reference table for the most common source-data columns and their Observation targets. Use this alongside the Data Migration guide when writing a row mapper, or search the field explorer interactively.
| Source column | Observation path | Notes |
|---|
case_id, report_id, event_id | id | Prefix with a source tag: nuforc-12345. Keeps IDs unique and re-runs idempotent. |
source_name, catalog_name | dataSourceId | A short, stable string identifying the dataset, not the individual row. |
| (entire row) | extensions.migration.rawRow | Preserve the original source row verbatim for audit. |
| Source column | Observation path | Notes |
|---|
date, date_reported, event_date | temporal.date | Always a full YYYY-MM-DD. If the source only has month or year, pad with -01 and declare the real precision below. |
| (inferred from date format) | temporal.dateCertainty | exact only when provenance proves the date. Otherwise approximate, estimated, or unknown. |
| (inferred from date format) | temporal.dateGranularity | day, month, year, or unknown. Must match what the source actually knows. |
duration_seconds, duration_min | temporal.durationSeconds | Convert to seconds. Set to undefined when unknown (not zero). |
start_date + end_date | temporal.dateRange | Use { start, end } for events that span a period. |
time, time_utc | temporal.time | Freeform string; pair with timeZone when available. |
| Source column | Observation path | Notes |
|---|
city, state, region | location.name | Composite: "Phoenix, AZ". The human-readable label. |
country, country_code | location.country | Full name or ISO code. |
lat, latitude | location.latitude | Decimal degrees. Use 0 if absent (and mark coordinatePrecision accordingly). |
lng, longitude | location.longitude | Decimal degrees. |
| (inferred) | location.coordinatePrecision | gps_fix, locality, region, country, or unknown. |
location_type, site_type | location.siteType | Guard against the enum; fall back to unknown. |
altitude, elevation | location.elevation | Meters above sea level. |
| Source column | Observation path | Notes |
|---|
shape, object_shape | objectCharacteristics.shape | Must be a recognized enum value. Use isObjectShape(value) guard; carry unmappable shapes in extensions. |
size, apparent_size | objectCharacteristics.apparentSize | Freeform string. |
color | objectCharacteristics.color | Freeform string. |
count, number_observed | objectCharacteristics.numberObserved | Integer >= 0. |
| Source column | Observation path | Notes |
|---|
witness_count, num_witnesses | witnesses.count | Integer >= 0. |
witness_type, credibility | witnesses.credibility | Guard against enum values. |
witness_names | witnesses.descriptions | Array of strings. |
| Source column | Observation path | Notes |
|---|
speed, speed_kmh | movement.speedKmh | Kilometers per hour, >= 0. |
altitude, altitude_meters | movement.altitudeMeters | Flight altitude in meters, >= 0. |
flight_path, trajectory | movement.flightPath | Freeform description string. |
maneuver | movement.maneuvers | Array of strings describing observed maneuvers. |
| Source column | Observation path | Notes |
|---|
photo_url, video_url | media[] | Each entry needs { id, type, url } at minimum. Generate a stable id. |
primary_photo | featuredMedia | A single MediaAttachment promoted for display. |
document_url, pdf_url | documents[] | Use { id, type, url } for attached documents. |
| Source column | Observation path | Notes |
|---|
radar_data, ir_data | sensorEvidence.sensors[] | Each sensor reading needs { id, type }. Guard type against the enum. |
sensor_notes | sensorEvidence.notes | Freeform string. |
| Source column | Observation path | Notes |
|---|
disposition, explanation | Not a direct field; see below | Source dispositions are their assessments, not yours. |
Source dispositions should be attributed to the source as an origin claim, or carried in extensions for later review. Never map a catalog's explanation: "probably Venus" to your own origin claim. See the migration guide on fabricated evaluation.
| Source column | Observation path | Notes |
|---|
| (always set) | status | Use draft for all migrated records. Promotion is a separate review step. |
| (auto-set) | createdAt, updatedAt | ISO timestamps. createObservation sets these automatically. |
schema_version | schemaVersion | Set by the factory. Do not override unless deliberately pinning. |
- Guard enums: use factory guards like
isObjectShape() before assigning. Unmappable values should stay in extensions, not force-mapped to a close-but-wrong enum.
- Preserve the raw row: always carry the full source row in
extensions.migration.rawRow so any mapping decision can be audited later.
- Stable IDs: prefix source IDs (
nuforc-12345, mufon-67890) so re-runs are idempotent and provenance is visible.
- Field search: use the onboarding workspace to search by field name, type, or enum value when mapping.
