VNX extensions
For VNX 0.11.0. Pre-release: these extensions and VNX itself may change at any time.
Viatrail reads and writes VNX files. VNX defines trail networks, plans, tracks, points and areas, and it lets each application add its own data. This page lists what Viatrail adds. It is for developers and agents who want to read Viatrail's data from a VNX file, or write a file that Viatrail understands.
The general rules for extensions (data records, type IDs, application keys and attachments) are on vnx.tools. This page uses them and does not repeat them.
JSON Schema
Every type on this page is in one machine-readable file: viatrail-extensions.schema.json (JSON Schema 2020-12). The app's code generates it, so it matches the app. The tables below come from the same file.
- Validate a whole document against it to check the two application keys.
- Each data record type is a
$defsentry named by its@type. Check a record against the entry that its@typenames. - Keys that start with
x-give facts that JSON Schema has no word for: where a record can be (x-vnx-locations), whether Viatrail writes it only itself (x-internal), a field's kind (x-kind), a date's encoding (x-encoding), attachment paths (x-attachment-paths), the data condition operators (x-data-operators) and the built-in types a definition may extend (x-nameable-built-in-types).
Names and reading rules
Viatrail's type IDs and application keys all start with app.viatrail., because Viatrail owns the domain viatrail.app. Other applications must not define types under this prefix.
When Viatrail imports a file:
- A record of a type on this page is read as its table says.
- A record of any other type, under
app.viatrail.or any other prefix, is kept unchanged with no report. It is written back unchanged on the next export. - Types marked internal below are written by Viatrail. Read them if they help you. Do not write them, and keep them unchanged when you write a file back.
Data record types
Each record is an object in the data array of an item, with an @type and the fields below. Every field is optional. "Where" lists the places in a VNX document where Viatrail reads the type.
{
"name": "Corrour bothy",
"at": [-3.6878, 57.0221, 560],
"data": [
{ "@type": "app.viatrail.shelter", "rating": 4, "booking": false, "beds": 8 },
{ "@type": "app.viatrail.water", "seasonal": false },
{ "@type": "app.viatrail.note", "text": "Burn **200 m** south. Bring a stove." }
]
}
app.viatrail.camp Camp
Where: points[], networks[].points[].
| Field | Type | Values | Meaning |
|---|---|---|---|
rating | integer, 1 to 5 (stars) | Overall rating? | |
flat | integer, 1 to 5 (stars) | How flat is the ground? | |
sheltered | integer, 1 to 5 (stars) | How sheltered is the camp from the wind? | |
water | integer, 1 to 5 (stars) | How convenient / clean is the water source? | |
booking | boolean | Does the camp need booking? |
app.viatrail.shelter Shelter
Where: points[], networks[].points[].
| Field | Type | Values | Meaning |
|---|---|---|---|
rating | integer, 1 to 5 (stars) | Overall rating? | |
booking | boolean | Does the shelter need booking? | |
beds | integer | Approximately how many beds? |
app.viatrail.hotel Hotel
Where: points[], networks[].points[].
| Field | Type | Values | Meaning |
|---|---|---|---|
rating | integer, 1 to 5 (stars) | Overall rating? | |
booking | boolean | Does the hotel need booking? | |
rooms | integer | Approximately how many rooms? |
app.viatrail.shop Shop
Where: points[], networks[].points[].
| Field | Type | Values | Meaning |
|---|---|---|---|
resupply | string | kiosk Kiosk, grocery Grocery, market Market | What can you resupply here? |
app.viatrail.settlement Settlement
Where: points[], networks[].points[], areas[], networks[].areas[].
| Field | Type | Values | Meaning |
|---|---|---|---|
hotels | boolean | Does this settlement have hotels? | |
resupply | string | kiosk Kiosk, grocery Grocery, market Market | What can you resupply here? |
app.viatrail.water Water
Where: points[], networks[].points[].
| Field | Type | Values | Meaning |
|---|---|---|---|
rating | integer, 1 to 5 (stars) | Overall rating? | |
seasonal | boolean | Is this water source dry in some seasons? |
app.viatrail.note Note
Where: networks[], tracks[], points[], networks[].points[], networks[].highlights[], plans[], areas[], networks[].areas[].
| Field | Type | Values | Meaning |
|---|---|---|---|
text | string | Text |
app.viatrail.photo Photo
Where: networks[], tracks[], points[], networks[].points[], networks[].highlights[], plans[], areas[], networks[].areas[].
A data type definition cannot name this type. Its photos travel only in a .vnz, as the files it names.
| Field | Type | Values | Meaning |
|---|---|---|---|
photos | list of string | an archive entry, app.viatrail.photo/{id}.jpg | Photos |
app.viatrail.route Route
Where: networks[].highlights[].
| Field | Type | Values | Meaning |
|---|---|---|---|
rating | integer, 1 to 5 (stars) | Overall rating? |
app.viatrail.terrain Terrain
Where: networks[].highlights[].
| Field | Type | Values | Meaning |
|---|---|---|---|
terrain | string | major_road Major Road, minor_road Minor Road, trail Trail, cross_country Cross-Country, bush_bash Bush Bash | Terrain type |
app.viatrail.hazard Hazard
Where: points[], networks[].points[], networks[].highlights[], areas[], networks[].areas[].
| Field | Type | Values | Meaning |
|---|---|---|---|
description | string | Description of the hazard |
Internal types
The app does not list these as data types. Each one's own description says who may write it. Keep them unchanged when you write a file back.
app.viatrail.tag Tag
Internal. Where: networks[], tracks[], points[], networks[].points[], networks[].highlights[], plans[], areas[], networks[].areas[].
A free-text tag. Any application may write it. It is internal only in that the app does not list it as a data type: it shows tags as chips. A data type definition cannot name this type.
| Field | Type | Values | Meaning |
|---|---|---|---|
value | string | Value |
app.viatrail.routing Routing (internal)
Internal. Where: plans[].arcs{}, networks[].arcs{}.
Written by Viatrail; do not write.
| Field | Type | Values | Meaning |
|---|---|---|---|
source | string | engine, gpx-import, gps-recording, user-snap, user-drawn, copied | How the arc's line was made. Only "engine" marks the arc as routed by an engine; with any other value, or no record, Viatrail does not route the arc again. |
config | object | The engine settings the arc was routed with. When source is "engine", config must have library-enabled, base-map-enabled, cross-country-enabled and forest-avoidance, or the import fails. |
app.viatrail.compute-failed Routing failed
Internal. Where: plans[].arcs{}, networks[].arcs{}.
Written by Viatrail; do not write. Its presence on an arc says the engine could not route it, and the line is a straight placeholder. It has no fields.
No fields.
Photos
An app.viatrail.photo record holds an ordered list of photos for its item. In a VNX document, each photo is the entry name of a JPEG file in the same .vnz archive:
{ "@type": "app.viatrail.photo", "photos": ["app.viatrail.photo/3f2a9c41.jpg"] }
The files go in a folder named after the type, as VNX recommends (VNX §7.2):
doc.vnx
app.viatrail.photo/3f2a9c41.jpg
app.viatrail.photo/77b01e8d.jpg
{id}is an ID that the exporting app chose for the photo. It has no meaning outside the file. On import, Viatrail gives each photo a new ID.- Viatrail finds a photo by the entry name that its record lists. It ignores files in the archive that no record names, with no error.
- A plain
.vnxfile cannot carry photos. When Viatrail exports without photos, it leaves out the photo records that list photos. A photo record with an empty list stays. - The same photo can be listed by more than one record. The archive holds it once.
Look and behaviour
VNX defines no style. Viatrail carries how an item is drawn in data records of its own, one record type for each section of the app's style editor. Each record goes in the data array of the item it styles.
| Record | Editor section | On |
|---|---|---|
app.viatrail.style.marker | Marker | points, areas, tracks, plans, networks |
app.viatrail.style.line | Line | areas, tracks, plans, networks |
app.viatrail.style.fill | Fill | areas |
app.viatrail.style.card | Card | points, areas, tracks, plans, networks |
app.viatrail.behaviour | Behaviour | areas, tracks, plans, networks (a point is always selectable) |
- An item carries only the records for the sections it sets. A record or key that is not there means Automatic: the rule sets decide.
- An item holds at most one record of each type. A second one is reported and ignored.
- A highlight has no look of its own: its line comes from its network and the rules. Viatrail reports a look or behaviour record on a highlight and does not store it.
- Colours are a
hue, an angle in degrees on a colour wheel from 0 to 359, with anintensityand adarkness. - An item's rank on the map, which decides which marker or card stays when two collide, is its card
importanceplus theboostof each of its records whose data marker type isprimaryorsecondary.
{
"name": "Wild camp",
"at": [-3.6878, 57.0221, 560],
"data": [
{ "@type": "app.viatrail.camp", "rating": 4 },
{ "@type": "app.viatrail.style.marker", "icon": "lucide:tent", "hue": 105, "outline": "circle" },
{ "@type": "app.viatrail.style.card", "importance": 4, "show-card": "yes" }
]
}
app.viatrail.style.marker Marker
Where: points[], networks[].points[], plans[], tracks[], areas[], networks[].areas[], networks[].
The item's own marker. A rule styles markers with app.viatrail.style.marker.item and app.viatrail.style.marker.data instead. Write at most one per item or rule. An absent key is Automatic: the rule sets decide. A value the app cannot use is dropped with a report and the rest are kept.
No fields.
app.viatrail.style.line Line style
Where: plans[], tracks[], areas[], networks[].areas[], networks[].
How the item's line is drawn: on a plan, a track, a network or an area. In a rule: the line of each item it matches. Write at most one per item or rule. An absent key is Automatic: the rule sets decide. A value the app cannot use is dropped with a report and the rest are kept.
| Field | Type | Values | Meaning |
|---|---|---|---|
hue | integer, 0 to 359 | ||
intensity | string | pale, normal, intense | |
darkness | string | light, normal, dark | |
width | integer | 2, 4, 6 | |
casing | string | light, dark | |
stripe | string | none, solid, dashes, dots | |
show-name | string | yes, no |
app.viatrail.style.fill Fill style
Where: areas[], networks[].areas[].
How an area is filled. Write at most one per item or rule. An absent key is Automatic: the rule sets decide. A value the app cannot use is dropped with a report and the rest are kept.
| Field | Type | Values | Meaning |
|---|---|---|---|
hue | integer, 0 to 359 | ||
intensity | string | pale, normal, intense | |
darkness | string | light, normal, dark | |
strength | string | light, medium, strong | |
pattern | string | solid, hatch, none |
app.viatrail.style.card Card
Where: points[], networks[].points[], plans[], tracks[], areas[], networks[].areas[], networks[].
The item's card on the map. Write at most one per item or rule. An absent key is Automatic: the rule sets decide. A value the app cannot use is dropped with a report and the rest are kept.
| Field | Type | Values | Meaning |
|---|---|---|---|
importance | integer (any 32-bit whole number) | Any whole number a 32-bit signed integer holds. The map places the labels of an item with a higher importance first. 0 is the default. | |
show-card | string | yes, no | |
tag-fill | string | card, solid |
app.viatrail.behaviour Behaviour
Where: points[], networks[].points[], plans[], tracks[], areas[], networks[].areas[], networks[].
Whether a tap selects the item. In a rule, hide hides the items it matches; an item cannot hide itself. Write at most one per item or rule. An absent key is Automatic: the rule sets decide. A value the app cannot use is dropped with a report and the rest are kept.
| Field | Type | Values | Meaning |
|---|---|---|---|
hide | string | yes, no | |
selectable | string | yes, no | Whether a tap on the map can select the item. It has no effect on a "waypoint" or a "highlight" item, which is always selectable; an item's own settings on one are refused. "waypoint" means a VNX point, top-level or in a network. |
The marker shape used by markers in rules
| Field | Type | Values | Meaning |
|---|---|---|---|
icon | string | An icon: "lucide:<id>" for a Lucide icon or "emoji:<id>" for an emoji. "none" draws no glyph. An id the app does not have is dropped with a report. | |
hue | integer, 0 to 359 | ||
intensity | string | pale, normal, intense | |
darkness | string | light, normal, dark | |
outline | string | circle, square, hexagon, diamond, flag, none |
Icon IDs
A marker's icon (on an item, in a rule, or in a custom data type) is one of three things:
| Value | Meaning |
|---|---|
lucide:<id> | A Lucide icon. The id is Lucide's own icon name, for example lucide:tent or lucide:mountain-snow. |
emoji:<id> | An emoji, named by an id made from its Unicode name (below), for example emoji:tent for ⛺. |
none | No glyph: the marker is drawn with nothing in it. |
Viatrail accepts only the ids in its two lists. They are published here so that a writer can look an id up:
lucide-ids.json: 1,665 Lucide ids. They are the icons Viatrail ships, taken from Lucide's published icon set. Use this list, not the newest Lucide release: an icon added to Lucide later is not in the app.emoji-ids.json: 1,898 emoji, each with its id, the emoji character and its Unicode name.
An icon whose id is not in its list, a value with no lucide: or emoji: prefix, and a bare word such as tent are dropped with a report. The rest of the record is kept.
How an emoji id is made
The emoji set is Unicode Emoji 15.1: every fully-qualified emoji, without skin-tone variants. The id is the emoji's Unicode name, changed to ASCII snake_case in three steps:
- Spell
#as "number sign" and*as "asterisk". - Decompose the name (Unicode NFKD) and drop every character that is not ASCII. Accents go, and so does a curly apostrophe, with no space in its place.
- Lower-case it, change each run of characters other than
a–zand0–9to one_, and trim_from both ends.
| Emoji | Unicode name | Value |
|---|---|---|
| #️⃣ | keycap: # | emoji:keycap_number_sign |
| 🥇 | 1st place medal | emoji:1st_place_medal |
| 🪅 | piñata | emoji:pinata |
| 🇨🇮 | flag: Côte d’Ivoire | emoji:flag_cote_divoire |
Custom data types
Users can define their own data types in Viatrail, and extend the built-in ones with more fields. A definition travels in the top-level application key app.viatrail.datatypes. Its value is a list of data type sets: each is a named library item holding data type definitions. A custom type's datatype is its own @type ID: a globally unique identifier, either a reverse-DNS name the user owns or a UUID. The app gives a type made in its settings a UUID.
"app.viatrail.datatypes": [
{
"name": "Pools",
"types": [
{
"datatype": "org.example.pool",
"label": { "en": "Pool", "fr": "Bassin" },
"hosts": ["area"],
"fields": [
{ "name": "depth", "kind": "number", "label": { "en": "Depth", "fr": "Profondeur" } },
{ "name": "swim", "kind": "bool", "label": { "en": "Good for swimming" } }
]
}
]
}
]
Records of that type then go in the data of an item: { "@type": "org.example.pool", "depth": 2.5, "swim": true }.
Data type set
| Field | Type | Values | Meaning |
|---|---|---|---|
name required | string | The data type set's name. It may be empty. | |
folder | string | The id of a folder in the same document. Absent or empty: the import places it where the user chooses. | |
pinned | string | When the data type set was pinned: a VNX timestamp (§4.3). | |
types required | list of datatype-type |
Type
One type. A type that breaks a rule is left out at import, alone, with a report; an unknown key is removed with a report.
| Field | Type | Values | Meaning |
|---|---|---|---|
datatype required | string | The @type of the records this type describes. Inside app.viatrail. it must be one of the built-in types a definition may name (x-nameable-built-in-types), spelled exactly: such a type is extended, not replaced. | |
label | object: label-map | Custom types only, and required there: the type's name. An extended built-in type has the registry's name. | |
hosts | list of strings | network, track, waypoint, highlight, plan, area | Custom types only: the item kinds the type is meant for. Viatrail does not check it on import. "waypoint" means a VNX point, top-level or in a network. |
fields | list of datatype-field | ||
summary | string | A template for a one-line summary of a record. A fault drops the summary, not the type. | |
strings | object | Phrases a summary can use: phrase key, then language, then a text or a text for each plural form. English is required, and a plural table needs every form the language uses. | |
behaviours | list of strings | plan, list, camp | Custom types only. plan: a highlight with a record of the type can start a plan along its line. list: the network lists the records of the type on its highlights. camp: a point with a record of the type can end a day of a plan. |
marker | object | Custom types only: the type's icon and hue. Absent: lucide:shapes at hue 0. An unusable value is removed with a report, and the type then has that default. |
Field
| Field | Type | Values | Meaning |
|---|---|---|---|
name required | string | The key in the record body. | |
kind required | string | text, markdown, bool, number, integer, stars, enum, date | |
label | object: label-map | Required, except on a field the extended built-in type already has. | |
note | object: label-map | ||
options | list of datatype-option | The values of an enum field. Kept but not used on a field of another kind. |
Enum option
| Field | Type | Values | Meaning |
|---|---|---|---|
value required | string | ||
label | object: label-map | Required, except on an option the extended built-in field already has. | |
note | object: label-map |
Label
Text by language: each key a lowercase primary language subtag (en, fr). English is required. A text may not be blank.
Rule sets
A rule set says how the map draws the items in a folder and in every folder below it. Rule sets travel in the top-level application key app.viatrail.rulesets. A file holds only the user's own rule sets. Viatrail's default rule set is never exported, whether the user changed it or not.
"app.viatrail.rulesets": [
{
"name": "Highlight wet ground",
"enabled": true,
"rules": [
{
"name": "Boggy stretches in blue",
"item-types": ["highlight"],
"conditions": [{ "field": "tag", "operator": "contains", "value": "boggy" }],
"style": [
{ "@type": "app.viatrail.style.line", "hue": 210, "intensity": "intense", "width": 6, "stripe": "dashes" }
]
},
{
"name": "Water sources",
"item-types": ["waypoint"],
"style": [
{ "@type": "app.viatrail.style.marker.data", "markers": [
{ "type": "app.viatrail.water", "marker": { "icon": "lucide:droplet", "hue": 210 }, "marker-type": "primary", "boost": 2 }
] }
]
}
]
}
]
A rule's style list holds app.viatrail.style.line, .fill and .card records, the same as on an item, plus two that only a rule has: app.viatrail.style.marker.item (a marker for each item kind the rule matches) and app.viatrail.style.marker.data (the data types the rule styles: for each, a marker, a marker-type of none, primary or secondary, and a boost). A rule's behaviour key holds the same app.viatrail.behaviour record as on an item, and only a rule may set its hide, which hides the matched items from the map. The rule's other fields (item-types, match-any, conditions) say which items it matches. In these lists, "waypoint" means a VNX point.
Rule set
| Field | Type | Values | Meaning |
|---|---|---|---|
name required | string | ||
enabled required | boolean | ||
folder | string | The id of a folder in the same document. Absent or empty: the import places it where the user chooses. A folder the document does not have drops the rule set with a report. | |
rules | list of rule | ||
pinned | string | When the rule set was pinned: a VNX timestamp (§4.3). |
Rule
| Field | Type | Values | Meaning |
|---|---|---|---|
name | string | ||
item-types | list of strings | waypoint, plan, track, highlight, area, network | The kinds of item the rule matches. An empty list matches nothing. "waypoint" means a VNX point, top-level or in a network. |
match-any | boolean | True: an item matches when any condition holds. Absent or false: all must hold. | |
conditions | list of condition | ||
style | list of records: app.viatrail.style.line, app.viatrail.style.fill, app.viatrail.style.card, app.viatrail.style.marker.item, app.viatrail.style.marker.data | The rule's style: its style records, each an object with its @type, at most one of each type. | |
behaviour | object: app.viatrail.behaviour |
Condition
A condition the app does not know (field or operator) is kept with a report and never matches.
| Field | Type | Values | Meaning |
|---|---|---|---|
field required | string | name, text, folder, path, tag, data | What the condition tests: one of the item's texts, or (data) its data records. |
operator required | string | ||
value | string | A text condition's text. A data condition has none. | |
type | string | A data condition's data type: any @type, built-in, custom or undefined. | |
data-field | string | A data condition's field, for an operator that tests a field. | |
operand | any JSON value | A data condition's value; its shape is the operator's (x-data-operators). |
| Condition | field | operator |
|---|---|---|
| Text condition | name, text, folder, path, tag | contains, starts_with, matches_regex |
| Data condition | data | present, absent, contains, starts_with, matches_regex, set, unset, is_true, is_false, eq, ne, lt, le, gt, ge, is, is_not, one_of, before, after |
app.viatrail.style.marker.item Item markers
A rule's marker for each item kind it lists in item-types: at most one entry per kind. Rules only. "waypoint" means a VNX point, top-level or in a network.
| Field | Type | Values | Meaning |
|---|---|---|---|
markers | list of object |
Each entry in markers:
| Field | Type | Values | Meaning |
|---|---|---|---|
type required | string | waypoint, plan, track, highlight, area, network | |
marker | object: marker |
app.viatrail.style.marker.data Data markers
A rule's data types and their markers: one entry per data type the rule styles, at most one per type, in the rule's order. Rules only. marker-type: none (no marker, no card row), primary (its own marker on the map and its own named row on cards) or secondary (a small icon in one shared row on cards; on the map only when the item has no primary marker, then only the strongest). An entry with only its type picks the type and changes nothing.
| Field | Type | Values | Meaning |
|---|---|---|---|
markers | list of object |
Each entry in markers:
| Field | Type | Values | Meaning |
|---|---|---|---|
type required | string | The data type's id. The last dot-separated part must start with a letter. | |
marker | object: marker | ||
marker-type | string | none, primary, secondary | |
boost | integer (any 32-bit whole number) | Any whole number a 32-bit signed integer holds. It adds to the importance of an item with a record of the type, and orders the item's marks and records: within a marker type, a higher boost comes first. 0 is the default. |