1# Atlas semantic conventions — registry v223The shared language of the pipeline: attribute keys that carry display and4geometry meaning from a source's translator, through composition, into the5bundle, and out to every reader. Producers are held to this vocabulary at6build time; readers ignore what they do not know and never refuse a bundle7over it. `semconv.go` is the executable twin of this document, and a test8holds the two to the same list.910A bundle declares the vocabulary it was written against in its manifest:11`"conventions": 2`. The number moves only when an existing key's meaning12breaks; new keys arrive as `experimental` and earn `stable`. v2 is such a13break: it collapsed the v1 entities `zone`, `category`, and `location` into14`collection` and `feature` when the format unified them — every kind of15thing on a map is a feature, every named set of them a collection — and16renamed `atlas.category.key` to `atlas.collection.key` to match.1718## Attributes1920| Key | Entity | Values | Stability | Meaning |21|---|---|---|---|---|22| `atlas.geometry.kind` | collection | `point` \| `path` \| `area` | stable | What shape of thing the collection holds. Declared once per collection; every feature in it is that kind, and readers pick rendering and UX by this key instead of sniffing geometry types. |23| `atlas.label.policy` | collection | `always` \| `quiet` | experimental | Whether an area collection's features wear their names on the map always, or quietly — only on highlight, selection, or an explicit reveal. Area collections only; absent means `always` for areas (today's look), and paths are always quiet. |24| `atlas.render.as` | collection | `pin` \| `text` | stable | How a point collection's features draw: markers, or floating text labels. Absent means `pin`; the legacy `displayType` field no longer rides the wire, and only ingestion still reads it to speak this key for old captures. |25| `atlas.icon.std` | collection | `set/name`, e.g. `maki/mountain` | stable | Standard-library icon for a collection without artwork. Resolved to embedded bytes at build time; the app only sees the resolved asset. |26| `atlas.icon.kind` | collection | `glyph` \| `picture` | stable | Whether the icon asset is a monochrome glyph the viewer tints, or a picture drawn as-is. Names what the `.png` suffix used to imply. |27| `atlas.icon.outset` | world | `light` \| `dark` | stable | The rim a map's markers wear to stay legible against its art. |28| `atlas.geometry.surface` | world | `plane` \| `sphere` | stable | What the raster pictures. Absent means `plane` — every map before the planets. |29| `atlas.geometry.projection` | world | `equirect` | stable | How a sphere was flattened. Required when surface is `sphere`. |30| `atlas.geometry.equirect.px` | world | `x,y,w,h` (world px) | stable | The raster window the projection fills. |31| `atlas.geometry.equirect.deg` | world | `west,north,east,south` (degrees) | stable | The ground that window pictures. |32| `atlas.geometry.mercator.px` | world | `x,y,w,h` (world px) | experimental | The raster window a Web-Mercator cut fills. Where `equirect` declares y linear in degrees, `mercator` declares y linear in projected latitude — `asinh(tan lat)` — the flattening a real-world tile window actually is. |33| `atlas.geometry.mercator.deg` | world | `west,north,east,south` (degrees) | experimental | The ground the Mercator window pictures, in degrees at its edges. |34| `atlas.geometry.body` | world | slug, e.g. `mars` | experimental | The body pictured. |35| `atlas.geometry.radius_km` | world | decimal string | experimental | The body's mean radius. |36| `atlas.geo.lat` | feature | decimal degrees | experimental | True planetary latitude as published (planetocentric). Provenance and card material; rendering derives from the map-level mapping. |37| `atlas.geo.lon` | feature | decimal degrees | experimental | True planetary longitude as published (east-positive). |38| `atlas.hydro.huc12` | feature | twelve digits | experimental | The USGS twelve-digit hydrologic unit — the subwatershed — the feature's ground lies wholly within, from the national Watershed Boundary Dataset. A feature spanning subwatersheds carries no key rather than a misleading one. |39| `atlas.stroke.width_px` | collection | positive decimal (world px) | experimental | The ground width of a path collection's features: a trail is a line and a weight, and the weight lets a reader draw the path as one continuous stroke. |40| `atlas.collection.key` | collection | slug | experimental | A collection's merge identity across sources. Absent, the icon key stands in. |4142## Policy names (never written to a payload)4344| Name | Meaning |45|---|---|46| `atlas.note.text` | A pin's description, as the merge policy table and ledger name it, so "which description wins" is decided and recorded in the same vocabulary as everything else. |4748## Rules4950- Producer-side: any `atlas.*` key not in this registry, attached to the51 wrong entity, or carrying a value outside its vocabulary **fails the52 build**.53- Reader-side: unknown keys are ignored. Bundles are never refused over54 conventions.55- `sphere` requires `projection` and both `equirect.*` mappings; the56 declared mapping must invert — a pin's packed position run backward57 through it recovers the source's published coordinates.58- `atlas.icon.std`, once declared, must be resolved to a real icon asset by59 the time the bundle is written.