Pre-release VNX 0.11.0 may change at any time.
VNX

Concepts

On this page
  1. The document
  2. What goes where
  3. Networks
  4. Plans
  5. Tracks
  6. Points
  7. Areas
  8. Folders
  9. Data records
  10. Descriptions, look, hidden and pinned
  11. Positions and values
  12. What a reader does with a damaged file
  13. VNZ archives and attachments
  14. What VNX does not carry

This page explains the VNX model: what each kind of object is, where it can go, and how it differs from the GPX and KML ideas you may know. The specification has the exact rules. Section numbers in brackets, such as (§3.3), point to it.

The document

A VNX document is one JSON object. It has a required vnx key with the format version, and up to six collections:

{
  "vnx": "0.11.0",
  "folders":   [],
  "networks":  [],
  "plans":     [],
  "tracks":    [],
  "points":    [],
  "areas":     []
}

Every collection is optional, and an empty collection means the same as no collection. A document does not say which software wrote it or when (§3.1).

A top-level key that contains a full stop, such as com.example.routes, is an application key. It adds a kind of content that VNX does not define. See Extensions.

What goes where

Object Where it can be What it holds
folder top level an id, a name, and an optional parent folder
network top level nodes, arcs, highlights, points, areas
plan top level its own nodes and arcs, and one walk
track top level segments of recorded positions
point top level, or in a network one position, at
area top level, or in a network one ring of positions, polygon
highlight in a network a walk over the network's arcs
data record in the data array of any item, or of an arc a @type and any fields

Every top-level item except a folder can name the folder it is in with a folder key. Points, areas and highlights in a network do not have folder, because the network already holds them (§3.10).

Networks

A network is a graph. It is the central idea of VNX and the thing GPX, KML and GeoJSON cannot hold.

One network: four nodes, three arcs, two highlights that share an arc node-1node-2node-3node-4 arc-1arc-2arc-3 Highlight “North route”: arc-1, then arc-2 Highlight “East route”: arc-1, then arc-3
Both highlights walk arc-1. The file stores that line once. Move a pip on arc-1 and both highlights follow it.

How this differs from GPX and KML

Idea GPX / KML VNX
A trail line each track or LineString has its own copy of the coordinates an arc, stored once and referred to by ID
A junction no object; two lines happen to have points near each other a node that arcs start and end at
A named route along trails a separate polyline that copies the coordinates a highlight: a list of arc IDs, in order
Two routes on the same trail two copies that can drift apart two highlights that refer to the same arc
Information about a stretch of trail extensions on a whole track, or nothing data records on a highlight (its walk) or on an arc

So the shared geometry is the meaning of the file, not a way to make it smaller. A reader that only wants lines can draw each highlight by following its arcs. The writing guide shows how.

Walks

A walk is an ordered array of passes. Each pass covers one arc, and the order is the direction of travel (§3.3.3).

"walk": [
  { "arc": "arc-1", "from": "node-1" },
  { "arc": "arc-2", "to": "node-3" }
]

A pass has arc, and sometimes these keys:

Key Value Meaning
from node ID or [lon, lat] where the pass enters its arc
to node ID or [lon, lat] where the pass leaves its arc
turn [lon, lat] the walk goes out to this point on the arc and comes back
pin [lon, lat] the user fixed this pass with a handle at this point

from and to appear only where they are needed: the first pass has from, the last pass has to, and a pass that starts part way along an arc (a from position) also has to. Every other pass starts at the node where the previous pass ended. It leaves by the other end of its arc, or, if it has a turn, by the node it entered by. A position on an arc means the nearest point on the arc's line. A walk can start or end part way along an arc, so a highlight can cover part of a trail.

Highlights

A highlight is a light container for data along a walk. It has a walk, an optional name, and data. What a highlight is, other than its name, is what its data records say: a rating, a warning, a surface type, a tag (§3.3.3).

A highlight in VNX is not a route that a user follows from start to finish only. It can mark any stretch of the network: "boggy after rain", "the scramble section", "the best descent".

Points and areas in a network

A network can also hold points and areas, with the same shape as top-level points and areas. Put them in the network when they belong to it, for example a shelter on the network's trails, or a no-go zone for its routes.

Plans

A plan is a top-level item that owns a small graph of its own (nodes and arcs) and carries one walk over it. It is for a single route that is not part of a shared network, such as a planned day out (§3.4).

Tracks

A track is a recording: what a GPS device logged (§3.5).

{
  "name": "Lairig Ghru, 12 May",
  "started": "2026-05-12T07:03:11Z",
  "ended": "2026-05-12T16:41:02Z",
  "segments": [
    { "pips": [[-3.6521, 57.1, 940, 1778569391000], [-3.651, 57.1012, 951, 1778569451000]] }
  ]
}

Points

A point is one position, at, with a name and data (§3.6). It is the same shape at the top level and in a network. A GPX <wpt> is a point.

{
  "name": "Spring",
  "at": [-3.6521, 57.1, 940],
  "data": [{ "@type": "com.example.description", "value": "Reliable after rain." }]
}

Areas

An area is one ring of positions, polygon (§3.7).

Folders

A folder groups top-level items. It is the only top-level object with an id, because it is the only one that other objects refer to (§3.2).

"folders": [
  { "id": "cairngorms", "name": "Cairngorms" },
  { "id": "approaches", "name": "Approaches", "parent": "cairngorms" }
]

An item goes in a folder with "folder": "approaches". A folder goes in another folder with parent. Folder ids are unique in a document, and parents never form a loop (§3.2). Folders can hold networks, plans, tracks, top-level points, top-level areas, and other folders.

Data records

Every item, and every arc, can have a data array of records. A record is a JSON object with a @type and any other fields (§5):

"data": [
  { "@type": "com.example.tag", "value": "day-walk" },
  { "@type": "com.example.surface", "value": "rock", "confidence": 0.8 }
]

VNX defines no record types. Applications define them, each under its own globally unique ID (reverse DNS, or a UUID). A reader keeps a record of a type it does not know, and does not report an error for it. See Extensions.

Descriptions, look, hidden and pinned

Positions and values

What a reader does with a damaged file

A reader is tolerant of damage, and reports all of it (§6.2):

Through version 0.x, each minor version is its own series. A 0.11 reader accepts any 0.11.x file and refuses every other minor series, such as 0.12 (§2.2).

VNZ archives and attachments

A .vnz file is a ZIP archive. It holds the document as doc.vnx, first in the archive, and any other files beside it: photos, audio, documents (§7).

doc.vnx
com.example.photo/summit.jpg
com.example.photo/descent.jpg
org.example.audio/ridge-notes.m4a

What VNX does not carry

By design, VNX has no cached distances, elevation gain or bounds (derive them from the geometry), no deleted items, no durable item identity, no map tiles, and no creation or change times for items (§6.1).