1# The `.atlas` native schema bundle23**Status: normative.** Atlas now has one accepted physical format. The retired4document-shaped v3 format is preserved for historical reference in5[`format-v3.md`](format-v3.md); current readers do not install it.67## Semantic shape89```text10Volume11 ├── Worlds12 │ ├── CoordinateSpace13 │ ├── FeatureSets14 │ │ └── Features15 │ │ ├── Geometry16 │ │ ├── TypedProperties17 │ │ ├── Relationships18 │ │ └── Provenance19 │ ├── RasterPyramids20 │ └── Presentation21 │ ├── Layers22 │ ├── Styles23 │ └── Legend24 └── Assets25```2627Semantics and presentation are separate. Feature membership, geometry,28relationships, typed claims, and evidence remain true when a presentation is29replaced. Layers and styles refer to semantic identities; they do not own or30duplicate features.3132## Physical shape3334A `.atlas` is a deterministic ZIP container. ZIP is only framing: the data35model is the embedded schema plus typed column blocks, not a collection of JSON36documents.3738```text39atlas.json bootstrap + release metadata40schema/<sha256>.json canonical file schema41data/volumes.pack typed column blocks42data/worlds.pack43data/coordinate-spaces.pack44data/feature-sets.pack45data/property-definitions.pack46data/features.pack47data/relationships.pack48data/provenance.pack49data/raster-pyramids.pack50data/raster-formats.pack51data/raster-coverage.pack52data/presentations.pack53data/styles.pack54data/layers.pack55data/legend.pack56data/assets.pack57assets/<sha256> content-addressed supporting bytes58tiles/<pyramid>/<z>/<x>/<y>.<ext> opaque raster bytes59```6061Typed blocks and opaque blobs are stored without ZIP compression so they can62be read independently. The bootstrap and schema may be deflated. Entry names63are relative, unique, and cannot contain empty, `.` or `..` segments.6465## Bootstrap and release identity6667`atlas.json` is deliberately small and schema-independent:6869```json70{71 "format": "atlas-schema-bundle",72 "framing": 1,73 "volume": "earth",74 "release": {75 "title": "Earth",76 "createdAt": "2026-08-03T16:21:07Z",77 "revision": 10,78 "stamp": "<64 lowercase hex characters>",79 "worlds": 180 },81 "schema": { "name": "schema/<hash>.json", "hash": "<sha256>" },82 "tables": [],83 "blobs": []84}85```8687- `createdAt` is newest source capture time, never build time.88- `revision` orders different producer policies over the same capture.89- `stamp` is SHA-256 over the canonical bootstrap with an empty stamp, after90 all schema, table, and blob hashes and lengths have been filled.91- file names are `<volume>-<YYYYMMDD>-<stamp12>.atlas`.92- registry winners order by `createdAt`, `revision`, `stamp`, then locator.9394The directory is the registry. `index.json`, when present, is a derived95convenience listing with no authority.9697## Typed block framing9899Every `.pack` begins with `ATLASPK\0`, framing version 1, row and column counts,100the canonical schema hash, the root type identity, and a fixed-width column101directory. Each directory entry declares:102103- stable 128-bit field identity;104- logical and physical kind;105- optionality;106- presence bitmap range;107- payload range;108- CRC-32 over presence and payload.109110Fixed-width values are directly addressable. Strings and bytes use a row111offset table followed by content. Consumers verify bounds and checksums before112exposing column views.113114## Compatibility without a committee115116Identity, not field position or spelling, governs meaning.117118| Change | Result |119|---|---|120| Add a type with a new ID | compatible |121| Add an optional field with a new ID | compatible |122| Rename a type or field while keeping its ID and kind | compatible |123| Independently add different IDs on two branches | union is compatible |124| Reuse an ID with a different kind | refused |125| Remove or reinterpret a required field | new identity required |126| Change container framing | old reader refuses |127128A reader merges its application schema with the file schema. Unknown types and129columns remain addressable and round-trippable; a presentation may ignore them.130This gives backward, forward, and sideward compatibility without a central131sequence of schema versions.132133## Install and validation134135One command serves picker, desktop open, drag/drop, and programmatic install:136137```text138source → open framing → merge schema → verify every table/blob139 → restore and validate semantic Volume140 → stage beside library → atomic rename → reopen + verify141 → rescan + deterministic fold → announce changed volume142```143144A malformed file never lands under `.atlas`. A legacy v3 file, ordinary ZIP,145unknown framing, inconsistent schema, changed field kind, corrupt column, bad146hash, missing reference, or invalid semantic graph is refused.147148## Producer requirements149150The producer constructs the semantic graph directly and calls the native151compiler. It must not create v3 JSON payloads as an intermediate format.152Raster files may be streamed from disk; their hashes and lengths still153participate in the release stamp. A completed file is reopened and fully154validated before it is renamed into the registry.155156## Reader requirements157158A conforming reader:1591601. validates bootstrap identity, framing, release metadata, and release stamp;1612. verifies and canonicalizes the embedded schema;1623. unions file and application schemas by stable identity;1634. verifies table roots, column kinds, required fields, bounds, and CRCs;1645. verifies opaque blob length and SHA-256 before use;1656. restores references by semantic ID and validates the complete graph;1667. treats Presentation as a view over semantic data, not as the data itself.