> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# APRS data standard

> How Axiom normalizes every record with the AI-Ready Public Record Standard envelope — the contract behind every Locus signal, score, and join key.

Every row in the Axiom Locus data catalog carries a uniform set of metadata columns called the **APRS envelope** (AI-Ready Public Record Standard). The envelope makes it possible to deduplicate records, sync incrementally, cite sources, join across datasets, and feed data directly into ML pipelines.

## Envelope columns

All catalog tables include these columns:

| Column                  | Type          | Description                                                                             |
| ----------------------- | ------------- | --------------------------------------------------------------------------------------- |
| `record_id`             | `text`        | Stable URN for the source document. Format: `urn:aprs:record:{namespace}:{source}:{id}` |
| `chunk_id`              | `text`        | Deterministic SHA-256 URN for vector indexing. Format: `urn:aprs:chunk:{hex}`           |
| `source_system`         | `text`        | Originating system name (e.g. `granicus`, `aisstream`, `derived`).                      |
| `source_uri`            | `text`        | URL or URN pointing to the original upstream record.                                    |
| `schema_version`        | `text`        | Semver-tagged APRS profile (e.g. `aprs.civic/1.0.0`).                                   |
| `normalization_version` | `text`        | Semver of the normalization pipeline that produced this row.                            |
| `acl_tier`              | `text`        | Access tier: `research`, `commercial`, or `internal`.                                   |
| `occurred_at`           | `timestamptz` | When the real-world event happened.                                                     |
| `ingested_at`           | `timestamptz` | When Axiom first ingested the record.                                                   |
| `modified_at`           | `timestamptz` | When the record was last updated in Axiom.                                              |

## Schema profiles

Each data domain uses a versioned schema profile in `schema_version`:

| Profile                 | Domain                                               |
| ----------------------- | ---------------------------------------------------- |
| `aprs.civic/1.0.0`      | Civic records (meeting minutes, ordinances, filings) |
| `aprs.permits/1.0.0`    | Building permits                                     |
| `aprs.events/1.0.0`     | Axiom-curated events                                 |
| `aprs.urban/1.0.0`      | Cell-level urban scores                              |
| `aprs.maritime/1.0.0`   | AIS positions and vessel visits                      |
| `aprs.commodity/1.0.0`  | Commodity prices, crop reports, and freight data     |
| `aprs.complaints/1.0.0` | 311 service requests                                 |
| `aprs.poi/1.0.0`        | Points of interest                                   |

## Domain-specific envelope extensions

Some data domains extend the base envelope with additional indexed columns that are critical for their query patterns. These columns appear alongside the ten standard envelope columns and are tracked in the [envelope coverage dashboard](/codex/envelope-coverage).

| Column     | Type   | Domain                                           | Description                                                                                           |
| ---------- | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `h3_index` | `text` | Geospatial tables                                | Uber H3 cell identifier at resolution 8. Enables spatial joins and cell-level scoring.                |
| `mmsi`     | `text` | Maritime tables (`port_events`, `ais_positions`) | 9-digit Maritime Mobile Service Identity. Enables vessel-level joins and identity-spoofing detection. |

Both columns are indexed and included in the `codex_compliance_summary` view as `h3_index_pct` and `mmsi_pct`.

## Record ID format

Every `record_id` follows a deterministic URN pattern so the same real-world record always maps to the same identifier:

```
urn:aprs:record:{namespace}:{source_system}:{local_id}
```

For example:

* `urn:aprs:record:civic:granicus:12345` — a civic record ingested from Granicus
* `urn:aprs:record:maritime:vessel_visit:9434210:USLAX:7891` — a vessel visit keyed by IMO, port, and visit ID
* `urn:aprs:record:commodity:conab:soy:2025/26:09:MT` — a crop report keyed by commodity, crop year, report month, and state

## Access tiers

The `acl_tier` column controls data visibility:

| Tier         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `research`   | Publicly available data suitable for research and analysis. |
| `commercial` | Licensed data available to commercial-tier subscribers.     |
| `internal`   | Axiom-internal data not exposed through APIs.               |

## Querying with envelope fields

You can use envelope columns to filter, sort, and join across any Locus table. For example, to find recently ingested records from a specific source:

```sql theme={null}
select *
from building_permits
where source_system = 'socrata'
  and ingested_at > now() - interval '7 days'
order by ingested_at desc
limit 100;
```

To join records across tables by time window:

```sql theme={null}
select bp.record_id, cr.record_id
from building_permits bp
join civic_records cr
  on bp.occurred_at::date = cr.occurred_at::date
  and st_dwithin(bp.geom, cr.geom, 500)
where bp.acl_tier = 'research';
```

## Compliance enforcement

Every change to collectors, edge functions, and migrations is validated against the APRS standard before it can be merged. The compliance pipeline runs three checks:

1. **Shape check** — verifies that every catalog table with data has envelope coverage tracked. If a table has rows but no `record_id` population metrics, the change is blocked.
2. **Runtime compliance** — samples the last 500 rows per table and validates them against nine APRS rules (valid URN format, non-null `source_uri`, valid timestamps, correct `acl_tier`, temporal ordering, and schema version format). Tables below 95% compliance with critical issues block the change.
3. **Static analysis** — flags collector files that write to catalog tables without importing the envelope function. This check is advisory and posts a warning rather than blocking.

These checks run automatically — you do not need to trigger them. If you query Locus data through the API, every record you receive has passed these validations.

## Coverage

The APRS envelope is present on all tables registered in the Locus data catalog. Envelope columns are populated automatically for new records at ingestion time. Historical records are being backfilled progressively — check `modified_at` to confirm a row has been fully normalized.

### Commodity tables

The following commodity and logistics tables carry the APRS envelope with the `aprs.commodity/1.0.0` or `aprs.maritime/1.0.0` profile:

| Table                    | Namespace   | Source                           |
| ------------------------ | ----------- | -------------------------------- |
| `antaq_vessel_calls`     | `maritime`  | ANTAQ (Brazil port authority)    |
| `conab_crop_reports`     | `commodity` | CONAB (Brazil crop surveys)      |
| `antt_road_freight`      | `commodity` | ANTT (Brazil road freight)       |
| `cepea_commodity_prices` | `commodity` | World Bank Pink Sheet            |
| `usace_lock_passages`    | `maritime`  | USDA Grain Transportation Report |

### Transit and vacancy tables

The following tables carry the APRS envelope with the `aprs.urban/1.0.0` profile:

| Table           | Namespace | Source                                                            |
| --------------- | --------- | ----------------------------------------------------------------- |
| `ntd_ridership` | `urban`   | FTA National Transit Database (monthly xlsx from transit.dot.gov) |
| `usps_vacancy`  | `urban`   | HUD USPS Vacancy Data (quarterly, requires HUD registration)      |

Every new row written to these tables includes `record_id`, `source_system`, `source_uri`, `schema_version`, `occurred_at`, `ingested_at`, and `modified_at`. Nightly backfill jobs continue to populate envelope fields on historical rows.