Extensions
On this page
VNX defines geometry and structure. It defines no data types. Every application adds its own information through extensions, and every reader keeps extensions it does not understand. This page explains how.
There are three ways to extend a document:
| Mechanism | Use it for | Where it goes |
|---|---|---|
| Data record | information about one item or arc: a rating, a tag, a note, a surface, a photo | the data array of that item or arc |
| Application key | a new kind of thing that is not about one item: a set of routing rules, a type catalogue | a top-level key with a full stop in its name |
| Attachment | files that records or keys refer to: photos, audio, documents | a folder in a .vnz archive |
Data records
Every item (folder, network, highlight, plan, track, point, area) and
every arc can have a data array. Each entry is a record: a JSON object with a
@type and any other fields (§5).
{
"name": "Spring",
"at": [-3.6521, 57.1, 940],
"data": [
{ "@type": "com.example.water", "value": "reliable", "treated": false },
{ "@type": "com.example.tag", "value": "resupply" },
{ "@type": "com.example.tag", "value": "day-2" }
]
}
Rules for records
datais a list, not a map. A record type can appear more than once. Two tags are two records. VNX does not say what a reader does with several records of one type. Your type defines that.- The body is yours. Apart from
@type, a reader does not look inside a record. It does not check field types, ranges or names. A field may even be calledtype. - Unknown types are kept. A reader that does not know a type keeps the record, does not report it, and writes it back unchanged after an edit. This is true on every host, including a host where the reader did not expect the type.
- Meaning is type plus host. One type can mean one thing on a highlight and another on an area. Say in your documentation which hosts your type is for.
Why @type: the @ marks the key as structure, not data. VNX borrows the
spelling from JSON-LD, but a VNX document is not JSON-LD and has no @context.
Where to put a record
- On a highlight, a record applies along the highlight's walk: "this stretch is a scramble". This is the main use of highlights. A highlight has no other content, so its records are what it is.
- On an arc, a record applies to that piece of trail itself, whatever walks use it: "this arc was routed by an engine".
- On a point or area, a record describes that place.
- On a network, plan, track or folder, a record describes the whole item.
Type IDs
A record's @type is a globally unique identifier: reverse DNS, or a
UUID. A reverse-DNS ID is a domain you control, written backwards, then a
name for the type. A UUID (3f2b8c1e-7a4d-4e9b-9c2a-5d6e7f8a9b0c) suits a type
that a user or an app makes with no domain behind it.
| You own | Your type IDs could be |
|---|---|
example.com |
com.example.tag, com.example.water, com.example.photo |
trails.example.org |
org.example.trails.grade |
example.app |
app.example.surface |
- Use a domain you own, or a new random UUID (version 4). The owner of the domain decides what names under it mean, so two organisations cannot choose the same ID by accident.
- IDs are compared exactly, letter case included.
com.example.Tagandcom.example.tagare two different types. Use lower case. - Keep an ID stable. A reader matches records by ID only. If you rename a type, files with the old ID become records of an unknown type.
- Version inside the record if you need to. VNX does not version record
types. If a type's fields will change, add a field such as
"v": 2, or use a new ID. - Do not use a domain you do not own, and do not use VNX's own words
without a domain (
tag,note). A reader does not validate the form, but the form is what prevents clashes.
Application keys
A top-level key whose name contains a full stop is an application key. It adds a kind of content that VNX does not define (§3.9).
{
"vnx": "0.11.0",
"networks": [],
"com.example.routes": {
"profiles": [{ "id": "dry", "avoid": ["com.example.bog"] }]
}
}
- An application key names an application's extension block, such as
app.viatrail.datatypesorcom.example.routes. The app's author chooses it, in reverse DNS: the full stop is how a reader tells it from a core key. - A data type ID (a record's
@type) is a different thing. It may be reverse DNS or a UUID. A type never needs its own application key: if an application defines its types in a file, the definitions go inside that application's own block. - The value can be any JSON value. It is opaque: a reader applies no VNX rule inside it.
- A reader keeps the key and its value unchanged through a read and a write. A
nullstaysnull, and an empty array stays empty. - A reader does not report an application key.
- Write each application key once only.
- Application keys exist at the top level only. On any other object that VNX defines, a key with a full stop is an unknown key, and the reader drops it and reports it. Inside a record body or an application key's value, a key with a full stop is ordinary data and is kept.
Choose a record when the information is about one item. Choose an application key when it is a new kind of thing, such as a catalogue of your data types or a set of rules that many items use.
Attachments in a VNZ archive
A .vnz archive can hold any files beside doc.vnx (§7). Put the files of each
data type in a folder named exactly after its type ID (§7.2):
doc.vnx
com.example.photo/3f2a9c.jpg
com.example.photo/77b01e.jpg
org.example.audio/ridge-notes.m4a
Then the record names its file by the full entry name:
{ "@type": "com.example.photo", "files": ["com.example.photo/3f2a9c.jpg"], "caption": "Summit cairn" }
- Two extensions in one archive then cannot have the same file name, because each uses its own folder.
- Files for an application key go in a folder named after the key.
- The folder name is a recommendation for writers. A reader does not interpret it. A reader returns every file in the archive as an attachment, and does not report a file that no record names.
- Do not decide what a file is from its extension. Your record says what it is.
What a reader does with extensions
| It finds | It does |
|---|---|
| a record of a type it knows | uses it |
| a record of a type it does not know | keeps it, writes it back unchanged, reports nothing |
a record with no usable @type |
drops that record and reports a diagnostic |
| an application key it knows | uses it |
| an application key it does not know | keeps it, writes it back unchanged, reports nothing |
| a dotted key on any other object that VNX defines (not inside a record body or an application key's value) | drops the key and reports a diagnostic |
a file in a .vnz that no record names |
returns it as an attachment, reports nothing |
An application can be stricter about its own namespace. For example, it can refuse a record under its own domain that its version does not know. That is the application's rule, not a VNX rule.
Document your extension
If other people will read or write your extension, publish:
- each type ID, its fields, their JSON types and meaning;
- which hosts each type is for (highlight, arc, point, and so on);
- whether a type can repeat on one item, and what several records mean;
- each application key and the shape of its value;
- the folder and file names your types use in a
.vnz; - a JSON Schema for your records, if you can.
Example VNX extensions
These are extensions that applications have published. They are examples of the mechanism on this page. They are not part of VNX, and a VNX reader does not need them.
- Viatrail extensions: the data types, application keys and photo attachments of the Viatrail app, with a JSON Schema.