Skip to content
ArrayBridge / Docs

Scientific context API

Scalar metadata carries ophiolite.scientific-context/1: declarations of quantity, unit, vertical_datum, positive_direction and evidence; source horizontal CRS and coordinate unit; explicit-mask missing values; unresolved fields; declaring actor; and the project policy revision used during review. Meaning belongs to the exact asset revision. Project defaults are separate versioned control configuration.

Authenticated POST routes (browser sessions require CSRF):

  • /api/context/policy: {project_id}; project read required.
  • /api/context/save: {project_id, expected_revision, policy}; project administer required, optimistic revision check. Policy fields: preferred_crs, default_unit, default_vertical_datum, require_complete_context, expected_bounds (WGS84 west, south, east, north; no antimeridian crossing).
  • /api/maps/preview, /api/maps/import: existing GeoTIFF request plus context declarations and policy_revision. Review reports warnings/errors; publication enforces requirements and rechecks policy before committing.
  • /api/context/return-preview, /api/context/return: import request plus exact parent {project_id,asset_id,revision}, unchanged boolean and optional processing client evidence. Source read and destination publication access are checked. Changed outputs are separate derived assets. The server supplies lineage after acquiring the exact source. Exact no-op returns reuse the original revision.

Connector OAuth uses equivalent context/* operations through the existing connector endpoint. No native write RPC is exposed. Requests remain bounded, actor-scoped and idempotent through the existing command journal; retry the same command and body. The current QGIS dialog publishes to its source project; the API can publish a changed contribution to another authorized project under that project’s policy.

Native observed input references and parameters are client-reported claims, not server-verified execution. Operational traces are separate from durable scientific lineage. This contract does not add an OSDU raster schema or an alternative authority; it is qualified against the current project backend. LAS retains its existing well identity/measured-depth contract; this new raster review does not reinterpret it.

Project policy responses include options.units and options.vertical_references (ID → label maps). named_vertical_references is an administrator-managed list of at most64 unique local reference names, each at most128 characters. Built-in IDs are reserved. New reviewed imports validate unit/reference membership on the server; quantity compatibility is checked separately. Existing asset declarations remain immutable. Policy edits use the existing optimistic revision and permission checks.

Native operation reports and conditional replacement

Section titled “Native operation reports and conditional replacement”

POST /api/context/native-report (also connector context/native-report) accepts event_id, 1–16 exact inputs in one project, algorithm, application_version, finite duration_ms (0–86400000), success, and coverage (processing-signals or raster-menu-accepted-to-layer). It rechecks every input’s read access, deduplicates by authenticated actor/event ID, rejects changed retries, and caps stored native reports at 10000. These are client-reported diagnostic observations, not execution proofs. The returned trace_id may be null when tracing is disabled or not sampled.

Return requests accept replace_source: true and processing observation_id. Replacement requires the source project, a Workspace-imported editable source, unchanged quantity/unit/vertical reference/direction, equivalent horizontal CRS, and the same grid. Source identity/property are retained. Original files are retained for each result. Native expected-revision/source-version checks remain atomic at the authoritative backend. Changed CRS, grid or meaning requires a new asset. unchanged and replace_source cannot be combined.

Publication reauthorizes, verifies declared observed input access, retains exact parent lineage, journals command recovery and emits operation history with profile qgis-native-publication/1. Optional tracing links publication to a previously received same-actor native observation matching the source. An absent diagnostic report does not block scientific publication. No arbitrary client trace context is accepted. Diagnostic timestamps for native duration are anchored at server receipt and explicitly marked client-reported; server publication spans use server time.