JSON Schemas

One component library is shared by every OpenAPI document and by the generated client. Every example in it is validated in CI.

Shared Atomicals documentation schema library, version 1.0.0. Download: common.schema.json. 23 definitions, every example validated in CI.

Shared schema definitions

Definition	Type	What it is	Example
AtomicalId Atomical ID	string, pattern constrained	Durable identity of an Atomical, assigned at mint and never reassigned.	4d0b1f1c9c53a5b1e0b1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061i0
Location Outpoint	string, pattern constrained	Current custody position. Changes on every move, so it is never a database key.	4d0b1f1c9c53a5b1e0b1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061:0
TransactionId	string, pattern constrained	No description recorded.	none
BlockHeight	integer	No description recorded.	none
AtomicAmount Atomic amount	string, pattern constrained	A satoshi or protocol quantity as a decimal string. JSON numbers are rejected, so no precision is lost in transit.	546
Ticker ARC-20 ticker	string	A globally allocated ARC-20 name. Always displayed alongside the resolved Atomical ID, because a ticker is not identity.	none
Network	string, enumerated	No description recorded.	none
ProtocolId	string, enumerated	Marketplace protocol lane. Every route, cursor, and idempotency scope is bound to exactly one.	none
AssetType	string, enumerated	No description recorded.	none
GenerationId Generation identifier	string	Identifies the immutable snapshot an answer was served from. Store it with any cached result.	none
Cursor Opaque signed cursor	string	Refers to a position inside one generation and carries the page sizes it was created with. Never parse, construct, or modify one.	none
RequestId	string	Per-request identifier returned with every response. Log it on success as well as failure.	none
IsoDateTime	string	No description recorded.	none
ReadinessState	string, enumerated	No description recorded.	none
Coverage	string, enumerated	No description recorded.	none
Error Error envelope	object	No description recorded.	none
Freshness Freshness metadata	object	Returned with read answers so a caller can decide whether to act on them.	none
MediaDescriptor Media descriptor	object	Describes a stored file. Treat the declared content type as untrusted and sniff the bytes.	none
AssetProjection Projected asset	object	The materialised read model for one projected Atomical.	none
HistoryEntry	object	No description recorded.	none
HolderRow	object	No description recorded.	none
CursorPage Cursor page	object	No description recorded.	none
SourceManifestEntry Source provenance record	object	No description recorded.	none

The rules the schemas encode

Atomic amounts are strings. AtomicAmount is a decimal string with a pattern, not a number. That is deliberate: a satoshi quantity above the safe integer range would lose precision as a JSON number, and a client that parses one into a float produces silently wrong arithmetic.

Atomical IDs have a shape. AtomicalId is <txid>i<index>, matched by pattern. A location is <txid>:<vout>. They are different things and the schemas keep them apart.

Names have three forms. AssetProjection carries name as the exact minted bytes and normalizedName for comparison. Neither is a display form. See Unicode and IDNA.

Freshness travels with answers. Freshness carries the generation identifier, indexed height, stale flag, mixed tip flag, source revision, and network. A caller that stores an answer without these cannot explain a later disagreement.

Errors have a code. Branch on error.code, never on error.message. Messages are for humans and can change without a version bump.

Media descriptors describe, they do not vouch

MediaDescriptor carries a declared content type and a digest. The digest proves the bytes. The content type is attacker controlled. Sniff the bytes.

Versioning

Schemas carry a version. When it changes:

1. Validate your stored records against the new schema.
2. Fix what fails before switching.
3. Keep the old schema available until nothing reads the old records.

See migration.

Adding a schema

Contributor instructions are in adding an API. In short: add the definition with at least one example, reference it from the documents that use it, and let CI validate the example.