annotations/_docs/00_problem/input_data/data_parameters.md

Azaion.Annotations — Input data parameters

Inventory of every external input the service accepts, with shape, evidence, and validation behavior. Sources: REST DTOs, multipart form fields, env vars, database seed contract.

REST API inputs

POST /annotations

Field	Type	Required	Constraint	Evidence
image_bytes	byte[] (base64-encoded JSON or multipart)	yes	none enforced; sampled by XxHash3.Hash128 (per RB-04) for id derivation	Services/AnnotationService.cs GenerateAnnotationId(...)
mission_id	Guid (post RB-07; today flight_id)	yes	foreign-key style, but no FK enforced in schema today	Entities/AnnotationEntity.cs, _docs/02_document/glossary.md
media_type	MediaType enum	yes	Image=10 or Video=20; integer wire format	Models/Wire/MediaType.cs
detections	Detection[]	yes (≥0)	each detection: class id, normalised cx/cy/w/h, confidence	Models/Dto/DetectionDto.cs
metadata	optional payload	no	passes through to row	AnnotationDto.cs

PUT /annotations/{id} and PATCH /annotations/{id}/status

Same DTO shape on the body; id from path. Status transition values come from the AnnotationStatus wire enum: Pending=10, Accepted=20, Rejected=30, Deleted=40.

DELETE /annotations/{id}

Path param only. Soft-deletes the row (sets status to Deleted=40) and relocates files to deleted_dir (per RB-01 + glossary "Soft-delete").

GET /annotations and /dataset

Query string filters: mission_id, status, class_id, paging (offset, limit). Validation is implicit through [FromQuery] model binding — no explicit validators visible at controller level.

POST /media and POST /media/batch

Multipart form: IFormFile / IFormFileCollection, mission_id, media_type. No format whitelist visible at controller layer (verify in Step 14).

GET /media/{id}/file, GET /media/{id}/thumbnail

Path param only; returns binary stream.

Auth endpoints

Annotations no longer hosts POST /auth/login, POST /auth/refresh, or POST /auth/register. Token issuance and refresh are owned by the admin service. The only auth-related input on the annotations surface is the Authorization: Bearer <token> HTTP header on every non-/health request, validated by JwtBearerHandler against admin's JWKS:

Header	Required	Notes
Authorization	yes (everywhere except /health)	Bearer <ES256 JWT> issued by admin; iss / aud / exp / signature all validated; alg pinned to ES256

/settings/*

Each controller binds JSON DTOs from Models/Dto/* mirroring the system_settings, directory_settings, camera_settings, user_settings shapes in Database/DatabaseMigrator.cs.

Database seed inputs (boot-time)

DatabaseMigrator issues ON CONFLICT DO NOTHING inserts on:

Table	Seeded rows
directory_settings	one row with default paths
system_settings	one row (today still includes silent_detection; removal tracked by RB-02)
detection_classes	19 rows (ids 0–18): ArmorVehicle, Truck, Vehicle, Artillery, Shadow, Trenches, MilitaryMan, TyreTracks, AdditionArmoredTank, Smoke, Plane, Moto, CamouflageNet, CamouflageBranches, Roof, Building, Caponier, Ammo, Protect.Struct (Smoke and Plane share color #000080 — pre-existing data quirk, fixed by RB-06)
(There is no users table in this service — identity is owned by the admin service.)

Detection class catalog becomes admin-CRUD after RB-06.

Environment variables (process inputs)

Name	Required	Default	Purpose
DATABASE_URL	yes	none — fail-fast (ConfigurationResolver)	Postgres connection; URI form auto-converted to Linq2DB form
JWT_ISSUER	yes	none — fail-fast	Expected iss claim (admin's issuer)
JWT_AUDIENCE	yes	none — fail-fast	Expected aud claim (this service)
JWT_JWKS_URL	yes	none — fail-fast; HTTPS required	Admin's JWKS endpoint for ES256 key resolution
CorsConfig:AllowedOrigins	yes (prod, unless AllowAnyOrigin=true)	empty	Configured origins for the default CORS policy
CorsConfig:AllowAnyOrigin	optional	false	Explicit opt-in to permissive CORS (validator blocks empty allow-list in Production unless this is set)
RABBITMQ_HOST	optional	127.0.0.1	stream broker host
RABBITMQ_STREAM_PORT	optional	5552	stream listener port
RABBITMQ_PRODUCER_USER	optional	azaion_producer	stream auth user
RABBITMQ_PRODUCER_PASS	optional	producer_pass	stream auth pass
AZAION_REVISION	optional	unknown	image build stamp; logged at boot
ASPNETCORE_URLS	optional	http://+:8080	bind address
ASPNETCORE_ENVIRONMENT	optional	Production	bound to ASP.NET host

Stream consumer wire format

Outbound (this service is producer-only):

• Stream name: azaion-annotations
• Body: gzip(MessagePack(AnnotationStreamMessage))
• Schema fields (post RB-09): annotation_id, operation (QueueOperation), date_time, payload — see _docs/02_document/components/02_annotations-realtime-sync/description.md and ADR-013.

Cross-references

• Wire enum table: _docs/02_document/modules/wire-enums.md
• ER diagram: _docs/02_document/data_model.md
• Common error envelope: _docs/02_document/common-helpers/01_http-error-envelope.md