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:

{
  "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:

{
  "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)

{
  "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"}]
  }
}