1<!-- Code generated by spec/gen from spec/registry.yaml. DO NOT EDIT. -->23# Atlas semantic conventions — registry v245The shared language of the format: attribute keys that carry display and6geometry meaning from a producer, through composition, into the bundle, and7out to every reader.89**This document is generated from `spec/registry.yaml`.** So is10`format/semconv`'s registry, and so are the TypeScript lanes' key constants.11Edit the spec, run `go generate ./format/semconv`, and commit what changes;12`spec/gen`'s test holds the committed artifacts to the generator's output,13so the three can never disagree.1415A bundle declares the vocabulary it was written against in its manifest:16`"conventions": 2`. The number moves only when an existing key's17meaning breaks; new keys arrive as `experimental` and earn `stable`. v2 is18such a break: it collapsed the v1 entities `zone`, `category`, and19`location` into `collection` and `feature` when the format unified them —20every kind of thing on a world is a feature, every named set of them a21collection — and renamed `atlas.category.key` to `atlas.collection.key` to22match.2324## Entities2526| Entity | What it is | Where its attributes ride |27|---|---|---|28| `bundle` | one `.atlas` file: one volume | reserved; no key attaches here yet |29| `world` | one ground within the volume | `worlds/<slug>.json` → `attrs` |30| `collection` | one ordered group of features | `worlds/<slug>.json` → `collections[].attrs` |31| `feature` | one point, path, or area | inline `features[].attrs`, or `worlds/<slug>.text` → `<id>.a` |3233## Attributes3435| Key | Entity | Values | Stability | Meaning |36|---|---|---|---|---|37| `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. |38| `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, and paths are always quiet. |39| `atlas.render.as` | collection | `pin` \| `text` | stable | How a point collection's features draw: markers, or floating text labels. Absent means `pin`; no payload carries a display-type field, and only ingestion still reads one to speak this key for old captures. |40| `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; a reader only sees the resolved asset. |41| `atlas.icon.kind` | collection | `glyph` \| `picture` | stable | Whether the icon asset is a monochrome glyph the reader tints, or a picture drawn as-is. Names what a file suffix used to imply. |42| `atlas.icon.outset` | world | `light` \| `dark` | stable | The rim a world's markers wear to stay legible against its art. |43| `atlas.geometry.surface` | world | `plane` \| `sphere` | stable | What the raster pictures. Absent means `plane`. |44| `atlas.geometry.projection` | world | `equirect` | stable | How a sphere was flattened. Required when surface is `sphere`. |45| `atlas.geometry.equirect.px` | world | `x,y,w,h` (world px) | stable | The raster window the projection fills. |46| `atlas.geometry.equirect.deg` | world | `west,north,east,south` (degrees) | stable | The ground that window pictures. |47| `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. |48| `atlas.geometry.mercator.deg` | world | `west,north,east,south` (degrees) | experimental | The ground the Mercator window pictures, in degrees at its edges. |49| `atlas.geometry.body` | world | slug, e.g. `mars` | experimental | The body pictured. |50| `atlas.geometry.radius_km` | world | decimal string | experimental | The body's mean radius. |51| `atlas.geo.lat` | feature | decimal degrees | experimental | True planetary latitude as published (planetocentric). Provenance and card material; rendering derives from the world-level mapping. |52| `atlas.geo.lon` | feature | decimal degrees | experimental | True planetary longitude as published (east-positive). |53| `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. |54| `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. |55| `atlas.collection.key` | collection | slug | experimental | A collection's merge identity across sources. Absent, the icon key stands in. |5657## Policy names (never written to a payload)5859| Name | Meaning |60|---|---|61| `atlas.note.text` | A feature's description, as a merge policy table and its ledger name it, so "which description wins" is decided and recorded in the same vocabulary as everything else. It is deliberately unregistered: `Validate` refuses it on any entity. |6263## Rules6465- **Producer-side (strict):** any `atlas.*` key not in this registry, attached66 to the wrong entity, or carrying a value outside its vocabulary **fails the67 build**. `semconv.Validate` and `semconv.Check` are that gate.68- **Reader-side (lenient):** unknown keys are ignored. A bundle is never69 refused over conventions. `semconv.EntityOf` reporting `false` is a cue to70 skip an attribute, not to fail.71- Keys outside the `atlas.` namespace are not this registry's business and72 pass through untouched.73- `sphere` requires `projection` and both `equirect.*` mappings; the declared74 mapping must invert — a packed position run backward through it recovers the75 source's published coordinates.76- `atlas.icon.std`, once declared, must be resolved to a real icon asset by77 the time the bundle is written.78- A collection's `atlas.geometry.kind`, when declared, must agree with the79 `kind` field on the wire.80- `atlas.label.policy` attaches only to area collections; a declaration on any81 other kind fails validation.