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.

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:

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[].

FieldTypeValuesMeaning
ratinginteger, 1 to 5 (stars)Overall rating?
flatinteger, 1 to 5 (stars)How flat is the ground?
shelteredinteger, 1 to 5 (stars)How sheltered is the camp from the wind?
waterinteger, 1 to 5 (stars)How convenient / clean is the water source?
bookingbooleanDoes the camp need booking?

app.viatrail.shelter Shelter

Where: points[], networks[].points[].

FieldTypeValuesMeaning
ratinginteger, 1 to 5 (stars)Overall rating?
bookingbooleanDoes the shelter need booking?
bedsintegerApproximately how many beds?

app.viatrail.hotel Hotel

Where: points[], networks[].points[].

FieldTypeValuesMeaning
ratinginteger, 1 to 5 (stars)Overall rating?
bookingbooleanDoes the hotel need booking?
roomsintegerApproximately how many rooms?

app.viatrail.shop Shop

Where: points[], networks[].points[].

FieldTypeValuesMeaning
resupplystringkiosk Kiosk, grocery Grocery, market MarketWhat can you resupply here?

app.viatrail.settlement Settlement

Where: points[], networks[].points[], areas[], networks[].areas[].

FieldTypeValuesMeaning
hotelsbooleanDoes this settlement have hotels?
resupplystringkiosk Kiosk, grocery Grocery, market MarketWhat can you resupply here?

app.viatrail.water Water

Where: points[], networks[].points[].

FieldTypeValuesMeaning
ratinginteger, 1 to 5 (stars)Overall rating?
seasonalbooleanIs this water source dry in some seasons?

app.viatrail.note Note

Where: networks[], tracks[], points[], networks[].points[], networks[].highlights[], plans[], areas[], networks[].areas[].

FieldTypeValuesMeaning
textstringText

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.

FieldTypeValuesMeaning
photoslist of stringan archive entry, app.viatrail.photo/{id}.jpgPhotos

app.viatrail.route Route

Where: networks[].highlights[].

FieldTypeValuesMeaning
ratinginteger, 1 to 5 (stars)Overall rating?

app.viatrail.terrain Terrain

Where: networks[].highlights[].

FieldTypeValuesMeaning
terrainstringmajor_road Major Road, minor_road Minor Road, trail Trail, cross_country Cross-Country, bush_bash Bush BashTerrain type

app.viatrail.hazard Hazard

Where: points[], networks[].points[], networks[].highlights[], areas[], networks[].areas[].

FieldTypeValuesMeaning
descriptionstringDescription 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.

FieldTypeValuesMeaning
valuestringValue

app.viatrail.routing Routing (internal)

Internal. Where: plans[].arcs{}, networks[].arcs{}.

Written by Viatrail; do not write.

FieldTypeValuesMeaning
sourcestringengine, gpx-import, gps-recording, user-snap, user-drawn, copiedHow 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.
configobjectThe 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

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.

