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

Extensions

On this page
  1. Data records
  2. Type IDs
  3. Application keys
  4. Attachments in a VNZ archive
  5. What a reader does with extensions
  6. Document your extension
  7. Example VNX extensions

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

  1. data is 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.
  2. 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 called type.
  3. 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.
  4. 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

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

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"] }]
  }
}

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" }

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:

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.