Module wire 

The versioned wire format of a GeometryGraph (ADR 0085).

One serde data model, two encodings: JSON (RFC 8259) and CBOR (RFC 8949). Every payload is an envelope naming the format and its version around the graph:

{
  "format": "axiolid-geometry-graph",
  "version": "1.0",
  "graph": { "nodes": [{ "Primitive": { "Sphere": { "radius": 1.0 } } }], "roots": [0] }
}

graph.nodes lists the nodes in insertion order, which is topological, and a node reference is the zero-based index of an earlier node. Enums are externally tagged by their variant names, fields by their names, a point or vector is an array of its coordinates and a transform the columns of its linear part then its translation. Real numbers round-trip bit-exactly and are finite.

Versions

Adding a node kind, an enum variant or an optional field is a minor version; renaming or removing anything, or changing its type, meaning or units, is a major version. A reader reads its own major up to its own minor, so every older minor of FORMAT_VERSION stays readable.

A writer labels each payload with the lowest version that represents it (#297), not with FORMAT_VERSION: a graph that uses nothing a minor added is written exactly as that minor’s predecessor wrote it, so an older reader keeps reading every graph that does not use newer features. A graph with no seam-snapping window is a 1.0 payload, one whose run stations carry no seam side or window a 1.0 or 1.1 payload, one with no run station at its basis’s start or end at most a 1.2 payload, one with no half-space bounded along its placement’s z at most a 1.3 payload, and one with no ruled surface at most a 1.4 payload.

Version	Added
1.0	The format (#267).
1.1	OrientedCurveStation.seam_window (#294), a real omitted at its default +0.0; absent, as in every 1.0 payload, it reads as 0, which is what a 1.0 station meant.
1.2	Seam sides and windows on run stations (#301): SectionAtStation.seam and .seam_window, omitted at Outgoing and +0.0 and read so when absent; the variant CurveRelation::OffsetsAtStations, whose RunStations carry the same two fields.
1.3	Run stations at their basis’s ends (#303): RunStation.basis_end, "Start" or "End", omitted when absent (a stated distance) and read so.
1.4	A half-space bounded along its placement’s z (#321): the variant SolidOperation::BoundedHalfSpaceAlongZ, fields as BoundedHalfSpace’s.
1.5	A surface ruled between two sides (#402): the variant SurfaceRelation::Ruled with its RuledSides, a curve node over an interval or an apex point.

Refusals

A reader never returns part of a payload. It refuses, by a named WireError: a missing or other format name, a missing version, a version it does not support (another major, or a newer minor, checked before the graph is read), a node kind or variant it does not know (WireError::UnknownKind, never skipped), a field it does not know, a non-finite number, anything that does not decode, and a graph that the builder’s validation refuses: a decoded graph is rebuilt node by node through GeometryGraphBuilder::push, so a payload cannot build a graph the API could not.

A writer refuses a graph holding a non-finite number, which JSON cannot carry, rather than write a payload that would read back differently.

Integers where reals are expected

Both readers accept an integer where a real is expected when it is exactly a double, as host encoders write whole-number doubles as integers: a JSON integer literal, or a CBOR integer item i with i as f64 as i128 == i (every |i| <= 2^53, and larger ones that are doubles). Integer zero has no sign, so it reads as +0.0; a writer keeps -0.0 a float. A CBOR integer that is not exactly a double is refused as WireError::Malformed, naming its path, wherever it stands: no index or count of the format reaches 2^53.

Structs

FormatVersion

A MAJOR.MINOR wire format version.

Enums

WireError

Why a graph could not be written or a payload could not be read.

Constants

FORMAT_NAME

The format name every payload carries in its format entry.

FORMAT_VERSION

The newest format version this crate reads and writes. A payload is labelled with the lowest version that represents it, which is this one only when the graph uses what this version added (see the module documentation).

Functions

from_cbor

Read a graph from a CBOR payload: one data item, nothing after it.

from_json

Read a graph from a JSON payload.

to_cbor

Write graph as a CBOR payload.

to_json

Write graph as a JSON payload.