Provisional. The schema and the convention may change during the current development phase, and a file valid under one version is not guaranteed to be interpreted the same way by a later one. Changes will be listed in the version history below and communicated where practical. See the Terms of Service, Section 7.
Superlattix model format
The XML schema and serialisation convention behind Superlattix model files – for anyone who reads, writes or scripts them outside the editor.
Schema 2.1 · Convention 2.1.9 · Download the XSD (v2.1.xsd)
1. Purpose and scope
A Superlattix model is stored as an XML file: the format the editor uses to save models and to open them from local files, and the format of XML export.
The format has two parts, which serve different purposes and carry different stability guarantees.
The schema (XSD) defines the container: the elements and attributes a model file may contain, their order, and their primitive types. It is published at a stable URL and versioned publicly.
The serialisation convention defines the meaning: for each element variety, which fields are significant, how their values are interpreted, and what constraints apply to them. The schema deliberately constrains little – a single generic element type carries every variety – so most of what makes a file interpretable lives in the convention.
A file can be valid against the schema and still be misread if it does not follow the convention. Both are required, and a file is conformant only when it satisfies both.
This page specifies the general-purpose convention used by the editor itself. Conventions optimised for specific downstream workflows may be specified separately against the same schema.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119. Field names refer to the XML: pos is the <pos> child of an element, size/@l is the l attribute of its <size> child, @specifier is the element's specifier attribute.
2. Schema and convention
The schema fixes the shape of a file: one <model>, its <metadata>, then any number of <element>s followed by any number of <body>s, each carrying the same generic fields – pos, start, end, dir, size, and the attributes variety, uid and specifier. The convention gives those fields their meaning for each variety, and adds the rules the schema cannot express.
Every field of every variety is one of three kinds:
| Kind | Writers | Readers |
|---|---|---|
| Significant | MUST write a value meeting the variety's constraints | MUST interpret it as specified |
| Unused | MUST write zero (empty for uid) | MUST ignore its value |
| Reserved | MUST write zero | MUST treat the element as unreadable (Section 5.5) if the value is non-zero |
Reserved fields are kept free for a meaning a later convention may give them; rejecting non-zero values now guarantees that no accepted file can be misread when that happens.
A file is a snapshot of a model's state. The format records no history and no identity across saves.
3. Versioning
The <format> element carries three version components:
| Component | Meaning |
|---|---|
version_major, version_minor | The schema version. MUST match the XSD named in schema/@href: 2.1 means v2.1.xsd. |
version_patch | The convention's serial number within that schema version: 2.1.9 reads as "convention 9 of schema 2.1". |
A higher convention number means a later convention, not a better or more compatible one. When the schema version changes, the convention serial restarts. A published schema is immutable: any change to the schema produces a new major.minor and a new XSD at a new URL.
A reader MUST reject a file whose convention it does not support, and a file whose schema/@href does not name the XSD for its major.minor. The current editor supports convention 2.1.9.
The version components are typed as tokens, not numbers, so that later conventions may be named rather than numbered.
4. Document structure
<model>
<metadata>
<format id="superlattix" version_major="2" version_minor="1" version_patch="9"/>
<schema href="https://superlattix.com/schema/v2.1.xsd"/>
<created at="2026-10-04T12:00:00Z" tool="superlattix-editor" tool_version="0.6.24"/>
</metadata>
<element variety="…" uid="…" specifier="…">…</element>
…
<body variety="…" uid="…" specifier="…">…</body>
…
</model>
<format> – id MUST be superlattix. All four attributes are required.
<schema> – href names the XSD the file follows.
<created> – at is the time the file was written (UTC, RFC 3339, seconds precision); tool and tool_version identify the writer.
All <element>s precede all <body>s. A model MAY contain no elements and no bodies. The order of elements carries no meaning, and neither does the order of bodies: writers MAY emit them in any order, and readers MUST NOT attach meaning to it. Within an element or body, the children appear in the order pos, start, end, dir, size; a body's genesis children precede them.
5. Common rules
5.1 Coordinates and units
Coordinates are in model units in a right-handed coordinate system with axes X, Y and Z. Model units are abstract: Superlattix models are schematic, not dimensionally accurate. All values are 32-bit floats. Every coordinate and size MUST be finite. -0 is equivalent to 0; writers SHOULD NOT write -0, and readers MUST treat it as 0.
5.2 Vectors, directions and tolerances
A field described as a unit vector need not be exactly unit length in the file: readers normalise it. It MUST be non-zero and finite. A field described as an axis direction (for example "+X, +Y or +Z") is accepted when it lies within DIR_TOL of one of those directions after normalisation, and is then treated as exactly that direction.
| Constant | Value | Meaning |
|---|---|---|
DIR_TOL | 1 × 10⁻⁴ | Tolerance for unit directions, perpendicularity and axis alignment |
PLANE_TOLERANCE | 0.001 | Tolerance, in model units, for a point lying in a plane |
MIN_EXTENT | 0.1 | Smallest extent, length or radius of any element, in model units |
5.3 Guide planes
Most elements are drawn on a guide plane: an axis plane whose normal is +X, +Y or +Z. Where a variety records its guide plane, it does so in dir. For elements drawn from start to end on a guide plane, the plane passes through start; end MUST lie in it within PLANE_TOLERANCE, and writers write end projected exactly into it.
5.4 Minimum size
Every extent, length and radius MUST be at least MIN_EXTENT. An element below this size is degenerate: it would be invisible, and the editor never creates one.
5.5 Elements that cannot be read or written
An element that violates the convention – degenerate, or invalid in any other way – is unreadable. An unreadable element never prevents the rest of a model from being read or written:
- A reader omits each unreadable element, and every body that depends on it, and loads the rest of the model.
- A writer omits any element that fails validation, and every body that depends on it, and writes the rest.
Only file-level problems fail a load: XML that cannot be parsed, a file that is not a Superlattix model, an unsupported schema or convention version, or a schema/@href that does not match the version.
5.6 Identifiers
@uid identifies an element that a body can reference. In this convention, every rect carries a uid and no other element does; other varieties and all bodies write an empty uid. A uid is a decimal unsigned 64-bit integer, unique within a file, and MUST NOT be 18446744073709551615. uids are opaque – neither dense nor ordered – and readers MUST NOT infer anything from their values. If two elements share a uid, the reader loads the first and omits the others as unreadable.
5.7 The specifier
@specifier is an unsigned byte (0–255) whose meaning depends on the variety. Varieties that do not use it write 0.
5.8 The start direction of round shapes
The helix and the circle start at a fixed angle that depends only on their axis n: the canonical start direction below, rotated right-handedly about n by HELIX_PHASE (currently 0). It is not stored in the file.
Axis n | Canonical direction |
|---|---|
+X | +Y |
+Y | +Z |
+Z | +X |
6. Element catalogue
Varieties are grouped for navigation only; a shared group does not imply a shared convention. Unless stated otherwise, every field not listed for a variety is unused.
| Group | Varieties |
|---|---|
| Lines | segment, arrow, belgian_arrow, british_arrow, wave_line |
| Planar shapes | rect, hexagon, circle |
| Non-planar shapes | helix, sphere |
| Symbols | particle, normal_arrow |
6.1 Lines
segment
A straight line between two points on a guide plane.
| Field | Meaning | Constraints |
|---|---|---|
start | First endpoint | Finite |
end | Second endpoint | In the guide plane through start; at least MIN_EXTENT from start |
dir | Guide-plane normal | +X, +Y or +Z |
<element variety="segment" uid="" specifier="0">
<pos x="0" y="0" z="0"/>
<start x="597.65625" y="707.70264" z="0"/>
<end x="697.0215" y="796.26465" z="0"/>
<dir x="0" y="0" z="1"/>
<size l="0" w="0" h="0"/>
</element>
arrow
A line from tail to tip with a triangular arrowhead: a golden triangle (36° apex) whose base is perpendicular to the shaft.
| Field | Meaning | Constraints |
|---|---|---|
start | Tail | Finite |
end | Tip | In the guide plane through start; at least MIN_EXTENT from start |
dir | Guide-plane normal | +X, +Y or +Z |
size/@w | Arrowhead base length | At least MIN_EXTENT; the editor writes 8 |
belgian_arrow and british_arrow
Block arrows from the midpoint of their base to the apex of their head. Their proportions are fixed; neither variety has size parameters.
| Field | Meaning | Constraints |
|---|---|---|
start | Midpoint of the base | Finite |
end | Apex of the head | In the guide plane through start; at least MIN_EXTENT from start |
dir | Guide-plane normal | +X, +Y or +Z |
wave_line
A sine-like wave along a centreline on a guide plane.
| Field | Meaning | Constraints |
|---|---|---|
start, end | Endpoints of the centreline | end in the guide plane through start; at least MIN_EXTENT apart |
dir | Guide-plane normal | Unit vector; the editor writes +X, +Y or +Z |
size/@w | Amplitude: the peak deviation from the centreline, i.e. half the wave's peak-to-peak height | Finite; zero draws a straight line |
@specifier | Number of periods | 1–255 |
For a positive amplitude, the first half-period bulges towards dir × (end − start); a negative amplitude mirrors the wave.
<element variety="wave_line" uid="" specifier="3">
<pos x="0" y="0" z="0"/>
<start x="197.20459" y="554.07715" z="0"/>
<end x="403.19824" y="553.833" z="0"/>
<dir x="0" y="0" z="1"/>
<size l="0" w="50" h="0"/>
</element>
6.2 Planar shapes
rect
A rectangle with one axis-aligned edge.
| Field | Meaning | Constraints |
|---|---|---|
@uid | Identifier, referenced by cuboids | Required (Section 5.6) |
pos | Origin corner: the corner from which the rect extends by l along start and by w along dir × start | Finite |
start | Edge direction u | +X, +Y or +Z |
dir | Normal n | Unit vector, perpendicular to start |
size/@l | Extent along start | At least MIN_EXTENT |
size/@w | Extent along dir × start | At least MIN_EXTENT |
With v = n × u, the vertices are pos, pos + l·u, pos + l·u + w·v and pos + w·v, counter-clockwise about n. The handedness v = n × u is part of the convention. The normal need not be axis-aligned: a tilted rect has start along an axis and dir anywhere in the plane perpendicular to it.
<element variety="rect" uid="647" specifier="0">
<pos x="700" y="0" z="100"/>
<start x="0" y="0" z="1"/>
<end x="0" y="0" z="0"/>
<dir x="0" y="1" z="0"/>
<size l="200" w="200" h="0"/>
</element>
Here u = +Z and v = +Y × +Z = +X, so the rect spans x 700–900 and z 100–300 in the plane y = 0.
hexagon
A regular hexagon.
| Field | Meaning | Constraints |
|---|---|---|
pos | Centre | Finite |
start | Direction from the centre to vertex v0; fixes the rotation about the normal | Unit vector, perpendicular to dir |
dir | Normal | Unit vector, any direction |
size/@l | Circumradius | At least MIN_EXTENT |
circle
| Field | Meaning | Constraints |
|---|---|---|
pos | Centre | Finite |
dir | Normal of the circle's plane | +X, +Y or +Z |
size/@l | Radius | At least MIN_EXTENT |
<element variety="circle" uid="" specifier="0">
<pos x="459.72162" y="0" z="244.87115"/>
<start x="0" y="0" z="0"/>
<end x="0" y="0" z="0"/>
<dir x="0" y="1" z="0"/>
<size l="57.84457" w="0" h="0"/>
</element>
6.3 Non-planar shapes
helix
| Field | Meaning | Constraints |
|---|---|---|
pos | Centre of the base circle, on the axis | Finite |
dir | Axis direction: the way the helix rises | +X, +Y or +Z |
size/@l | Radius | At least MIN_EXTENT |
size/@h | Height: the rise from the first point to the last | At least MIN_EXTENT |
@specifier | Handedness with respect to dir: 0 right-handed, 1 left-handed | 0 or 1 |
start | Reserved (phase) | MUST be zero |
size/@w | Reserved (pitch) | MUST be zero |
The helix makes exactly NUMBER_OF_HELIX_WINDS turns. Its first point lies on the base circle in the canonical start direction (Section 5.8); its last point lies exactly size/@h above the first, so helices with the same axis, radius and handedness can be stacked without a kink.
<element variety="helix" uid="" specifier="0">
<pos x="396.3865" y="0" z="589.0807"/>
<start x="0" y="0" z="0"/>
<end x="0" y="0" z="0"/>
<dir x="0" y="1" z="0"/>
<size l="38.97389" w="0" h="75"/>
</element>
sphere
| Field | Meaning | Constraints |
|---|---|---|
pos | Centre | Finite |
dir | Normal of the guide plane the sphere was drawn on; recorded but not interpreted, sign irrelevant | Unit vector; the editor writes +X, +Y or +Z |
size/@l | Radius | At least MIN_EXTENT |
6.4 Symbols
particle
A particle, optionally with a spin arrow through its centre.
| Field | Meaning | Constraints |
|---|---|---|
pos | Centre | Finite |
size/@l | Radius | At least MIN_EXTENT |
dir | Spin direction, or (0, 0, 0) for a particle without spin; the sign is the way the arrow points | Exactly zero, or ±X, ±Y or ±Z |
size/@h | Spin arrow shaft length: always 6 × radius | Informative; ignored on read |
@specifier | Planes of the spin arrow's head blades (below) | 0–2 |
@specifier | Spin along ±X | Spin along ±Y | Spin along ±Z |
|---|---|---|---|
| 0 | XY plane | XY plane | XZ plane |
| 1 | XY plane | XY plane | YZ plane |
| 2 | XZ plane | XY plane | YZ plane |
normal_arrow
An arrow perpendicular to a guide plane, touching the plane at pos – at its tail when it points away from the plane, at its head when it points towards it.
| Field | Meaning | Constraints |
|---|---|---|
pos | Point on the guide plane | Finite |
dir | Direction the arrowhead points; the guide plane's normal is |dir|, and the plane passes through pos | ±X, ±Y or ±Z |
@specifier | Side of the guide plane: 0 the side its positive normal points to, 1 the other side | 0 or 1 |
size/@l | Shaft length | At least MIN_EXTENT |
On a horizontal guide plane (normal +Y):
dir | @specifier | Drawn |
|---|---|---|
(0, 1, 0) | 0 | Above the plane, pointing up |
(0, −1, 0) | 0 | Above the plane, pointing down to it |
(0, −1, 0) | 1 | Below the plane, pointing down |
(0, 1, 0) | 1 | Below the plane, pointing up to it |
7. Bodies
A body is a solid derived from one or more elements, which it references by uid in its <genesis> children. A body's own uid is empty.
cuboid
A rect extruded along its normal.
| Field | Meaning | Constraints |
|---|---|---|
genesis | The uid of the base rect | Exactly one entry, referencing a rect in the same file |
size/@h | Extrusion height along the base rect's normal; a negative value extrudes against it | Finite |
<body variety="cuboid" uid="" specifier="0">
<genesis>647</genesis>
<pos x="0" y="0" z="0"/>
<start x="0" y="0" z="0"/>
<end x="0" y="0" z="0"/>
<dir x="0" y="0" z="0"/>
<size l="0" w="0" h="150"/>
</body>
A cuboid whose base rect is unreadable is omitted with it.
8. Conformance
A conforming file is valid against the XSD for its schema version and satisfies every rule of the convention it declares.
A conforming writer writes every significant field within its constraints, every unused field as zero (or empty) and every reserved field as zero; writes only conforming elements; and declares its convention in <format> and the matching XSD in <schema>.
A conforming reader rejects files with an unsupported schema or convention or a mismatched schema/@href; interprets every significant field as specified and ignores unused fields; and omits unreadable elements – including those with non-zero reserved fields or a duplicate uid – together with the bodies that depend on them, without rejecting the file.
Anything a conforming writer writes, a conforming reader accepts.
9. Version history
Convention 2.1.9 – schema 2.1
The first published convention of schema 2.1. Earlier conventions were used only during development and are not supported.
Appendix A – XSD
The schema is published at https://superlattix.com/schema/v2.1.xsd.
Show the schema
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="model" type="modelType"/>
<xs:simpleType name="versionComponentType">
<xs:restriction base="xs:token">
<xs:pattern value="[A-Za-z0-9][A-Za-z0-9_\-]*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="uidType">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]*"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="formatType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:string" name="id" use="required"/>
<xs:attribute type="versionComponentType" name="version_major" use="required"/>
<xs:attribute type="versionComponentType" name="version_minor" use="required"/>
<xs:attribute type="versionComponentType" name="version_patch" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="schemaType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:string" name="href"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="createdType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:dateTime" name="at"/>
<xs:attribute type="xs:string" name="tool"/>
<xs:attribute type="xs:string" name="tool_version"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="metadataType">
<xs:sequence>
<xs:element type="formatType" name="format"/>
<xs:element type="schemaType" name="schema"/>
<xs:element type="createdType" name="created"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="vecType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:float" name="x" use="optional"/>
<xs:attribute type="xs:float" name="y" use="optional"/>
<xs:attribute type="xs:float" name="z" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="sizeType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:float" name="l" use="optional"/>
<xs:attribute type="xs:float" name="w" use="optional"/>
<xs:attribute type="xs:float" name="h" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="elementType">
<xs:sequence>
<xs:element type="vecType" name="pos" minOccurs="0"/>
<xs:element type="vecType" name="start" minOccurs="0"/>
<xs:element type="vecType" name="end" minOccurs="0"/>
<xs:element type="vecType" name="dir" minOccurs="0"/>
<xs:element type="sizeType" name="size" minOccurs="0"/>
</xs:sequence>
<xs:attribute type="xs:string" name="variety" use="optional"/>
<xs:attribute type="uidType" name="uid" use="optional"/>
<xs:attribute type="xs:unsignedByte" name="specifier" use="optional"/>
</xs:complexType>
<xs:complexType name="bodyType">
<xs:sequence>
<xs:element type="xs:unsignedLong" name="genesis" minOccurs="0" maxOccurs="unbounded"/>
<xs:element type="vecType" name="pos"/>
<xs:element type="vecType" name="start"/>
<xs:element type="vecType" name="end"/>
<xs:element type="vecType" name="dir"/>
<xs:element type="sizeType" name="size"/>
</xs:sequence>
<xs:attribute type="xs:string" name="variety"/>
<xs:attribute type="uidType" name="uid"/>
<xs:attribute type="xs:unsignedByte" name="specifier"/>
</xs:complexType>
<xs:complexType name="modelType">
<xs:sequence>
<xs:element type="metadataType" name="metadata"/>
<xs:element type="elementType" name="element" minOccurs="0" maxOccurs="unbounded"/>
<xs:element type="bodyType" name="body" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Appendix B – Constants
| Constant | Value | Used by |
|---|---|---|
MIN_EXTENT | 0.1 | All varieties |
DIR_TOL | 1 × 10⁻⁴ | Directions and axis alignment |
PLANE_TOLERANCE | 0.001 | Points in a guide plane |
HELIX_PHASE | 0 rad | Helix, circle |
NUMBER_OF_HELIX_WINDS | TODO | Helix |
| Wave line periods | 1–255 | Wave line |
