Drone Data Contract¶
DroneMission¶
Required operational fields include:
mission_iddrone_idoperator_idoperator_roleregionpack_idmission_typestarted_atended_atstatuslaunch_locationintended_arearecommended_patternhuman_approvedautonomous_flight_controlsourcevisibilitynotes_public
Internal mission notes are stored privately and removed from public responses.
DroneTelemetryPoint¶
Read-only bridge records use the same telemetry contract as operator-submitted points.
mission_iddrone_idtimestamplatitudelongitudealtitude_mheading_deggroundspeed_mpsbattery_percentgps_fix_qualitycamera_heading_degcamera_pitch_degsourcesource_typepublic_visibility- bridge source:
mavlink_bridge - bridge source types:
fixture_replay,tlog_replay,udp_live
Validation bounds:
- latitude:
-90to90 - longitude:
-180to180 - altitude:
-20to1000meters - heading/camera heading:
0to360 - camera pitch:
-180to180 - battery:
0to100 - timestamp is required and must parse as a date/time
DroneObservation¶
observation_idmission_iddrone_idtimestamplatitudelongitudeobservation_typecountestimated_length_mprobable_speciesspecies_assessment_sourcespecies_confidenceobserved_behaviorbehavior_sourceevidence_typemedia_referencemedia_reference_type(enum:local_filename,drone_clip_id,camera_card_reference,external_url,agency_evidence_id,private_case_reference,none)media_timestampanalyst_review_status(enum:unreviewed,needs_review,in_review,reviewed,rejected,inconclusive)analyst_reviewed_atanalyst_reviewer_roleanalyst_notes_privatepublic_review_summaryreview_outcome(enum:no_public_change,confirms_operator_observation,downgrades_operator_observation,upgrades_operator_observation,species_uncertain,false_positive,duplicate,unusable_media)evidence_confidenceconfidencereview_statussourcesource_typepublic_visibility
Private analyst or internal notes, analyst private notes, analyst reviewer role, analyst review timestamps, raw media references, media reference types, and media timestamps are never exposed through public endpoints. Media-reference visibility is private-by-default until a future phase defines public-safe attachment release rules.
Observation Types¶
shark_sightingunknown_large_marine_animalno_sighting_patrol_resultcarcassbaitfish_congregationmarine_mammal_activitywater_clarity_observationsurf_line_activityswimmer_densityvessel_activityother
The Drone Operator Console presents uppercase UI labels and maps them to this API enum. POOR_VISIBILITY maps to water_clarity_observation; NO_SIGHTING_PATROL maps to no_sighting_patrol_result; OTHER maps to other.
Console Field Mapping¶
Console required fields:
mission_idobservation_typeobserved_atlatitudelongitudeobserver_rolevisual_confidenceprovenance
| Console field | API field |
|---|---|
observed_at |
timestamp |
visual_confidence |
confidence |
species_guess |
probable_species |
estimated_size_m |
estimated_length_m |
estimated_count |
count |
provenance |
source |
observer_role |
source_type |
behavior_notes |
observed_behavior |
operator_notes |
internal_notes |
public_summary, visibility_notes, surf_zone_notes |
public-safe analyst note text |
Expected console provenance values:
drone_operator_visuallifeguard_visualanalyst_reviewed_visualofficial_agency_reportproject_owner_analyst_visual_assessmentdemo_fixture
Validation bounds:
- latitude:
-90to90 - longitude:
-180to180 - count:
1to1000, exceptno_sighting_patrol_resultmay use0 - estimated length:
0.1to20meters when present - confidence/species confidence/evidence confidence:
0to1; impossible values are rejected rather than clamped - timestamp is required and must parse as a date/time
- observation type, review status, and species assessment source must use known enumerations
Species guesses remain provisional operator metadata unless confirmed by an official source or qualified review. official_species_classification remains separate from operator guess fields.
Analyst Review Fields¶
Phase 25D-A adds metadata-only analyst review fields. These are annotations on existing observations:
analyst_review_status,review_outcome,public_review_summary,evidence_confidenceare review metadataanalyst_notes_private,analyst_reviewer_role,analyst_reviewed_at,media_reference,media_reference_type, andmedia_timestampare private and excluded from public responsesmedia_reference_typeandmedia_timestampdescribe the associated media internally (reference only; no upload or hosting)- The PATCH endpoint updates analyst review fields on an existing observation without modifying the original
See Observation Analyst Review.
Local Attachment Metadata Fields¶
Phase 25D-C implements metadata-only local attachment records behind MEDIA_ATTACHMENTS_ENABLED=false by default. Phase 25D-D hardens metadata validation before any binary upload work exists. No binary upload, download, external URL fetch, computer vision, species inference, sighting inference, or media analysis is implemented. See Local Media Attachment Prototype and Media Attachment Storage Design.
Attachment records include internal fields such as attachment_id, observation_id, mission_id, storage_backend, storage_key, original_filename, stored_filename, media_kind, mime_type, file_size_bytes, captured_at, uploaded_at, uploaded_by_role, review_visibility, public_release_status, checksum_sha256, evidence_confidence, analyst_review_status, and public_summary.
Public responses never expose storage_key, stored_filename, original_filename, checksum_sha256, uploaded_by_role, local paths, or raw media references. Public feeds do not expose attachment IDs or private attachment metadata.
Attachment metadata validation rejects path traversal, absolute paths, Windows drive-root paths, parent-directory references, executable/script filename extensions, unsupported enum values, invalid checksums, impossible file sizes, malformed timestamps, and overlong summaries. original_filename is private display metadata only and is never used as a storage path.
Attachment endpoints:
POST /api/v1/drone/observations/{observation_id}/attachmentsGET /api/v1/drone/observations/{observation_id}/attachmentsPATCH /api/v1/drone/observations/{observation_id}/attachments/{attachment_id}/review
Attachment endpoints are local-prototype routes and require MEDIA_ATTACHMENTS_ENABLED=true.
Map-Ready Feed Fields¶
Each feed item includes latitude, longitude, timestamp, observation type, review status, confidence, mission ID, source type, active pack, explanation summary, recommended action, recommended surveillance pattern, expiration, and data freshness.
UAV Operator Feedback¶
Phase 25F adds research-only UAV operator feedback records. These records collect field requirements and workflow notes from UAV operators, lifeguards, coastal authorities, researchers, and agency teams.
Feedback records include:
feedback_idsubmitted_atsubmitter_roleorganization_typeregioncountrycontact_allowedcontact_referencedrone_platformdrone_modelflight_apptelemetry_availabletelemetry_export_formatmedia_workflowno_sighting_patrols_loggedobservation_fields_usedprivacy_constraintscontrolled_airspace_notesoperator_pain_pointsrequested_featuressuggested_observation_typesworkflow_notespublic_summaryinternal_notes_privatereview_statusreviewed_atreviewer_rolerequirements_tags
Private fields such as contact_reference, internal_notes_private, reviewed_at, and reviewer_role are excluded from public-safe output.
Feedback records are requirements input only. They do not create drone observations, sightings, warnings, public alerts, replay facts, surveillance feed items, scoring changes, or drone operations.