Spatial dimension type: extending dimension with a spatial descriptor for geometry/geography and spatial index data

[xavipereztr]

Hi everyone!

Context

At CARTO we are building AI Agent-driven geospatial analytics on top of the leading cloud data warehouses (BigQuery, Snowflake, Databricks). We are currently implementing current OSI spec in production as the semantic layer for our AI Agents and have learned a lot about what information a consuming tool actually needs to work correctly with spatial data.

We opened a broader discussion on geospatial support in #69, covering spatial field types, spatial relationship predicates, and geographic hierarchies. This post focuses on the most immediately practical piece: a first-class spatial dimension type at the field level.

The problem

Today, a field containing a WKB polygon geometry and a field containing an H3 spatial index string are both indistinguishable from a regular string column in OSI. An LLM-powered agent, BI tool, or query engine has no way to know that one should be rendered as a polygon layer, that the other represents a hexagonal grid cell in a hierarchical spatial system at a specific resolution, or that neither should be treated as a free-text field.

A bare boolean flag analogous to is_time would be a step forward, but not enough. Spatial columns carry metadata that is critical for correct tool behaviour: the geometry type, the coordinate reference system, the spatial index system and resolution, and the geographic granularity level. Without these, an AI Agent will have to guess.

This is directly related to the ongoing conversations in #25 and #17 about replacing is_time with a richer dimension_type or datatype enum, and to #55 on semantic field types. Our proposal is a concrete example of what a richer dimension type looks like in practice; spatial would be one of those types, carrying the metadata object that consuming tools need.

Proposal: spatial_data descriptor object inside dimension

We propose adding a spatial_data object within the existing dimension block. Its presence marks the field as a spatial dimension; its absence means the field is not spatial. All spatial sub-attributes live inside it, inherently scoped and only relevant for spatial fields.

dimension:
  spatial_data:                           # object; presence = spatial dimension
    type: ""                         # point | polygon | line | raster | spatial_index
    srid:                            # EPSG code, for geometry types
    spatial_index:                           # only present when type is spatial_index
      system: ""                     # h3 | quadbin | s2 | geohash
      resolution:                    # integer
      rollup_resolutions: []         # valid coarser resolutions
    geographic_level: ""             # e.g. "census_block_group", "h3_cell_res8"
    geographic_hierarchy:
      parent: ""
      children: []

Example 1 — polygon geometry at census block group level

- name: geom
  expression:
    dialects:
      - dialect: ANSI_SQL
        expression: "geom"
  dimension:
    spatial_data:
      type: polygon
      srid: 4326
      geographic_level: "census_block_group"
      geographic_hierarchy:
        parent: "census_tract"
        children: []
  description: "Block group boundary polygon (WGS84)"
  ai_context:
    instructions: >
      Use ST_CONTAINS or ST_INTERSECTS for spatial joins.
      Roll up to census tract via SUBSTR(geoid, 1, 11), to county via SUBSTR(geoid, 1, 5).
      When aggregating rate fields to a coarser level, use population-weighted averages,
      not simple sums or averages.

Example 2 — H3 spatial index at resolution 8

- name: h3
  expression:
    dialects:
      - dialect: ANSI_SQL
        expression: "h3"
  dimension:
    spatial:
      type: spatial_index
      index:
        system: h3
        resolution: 8
        rollup_resolutions: [7, 6, 5]
      geographic_level: "h3_res8"
      geographic_hierarchy:
        parent: "h3_res7"
        children: []
  description: "H3 cell index at resolution 8"
  ai_context:
    instructions: >
      Render as a hexagonal grid layer, not as points or polygons.
      Join via h3 = h3 or h3_toparent() for cross-resolution joins.
      Roll up with h3_toparent(h3, 7|6|5). Never apply ST_CONTAINS directly.
      When aggregating rate fields at a coarser resolution, use population-weighted averages.

Why at the spec level, not custom_extensions

We are currently shipping this pattern through CARTO's custom_extensions (vendor_name: CARTO) and it works. But we believe it belongs in the OSI core for three reasons:

Symmetry with is_time. The spec already treats time as a first-class dimension type. Spatial is equally fundamental and equally cross-industry — real estate, logistics, public health, retail, urban planning. It deserves the same treatment.

The underlying standards are open and stable. Geometry types (point, polygon, line) are OGC standards implemented by every major spatial database. H3, Quadbin, and Geohash are open-source and widely adopted. SRID codes follow the EPSG registry. None of this is vendor-specific.

Interoperability requires a common vocabulary. If spatial semantics live only in vendor custom_extensions, a tool consuming an OSI model from vendor A cannot understand the spatial metadata from vendor B — even if both describe the same H3 column identically. A spec-level spatial_data descriptor means any OSI-compliant consumer gains spatial awareness without vendor-specific knowledge.

That said, if the community prefers to keep the core spec narrow, we are happy to publish the spatial_data descriptor as a documented CARTO custom_extension with an open schema that others can adopt. We'd also be open to a two-layer approach: a minimal core (type + srid only) promoted to spec now, with richer attributes (index, geographic_level, geographic_hierarchy) as an extension to promote later.

We'd welcome feedback on the schema design and on where the right boundary is.

Thanks!