Trail networks, in a file
VNX is a JSON format for trail data. A GPX or KML file holds lines. A VNX file also holds how those lines join: a network of nodes and arcs, and named walks drawn over it. Two walks that follow the same trail point at the same arc, so the file keeps the fact that they share it.
A plain document has the extension .vnx. A ZIP archive that holds a document
and its attachments (photos, audio, any other files) has the extension .vnz.
{
"vnx": "0.11.0",
"networks": [{
"name": "Lairig Ghru approaches",
"nodes": {
"node-1": [-3.6712, 57.118, 340],
"node-2": [-3.6605, 57.1042, 512.5]
},
"arcs": {
"arc-1": { "from": "node-1", "to": "node-2", "pips": [[-3.6644, 57.1085, 451.9]] }
},
"highlights": [{
"name": "North approach",
"walk": [{ "arc": "arc-1", "from": "node-1", "to": "node-2" }],
"data": [{ "@type": "com.example.tag", "value": "scramble" }]
}]
}]
}
A position is [lon, lat, ele, time_ms]. Longitude comes first. A file
with latitude and longitude the wrong way round still parses, and draws in the
wrong part of the world.
Start here
Write a VNX fileStep by step, with the rules that catch most writers and a checklist.
ExtensionsAdd your own data with globally unique type IDs, application keys and attachment folders.
SpecificationThe full format definition. Every rule is stated here.
For agents
Read /llms.txt first. It lists every page. /llms-full.txt
holds the concepts, the writing guide, the extensions page and the full
specification in one plain Markdown file. The JSON Schema for the document is at
/schema/vnx-0.11.schema.json. The schema checks
shape only. The specification has rules that a schema cannot state, such as
walk connectivity, and the reference tool checks them:
git clone https://github.com/dave/vnx
cd vnx/go && go run ./cmd/vnx validate --json path/to/file.vnx
Libraries and tools
The source is at github.com/dave/vnx. It holds
six libraries that read and write VNX: Go, Python, JavaScript, Rust, Kotlin and
Swift. The Go module also has the vnx command-line tool:
| Command | What it does |
|---|---|
vnx validate <file> |
Reads a .vnx or .vnz file and prints its diagnostics. --json for a machine-readable report. |
vnx outline <file> |
Prints the structure: names, and the counts of nodes, arcs, highlights, points and areas in each network. |
vnx convert --to gpx|kml|geojson [--out <out-file>] <file> |
Writes the document as GPX, KML or GeoJSON, to --out or to standard output. Put the flags before the file. Those formats cannot hold a network, so the conversion loses the structure, and the tool reports what it could not write. |
A library conforms when it passes the conformance corpus in
corpus/: files that a reader
must accept, refuse, or read with exact diagnostics, and files that a writer
must produce. To write a library in another language, read
IMPLEMENTING.md in the repository.
Why VNX exists
GPX has tracks and routes as separate lists of coordinates. KML has geometry and style, but no topology. GeoJSON has features with no relations between them. When you export a trail network to any of the three, the graph becomes a set of unrelated lines. The drawing survives. The structure does not.
VNX keeps the structure. It is not a GeoJSON extension: a reader that ignored the parts GeoJSON does not define would have almost nothing left.
VNX is not a backup format. It carries no durable identity for the things in it, so an export, an edit and an import makes copies, not updates. A VNX file is a snapshot.