# Common UI Document Properties

## Overview
All OCLI UI Documents are registered in the database as GeoJSON Feature objects (row per document) in the `features` table. The UI consumes these Features to locate the document payload, render it on the map or in panels, and display legends/metadata.

## Standard GeoJSON Envelope
- `type`: `Feature`
- `id`: optional string/UUID for stable reference (also present in properties as `uid`)
- `geometry`: Geometry appropriate for the document (often the footprint or point of interest)
- `properties`: A JSON object with standard and type-specific fields (see below)

## Common Properties
The following properties MUST or SHOULD be present across all document types (DB-aligned).

### Required
- `type` (string): One of the supported document types (Scalar, Mesh, PointCloud, Cluster, Image, Report, Media, Vector, DEM, Actor, Shape).
- `source` (object): How and where to load the document. Typically includes:
  - `url` (string): e.g., `/tiler/tiles/{z}/{x}/{y}@2x` or `/s3/<bucket>/<key>` or `wss://...`
  - `type` (string): `Raster` | `GeoJSON` | `Mesh` | `PointCloud` | `Media` | `Report` | `websocket`
  - `url_params` (object) [optional]: e.g., `{ "url": "http://rook-ceph.../staging/<path>.tiff" }` when using the tiler
  - `tileSize`, `max_zoom`, `attribution` [optional]

### Recommended
- `roles` (array[string]): e.g., `["public_read", "demo_read", "draft_read"]`
- `Bucket` (string), `Endpoint` (string), `ResultKey` (string), `version` (number), `friendly_name` (string)
- `classification` (object): e.g., `{ "ocli": [5], "metadata_preset": [6] }`
- `visible_metadata` (array[object]): items with `{label, value}` surfaced by UI
- `bands` (object): for raster-like documents; see "Bands and band_meta" below
- `legend` (object): Links and rules for the legend panel
- `metadata` (object): Freeform, but keep stable keys for pipelines

## Legend
Use the `legend` property to drive UI rendering of labels and colors.

- `legend.title`: Title displayed in the legend dock.
- `legend.href`: External legend image/HTML if applicable.
- `legend.rules`: Array of rules.
  - `value` | `range`: Single value or numeric range.
  - `color`: Hex or rgba string.
  - `label`: Display name.

## Metadata Presets
Provide predictable keys for fast mapping in UI. Common presets:

- `metadata.sensor` (e.g., S1A, TSX)
- `metadata.acquisition_time` (ISO 8601)
- `metadata.product_id`
- `metadata.processing_level` (e.g., L1, ARD)
- `metadata.gsd` (number, meters)

## Classifications
- `classification.level`: e.g., UNCLASSIFIED, INTERNAL, CONFIDENTIAL
- `classification.distribution`: e.g., NOFORN, REL TO XYZ
- `classification.notice`: short banner to render in UI


---

## OCLI Source object
In the production database, OCLI uses `properties.source` to describe where and how to load the document payload. This replaces the legacy `payload` object used in earlier drafts of this documentation.

Typical structure:

```json
{
  "properties": {
    "source": {
      "url": "/tiler/tiles/{z}/{x}/{y}@2x",
      "type": "Raster",
      "max_zoom": 18,
      "tileSize": 512,
      "url_params": {
        "url": "http://rook-ceph-rgw-geo.rook-ceph.svc:80/staging/<project>/<path>/<file>.tiff"
      },
      "attribution": "optional attribution string"
    }
  }
}
```

Other common `source.type` values and expectations:
- Raster: tile endpoint as above (COG/GeoTIFF behind the tiler) or direct image URL for thumbnails
- GeoJSON: `{"url": "/s3/<bucket>/<key>.geojson", "type": "GeoJSON"}`
- Mesh: `{"url": "/s3/<bucket>/<key>.glb", "type": "Mesh"}`
- PointCloud: `{"url": "/s3/<bucket>/<key>.las.geojson", "type": "PointCloud"}`
- Media: `{"url": "/s3/<bucket>/<key>.<ext>", "type": "Media"}`
- Report: `{"url": "/s3/<bucket>/<key>.pdf", "type": "Report"}`
- websocket: `{"url": "wss://...", "type": "websocket"}` for live Actor/streamed data

### Additional standard fields used by OCLI
At the `properties` level you will often see these fields:
- `roles`: e.g., ["public_read", "demo_read", "draft_read"]
- `Bucket`: S3 bucket or namespace (e.g., `staging`)
- `Endpoint`: S3/HTTP endpoint (e.g., `https://s3.optoss.net`)
- `ResultKey`: Storage key/path for the document root
- `version`: number (pipeline or schema specific)
- `friendly_name`: human-readable path/name
- `classification`: object or arrays, e.g., `{ "ocli": [5], "inspire": [], "metadata_preset": [6] }`
- `visible_metadata`: array of `{label, value}` pairs to surface in UI
- `centroid`: GeoJSON Point with [lon, lat, (z)]
- `geoReference`: e.g., `{ "position": [lon, lat, z], "model_crs": "EPSG:4978" }` for 3D assets
- `layers`: array of layer descriptors for 3D meshes/voxels

### Bands and band_meta
Raster-like documents (Image, DEM, Scalar, Cluster) often include a `bands` block:

```json
{
  "properties": {
    "bands": {
      "band_ids": ["R", "G", "B", "A"],
      "band_meta": [
        {"band": 1, "name": "R", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255},
        {"band": 2, "name": "G", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255}
      ]
    }
  }
}
```
Optional keys in `band_meta`: `mean`, `stdDev`, `color`, `color_map`, `noDataValue`, `description`.

### Migration note (legacy payload → source)
- Legacy drafts in this folder used `properties.payload` with `href` and `media_type`.
- The production schema uses `properties.source` with `url` and `type` (plus tiler parameters for rasters).
- When updating or creating documents, prefer `properties.source`.
- Note: the UI/DB do not inspect `payload.media_type`; if present in legacy examples, treat it as informational only.

## DB‑aligned Base Feature Example (Image/Raster)
```json
{
  "type": "Feature",
  "geometry": {"type": "Polygon", "coordinates": [[[4.4984604, 53.2402083], [4.4649804, 52.2534568], [6.0716785, 52.222566], [6.1417699, 53.2082014], [4.4984604, 53.2402083]]] },
  "properties": {
    "type": "Image",
    "roles": ["public_read"],
    "Bucket": "staging",
    "source": {
      "url": "/tiler/tiles/{z}/{x}/{y}@2x",
      "type": "Raster",
      "max_zoom": 16,
      "tileSize": 512,
      "url_params": {
        "url": "http://rook-ceph-rgw-geo.rook-ceph.svc/staging/default/composite/example.tiff"
      }
    },
    "version": 1.4,
    "Endpoint": "https://s3.optoss.net",
    "ResultKey": "default/composite/example",
    "friendly_name": "default/composite/example",
    "bands": {
      "band_ids": ["R","G","B","A"],
      "band_meta": [
        {"band": 1, "name": "R", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255},
        {"band": 2, "name": "G", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255},
        {"band": 3, "name": "B", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255},
        {"band": 4, "name": "A", "type": "Byte", "min": 0, "max": 255, "domain_min": 0, "domain_max": 255}
      ]
    },
    "classification": {"ocli": [3]},
    "visible_metadata": [{"label": "Instrument", "value": "MSI"}]
  }
}
```