RecordEditor sectionOn
app.viatrail.style.markerMarkerpoints, areas, tracks, plans, networks
app.viatrail.style.lineLineareas, tracks, plans, networks
app.viatrail.style.fillFillareas
app.viatrail.style.cardCardpoints, areas, tracks, plans, networks
app.viatrail.behaviourBehaviourareas, tracks, plans, networks (a point is always selectable)
{
  "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.

FieldTypeValuesMeaning
hueinteger, 0 to 359
intensitystringpale, normal, intense
darknessstringlight, normal, dark
widthinteger2, 4, 6
casingstringlight, dark
stripestringnone, solid, dashes, dots
show-namestringyes, 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.

FieldTypeValuesMeaning
hueinteger, 0 to 359
intensitystringpale, normal, intense
darknessstringlight, normal, dark
strengthstringlight, medium, strong
patternstringsolid, 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.

FieldTypeValuesMeaning
importanceinteger (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-cardstringyes, no
tag-fillstringcard, 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.

FieldTypeValuesMeaning
hidestringyes, no
selectablestringyes, noWhether 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

FieldTypeValuesMeaning
iconstringAn 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.
hueinteger, 0 to 359
intensitystringpale, normal, intense
darknessstringlight, normal, dark
outlinestringcircle, 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:

ValueMeaning
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 ⛺.
noneNo 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:

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:

  1. Spell # as "number sign" and * as "asterisk".
  2. 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.
  3. Lower-case it, change each run of characters other than a–z and 0–9 to one _, and trim _ from both ends.
EmojiUnicode nameValue
#️⃣keycap: #emoji:keycap_number_sign
🥇1st place medalemoji:1st_place_medal
🪅piñataemoji:pinata
🇨🇮flag: Côte d’Ivoireemoji: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

FieldTypeValuesMeaning
name requiredstringThe data type set's name. It may be empty.
folderstringThe id of a folder in the same document. Absent or empty: the import places it where the user chooses.
pinnedstringWhen the data type set was pinned: a VNX timestamp (§4.3).
types requiredlist 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.

FieldTypeValuesMeaning
datatype requiredstringThe @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.
labelobject: label-mapCustom types only, and required there: the type's name. An extended built-in type has the registry's name.
hostslist of stringsnetwork, track, waypoint, highlight, plan, areaCustom 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.
fieldslist of datatype-field
summarystringA template for a one-line summary of a record. A fault drops the summary, not the type.
stringsobjectPhrases 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.
behaviourslist of stringsplan, list, campCustom 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.
markerobjectCustom 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

FieldTypeValuesMeaning
name requiredstringThe key in the record body.
kind requiredstringtext, markdown, bool, number, integer, stars, enum, date
labelobject: label-mapRequired, except on a field the extended built-in type already has.
noteobject: label-map
optionslist of datatype-optionThe values of an enum field. Kept but not used on a field of another kind.

Enum option

FieldTypeValuesMeaning
value requiredstring
labelobject: label-mapRequired, except on an option the extended built-in field already has.
noteobject: 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

FieldTypeValuesMeaning
name requiredstring
enabled requiredboolean
folderstringThe 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.
ruleslist of rule
pinnedstringWhen the rule set was pinned: a VNX timestamp (§4.3).

Rule

FieldTypeValuesMeaning
namestring
item-typeslist of stringswaypoint, plan, track, highlight, area, networkThe kinds of item the rule matches. An empty list matches nothing. "waypoint" means a VNX point, top-level or in a network.
match-anybooleanTrue: an item matches when any condition holds. Absent or false: all must hold.
conditionslist of condition
stylelist of records: app.viatrail.style.line, app.viatrail.style.fill, app.viatrail.style.card, app.viatrail.style.marker.item, app.viatrail.style.marker.dataThe rule's style: its style records, each an object with its @type, at most one of each type.
behaviourobject: app.viatrail.behaviour

Condition

A condition the app does not know (field or operator) is kept with a report and never matches.

FieldTypeValuesMeaning
field requiredstringname, text, folder, path, tag, dataWhat the condition tests: one of the item's texts, or (data) its data records.
operator requiredstring
valuestringA text condition's text. A data condition has none.
typestringA data condition's data type: any @type, built-in, custom or undefined.
data-fieldstringA data condition's field, for an operator that tests a field.
operandany JSON valueA data condition's value; its shape is the operator's (x-data-operators).
Conditionfieldoperator
Text conditionname, text, folder, path, tagcontains, starts_with, matches_regex
Data conditiondatapresent, 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.

FieldTypeValuesMeaning
markerslist of object

Each entry in markers:

FieldTypeValuesMeaning
type requiredstringwaypoint, plan, track, highlight, area, network
markerobject: 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.

FieldTypeValuesMeaning
markerslist of object

Each entry in markers:

FieldTypeValuesMeaning
type requiredstringThe data type's id. The last dot-separated part must start with a letter.
markerobject: marker
marker-typestringnone, primary, secondary
boostinteger (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.