1# The semantic conventions of the .atlas format, as one machine-readable2# source (issue #5 §8, an M7 fast-follow of §10 decision 9).3#4# Three artifacts are generated from this file and from nothing else:5#6# format/semconv/registry_gen.go the Go registry: namespace, version,7# entities, stability tiers, key constants,8# the vocabularies, and the registry map9# analysis/semconv/keys.ts the TypeScript lanes' key constants10# docs/semconv/REGISTRY.md the document a reader learns the11# vocabulary from12#13# go generate ./format/semconv # or: go run ./spec/gen14#15# The value checkers are hand-written in format/semconv/registry.go and are16# referenced here by name (`check:`). A `check:` naming a function the17# generator does not know fails codegen, so a typo cannot become a key that18# checks nothing.19#20# Adding a key: add an entry to `keys`, regenerate, commit all four files. The21# `spec/gen` test compares the committed artifacts against the generator's22# output, so a spec edit without a regeneration is a red gate rather than a23# quiet drift.2425version: 226version_doc: >-27 Version names the vocabulary a bundle was written against. It rides the28 manifest as "conventions" and moves only when an existing key's meaning29 breaks -- additions ride on per-key stability instead.303132 v2 collapsed the v1 entities zone, category, and location into collection33 and feature when the format unified them, and renamed atlas.category.key to34 atlas.collection.key to match.3536namespace: "atlas."37namespace_doc: >-38 Namespace prefixes every key the registry governs. An attribute outside it39 is not this registry's business and passes through untouched.4041# The document's prose. Everything in docs/semconv/REGISTRY.md that is not a42# table row lives here, so the document has exactly one source.43document:44 title: Atlas semantic conventions — registry v{{version}}45 intro: |46 The shared language of the format: attribute keys that carry display and47 geometry meaning from a producer, through composition, into the bundle, and48 out to every reader.4950 **This document is generated from `spec/registry.yaml`.** So is51 `format/semconv`'s registry, and so are the TypeScript lanes' key constants.52 Edit the spec, run `go generate ./format/semconv`, and commit what changes;53 `spec/gen`'s test holds the committed artifacts to the generator's output,54 so the three can never disagree.5556 A bundle declares the vocabulary it was written against in its manifest:57 `"conventions": {{version}}`. The number moves only when an existing key's58 meaning breaks; new keys arrive as `experimental` and earn `stable`. v2 is59 such a break: it collapsed the v1 entities `zone`, `category`, and60 `location` into `collection` and `feature` when the format unified them —61 every kind of thing on a world is a feature, every named set of them a62 collection — and renamed `atlas.category.key` to `atlas.collection.key` to63 match.64 rules: |65 - **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.8283entities_doc: >-84 The entities attributes attach to, from the widest to the narrowest.85entities:86 - name: bundle87 const: EntityBundle88 what: "one `.atlas` file: one volume"89 where: reserved; no key attaches here yet90 - name: world91 const: EntityWorld92 what: one ground within the volume93 where: "`worlds/<slug>.json` → `attrs`"94 - name: collection95 const: EntityCollection96 what: one ordered group of features97 where: "`worlds/<slug>.json` → `collections[].attrs`"98 - name: feature99 const: EntityFeature100 what: one point, path, or area101 where: "inline `features[].attrs`, or `worlds/<slug>.text` → `<id>.a`"102103stabilities_doc: >-104 The stability tiers.105stabilities:106 - name: stable107 const: Stable108 - name: experimental109 const: Experimental110111vocabularies_doc: >-112 The vocabularies the registered keys admit.113114keys_doc: >-115 The registered keys.116117# The registry itself. Order is the order a reader meets these keys, and it is118# the order the generated const blocks carry; the map and every listing sort119# themselves, so nothing downstream depends on it.120#121# Fields:122# key the attribute key as it rides a payload123# const the Go constant; the TypeScript constant is derived from it124# entity bundle | world | collection | feature125# stability stable | experimental126# check the hand-written checker in format/semconv/registry.go127# values for check: enum — the vocabulary, each with its Go constant128# arity for check: numbers — how many comma-separated numbers129# doc the Go doc comment. Omit to join the previous key's comment.130# values_md the document's "Values" cell131# meaning the document's "Meaning" cell132keys:133 - key: atlas.geometry.kind134 const: KeyGeometryKind135 entity: collection136 stability: stable137 check: enum138 values:139 - {const: GeometryPoint, value: point}140 - {const: GeometryPath, value: path}141 - {const: GeometryArea, value: area}142 doc: >-143 KeyGeometryKind says what shape of thing a collection holds: points,144 paths, or areas. Every collection declares one kind and every feature in145 it is that kind; readers pick their rendering and UX by this key instead146 of sniffing geometry types at draw time.147 values_md: '`point` \| `path` \| `area`'148 meaning: >-149 What shape of thing the collection holds. Declared once per collection;150 every feature in it is that kind, and readers pick rendering and UX by151 this key instead of sniffing geometry types.152153 - key: atlas.label.policy154 const: KeyLabelPolicy155 entity: collection156 stability: experimental157 check: enum158 values:159 - {const: LabelAlways, value: always}160 - {const: LabelQuiet, value: quiet}161 doc: >-162 KeyLabelPolicy says whether an area collection's features wear their163 names on the map always, or quietly -- only on highlight, selection, or164 an explicit reveal. Area collections only: absent means always for165 areas, and paths are always quiet.166 values_md: '`always` \| `quiet`'167 meaning: >-168 Whether an area collection's features wear their names on the map always,169 or quietly — only on highlight, selection, or an explicit reveal. Area170 collections only; absent means `always` for areas, and paths are always171 quiet.172173 - key: atlas.render.as174 const: KeyRenderAs175 entity: collection176 stability: stable177 check: enum178 values:179 - {const: RenderAsPin, value: pin}180 - {const: RenderAsText, value: text}181 doc: >-182 KeyRenderAs says how a point collection's features are drawn: as markers183 or as floating text labels.184 values_md: '`pin` \| `text`'185 meaning: >-186 How a point collection's features draw: markers, or floating text labels.187 Absent means `pin`; no payload carries a display-type field, and only188 ingestion still reads one to speak this key for old captures.189190 - key: atlas.icon.std191 const: KeyIconStd192 entity: collection193 stability: stable194 check: setName195 doc: >-196 KeyIconStd names a standard-library icon for a collection that has no197 artwork of its own, as set/name, e.g. "maki/mountain". A producer198 resolves it to embedded bytes; a reader only ever sees the resolved199 asset.200 values_md: '`set/name`, e.g. `maki/mountain`'201 meaning: >-202 Standard-library icon for a collection without artwork. Resolved to203 embedded bytes at build time; a reader only sees the resolved asset.204205 - key: atlas.icon.kind206 const: KeyIconKind207 entity: collection208 stability: stable209 check: enum210 values:211 - {const: IconKindGlyph, value: glyph}212 - {const: IconKindPicture, value: picture}213 doc: >-214 KeyIconKind says whether a collection's icon asset is a monochrome glyph215 the reader tints, or a picture drawn as-is.216 values_md: '`glyph` \| `picture`'217 meaning: >-218 Whether the icon asset is a monochrome glyph the reader tints, or a219 picture drawn as-is. Names what a file suffix used to imply.220221 - key: atlas.icon.outset222 const: KeyIconOutset223 entity: world224 stability: stable225 check: enum226 values:227 - {const: OutsetLight, value: light}228 - {const: OutsetDark, value: dark}229 doc: >-230 KeyIconOutset says which rim a world's markers wear so they stay legible231 against its art: the light rim of a dark raster or the dark rim of a232 light one.233 values_md: '`light` \| `dark`'234 meaning: >-235 The rim a world's markers wear to stay legible against its art.236237 - key: atlas.geometry.surface238 const: KeyGeometrySurface239 entity: world240 stability: stable241 check: enum242 values:243 - {const: SurfacePlane, value: plane}244 - {const: SurfaceSphere, value: sphere}245 doc: >-246 KeyGeometrySurface declares what a world's raster is a picture of: a247 plane or a sphere. A world that says nothing is a plane.248 values_md: '`plane` \| `sphere`'249 meaning: >-250 What the raster pictures. Absent means `plane`.251252 - key: atlas.geometry.projection253 const: KeyGeometryProjection254 entity: world255 stability: stable256 check: enum257 values:258 - {const: ProjectionEquirect, value: equirect}259 doc: >-260 KeyGeometryProjection says how a spherical surface was flattened into261 the raster. Equirectangular is the only vocabulary so far.262 values_md: '`equirect`'263 meaning: >-264 How a sphere was flattened. Required when surface is `sphere`.265266 - key: atlas.geometry.equirect.px267 const: KeyGeometryEquirectPx268 entity: world269 stability: stable270 check: numbers271 arity: 4272 doc: >-273 KeyGeometryEquirectPx is the raster window the projection fills, in274 world pixels, as "x,y,w,h".275 values_md: '`x,y,w,h` (world px)'276 meaning: >-277 The raster window the projection fills.278279 - key: atlas.geometry.equirect.deg280 const: KeyGeometryEquirectDeg281 entity: world282 stability: stable283 check: numbers284 arity: 4285 doc: >-286 KeyGeometryEquirectDeg is the ground that window pictures, in degrees,287 as "west,north,east,south".288 values_md: '`west,north,east,south` (degrees)'289 meaning: >-290 The ground that window pictures.291292 - key: atlas.geometry.mercator.px293 const: KeyGeometryMercatorPx294 entity: world295 stability: experimental296 check: numbers297 arity: 4298 doc: >-299 KeyGeometryMercatorPx is the raster window a Web-Mercator cut fills, in300 world pixels, as "x,y,w,h". Where equirect declares y linear in degrees,301 mercator declares y linear in the projected latitude -- asinh(tan302 latitude) -- which is the flattening a real-world tile window actually303 is.304 values_md: '`x,y,w,h` (world px)'305 meaning: >-306 The raster window a Web-Mercator cut fills. Where `equirect` declares y307 linear in degrees, `mercator` declares y linear in projected latitude —308 `asinh(tan lat)` — the flattening a real-world tile window actually is.309310 - key: atlas.geometry.mercator.deg311 const: KeyGeometryMercatorDeg312 entity: world313 stability: experimental314 check: numbers315 arity: 4316 doc: >-317 KeyGeometryMercatorDeg is the ground a Mercator window pictures, in318 degrees at the window's edges, as "west,north,east,south".319 values_md: '`west,north,east,south` (degrees)'320 meaning: >-321 The ground the Mercator window pictures, in degrees at its edges.322323 - key: atlas.geometry.body324 const: KeyGeometryBody325 entity: world326 stability: experimental327 check: slug328 doc: >-329 KeyGeometryBody names the body pictured, e.g. "mars".330 values_md: 'slug, e.g. `mars`'331 meaning: >-332 The body pictured.333334 - key: atlas.geometry.radius_km335 const: KeyGeometryRadiusKM336 entity: world337 stability: experimental338 check: decimal339 doc: >-340 KeyGeometryRadiusKM is the body's mean radius in kilometers, as a341 decimal string.342 values_md: 'decimal string'343 meaning: >-344 The body's mean radius.345346 - key: atlas.geo.lat347 const: KeyGeoLat348 entity: feature349 stability: experimental350 check: decimal351 doc: >-352 KeyGeoLat and KeyGeoLon carry a feature's true planetary coordinates as353 the source published them: planetocentric degrees, east-positive354 longitude. They are provenance and card material; rendering derives355 positions from the world-level mapping instead.356 values_md: 'decimal degrees'357 meaning: >-358 True planetary latitude as published (planetocentric). Provenance and359 card material; rendering derives from the world-level mapping.360361 # No doc: this key joins the comment above, the way the two read together.362 - key: atlas.geo.lon363 const: KeyGeoLon364 entity: feature365 stability: experimental366 check: decimal367 values_md: 'decimal degrees'368 meaning: >-369 True planetary longitude as published (east-positive).370371 - key: atlas.hydro.huc12372 const: KeyHydroHUC12373 entity: feature374 stability: experimental375 check: huc12376 doc: >-377 KeyHydroHUC12 names the USGS twelve-digit hydrologic unit -- the378 subwatershed -- a feature's ground lies wholly within. A feature379 spanning subwatersheds carries no key rather than a misleading one.380 values_md: 'twelve digits'381 meaning: >-382 The USGS twelve-digit hydrologic unit — the subwatershed — the feature's383 ground lies wholly within, from the national Watershed Boundary Dataset.384 A feature spanning subwatersheds carries no key rather than a misleading385 one.386387 - key: atlas.stroke.width_px388 const: KeyStrokeWidthPx389 entity: collection390 stability: experimental391 check: positiveDecimal392 doc: >-393 KeyStrokeWidthPx is the ground width of a path collection's features, in394 world pixels: a trail is a line and a weight, and declaring the weight395 lets a reader draw the path as one continuous stroke instead of an area396 faked around it.397 values_md: 'positive decimal (world px)'398 meaning: >-399 The ground width of a path collection's features: a trail is a line and a400 weight, and the weight lets a reader draw the path as one continuous401 stroke.402403 - key: atlas.collection.key404 const: KeyCollectionKey405 entity: collection406 stability: experimental407 check: slug408 doc: >-409 KeyCollectionKey is a collection's merge identity: the slug collections410 from different sources meet under when they mean the same concept.411 Absent, the icon key stands in.412 values_md: 'slug'413 meaning: >-414 A collection's merge identity across sources. Absent, the icon key stands415 in.416417# Names the vocabulary uses that never ride a payload. They are deliberately418# unregistered: Validate refuses them on every entity.419policy_keys_doc: >-420 Policy names (never written to a payload)421policy_keys:422 - key: atlas.note.text423 const: KeyNoteText424 doc: >-425 KeyNoteText never appears in a payload. It is the name a merge policy426 table and its ledger use for a feature's description, so "which427 description wins" is decided and recorded in the same vocabulary as428 everything else. It is deliberately unregistered: [Validate] refuses it429 on any entity.430 meaning: >-431 A feature's description, as a merge policy table and its ledger name it,432 so "which description wins" is decided and recorded in the same433 vocabulary as everything else. It is deliberately unregistered:434 `Validate` refuses it on any entity.