{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://vnx.tools/schema/vnx-0.11.schema.json",
  "title": "VNX 0.11",
  "description": "Structural schema for a VNX 0.11 document. A JSON Schema can check shape only, and several of this format's rules are not about shape (walk connectivity, for example), so validate with a VNX reader as well. It is deliberately permissive about unknown keys, because spec §6.2 makes an unknown key a reader DIAGNOSTIC and keeps the item — a schema that refused them would disagree with every conforming reader.",
  "type": "object",
  "required": [
    "vnx"
  ],
  "properties": {
    "vnx": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "The specification version, MAJOR.MINOR.PATCH. All three components are required: the two-component spelling is refused, not coerced. Whether a reader can READ this version is reader-relative and outside a schema's reach. THIS FILE IS NAMED FOR THE MINOR SERIES and covers every patch of it, because a patch bump is additive by definition (spec §2.2); a new minor gets a new schema file."
    },
    "folders": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/folder"
      }
    },
    "points": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/point"
      }
    },
    "areas": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/area"
      }
    },
    "tracks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/track"
      }
    },
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/plan"
      }
    },
    "networks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/network"
      }
    }
  },
  "patternProperties": {
    "\\.": {
      "description": "An application key (spec §3.9): a top-level key containing a full stop, named in reverse-DNS form by the owner of the domain. Its value is any JSON value, carried VERBATIM and never interpreted, so this schema constrains nothing about it. The rule is top-level only: on any other object a dotted key is an unrecognised key, which a reader diagnoses."
    }
  },
  "$defs": {
    "timestamp": {
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$",
      "description": "ISO 8601, UTC, Z suffix, optional fractional seconds — and nothing else (spec §4.3)."
    },
    "identifier": {
      "type": "string",
      "minLength": 1,
      "description": "Container-scoped and document-local. A plan's node-1 and a network's node-1 are DIFFERENT nodes; a reader that builds one global map merges them. That rule is about scope, not shape, so nothing here can enforce it."
    },
    "position": {
      "type": "array",
      "minItems": 2,
      "description": "Fixed positional channels: [lon, lat, ele, time_ms]. From index 2, null means ABSENT — a first-class state, not a zero. Channels beyond index 3 are ignored rather than refused, so a fifth channel can be added later without breaking readers. ⚠ Nothing here can catch a lon/lat transposition: both orderings are numbers, both are in range, and the point lands 8000 km away with this schema still green. Check one point on a map.",
      "prefixItems": [
        {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        {
          "type": [
            "number",
            "null"
          ]
        },
        {
          "type": [
            "number",
            "null"
          ]
        }
      ],
      "items": true
    },
    "record": {
      "type": "object",
      "required": [
        "@type"
      ],
      "description": "One element of a `data` bag (spec §5). Apart from @type the body is OPAQUE and must stay so: an unknown type is inert on any host, and its fields survive read-modify-write at value level. A schema that constrained the body would break exactly the extensibility the bag exists for.",
      "properties": {
        "@type": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/record"
      }
    },
    "folder": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/identifier"
        },
        "name": {
          "type": "string"
        },
        "parent": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        }
      }
    },
    "ring": {
      "type": "array",
      "minItems": 3,
      "items": {
        "$ref": "#/$defs/position"
      },
      "description": "ONE open ring (spec §3.7): at least three positions, the last NOT repeating the first; the boundary runs from the last back to the first. That the ring is open, and that three of its positions are distinct, are relationships between values, which JSON Schema cannot state; the reader checks them. Nested rings ARE caught here, because a ring element must be a position and a position's first element must be a number."
    },
    "point": {
      "type": "object",
      "required": [
        "at"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "folder": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "at": {
          "$ref": "#/$defs/position"
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "area": {
      "type": "object",
      "required": [
        "polygon"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "folder": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "polygon": {
          "$ref": "#/$defs/ring"
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "segment": {
      "type": "object",
      "required": [
        "pips"
      ],
      "description": "A segment boundary is a PAUSE, not chunking. The gap between two segments is not geometry and not walking — a reader that joins them draws a line nobody walked and counts time nobody spent moving.",
      "properties": {
        "pips": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/position"
          }
        }
      }
    },
    "track": {
      "type": "object",
      "required": [
        "segments"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "folder": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "started": {
          "$ref": "#/$defs/timestamp"
        },
        "ended": {
          "$ref": "#/$defs/timestamp"
        },
        "segments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/segment"
          }
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "plan": {
      "type": "object",
      "required": [
        "walk"
      ],
      "description": "A top-level plan owns its graph (spec §3.4): `nodes` and `arcs` shaped as a network's, and one `walk` shaped as a highlight's. Its walk runs node to node: no position, no `turn`, no `pin`. The schema states that last rule for the walk's own keys; which nodes and arcs it names is beyond it.",
      "properties": {
        "name": {
          "type": "string"
        },
        "folder": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "nodes": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/identifier"
          },
          "additionalProperties": {
            "$ref": "#/$defs/nodePosition"
          },
          "description": "⚠ Two entries with the SAME key resolve last-wins in every mainstream parser, before this schema ever runs, so a node vanishes and nothing anywhere can say so (spec §6.4). No validator can detect this."
        },
        "arcs": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/identifier"
          },
          "additionalProperties": {
            "$ref": "#/$defs/namedArc"
          }
        },
        "walk": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/planPass"
          }
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "namedArc": {
      "type": "object",
      "required": [
        "from",
        "to",
        "pips"
      ],
      "description": "An arc inside a network or a plan, referenced by key from a walk. Its `pips` are the INTERIOR points of its line only, and may be empty: the line runs from the `from` node's position through the pips to the `to` node's. That `from` and `to` differ (no self-loop) and that both name nodes of the same owner are relationships no schema can verify.",
      "properties": {
        "from": {
          "$ref": "#/$defs/identifier"
        },
        "to": {
          "$ref": "#/$defs/identifier"
        },
        "pips": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/nodePosition"
          }
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "endpoint": {
      "description": "Either a node key or a position on the pass's arc. Which of the two it is, whether the node exists, and whether it is an end of the arc are all beyond a schema.",
      "anyOf": [
        {
          "$ref": "#/$defs/identifier"
        },
        {
          "$ref": "#/$defs/walkPosition"
        }
      ]
    },
    "highlight": {
      "type": "object",
      "description": "SPEC 3.3.3: a lightweight container for data objects along a walk of its network's arcs. It has an optional name, and no notes of its own.",
      "required": [
        "walk"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "walk": {
          "$ref": "#/$defs/walk"
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "networkPoint": {
      "type": "object",
      "required": [
        "at"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "at": {
          "$ref": "#/$defs/position"
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "network": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "folder": {
          "$ref": "#/$defs/identifier"
        },
        "hidden": {
          "type": "boolean"
        },
        "pinned": {
          "$ref": "#/$defs/timestamp",
          "description": "SPEC 3.8: the time the user pinned the item. Absent means not pinned. A folder carries no `pinned`."
        },
        "nodes": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/identifier"
          },
          "additionalProperties": {
            "$ref": "#/$defs/nodePosition"
          },
          "description": "⚠ Two entries with the SAME key resolve last-wins in every mainstream parser, before this schema ever runs, so a node vanishes and nothing anywhere can say so (spec §6.4). No validator can detect this."
        },
        "arcs": {
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/identifier"
          },
          "additionalProperties": {
            "$ref": "#/$defs/namedArc"
          }
        },
        "highlights": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/highlight"
          }
        },
        "points": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/networkPoint"
          }
        },
        "areas": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/area"
          }
        },
        "data": {
          "$ref": "#/$defs/data"
        }
      }
    },
    "nodePosition": {
      "type": "array",
      "minItems": 2,
      "description": "A node or an arc pip (spec §3.3.1, §3.3.2): [lon, lat] or [lon, lat, ele]. The time channel is absent or null; a reader drops a time it meets, with a diagnostic, and a document carrying one is not this shape. Channels beyond index 3 are ignored, as for every position.",
      "prefixItems": [
        {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        {
          "type": [
            "number",
            "null"
          ]
        },
        {
          "type": "null"
        }
      ],
      "items": true
    },
    "walkPosition": {
      "type": "array",
      "minItems": 2,
      "description": "A `from`, `to`, `turn` or `pin` position (spec §3.3.3): [lon, lat] only. Elevation comes from the arc's line. Whether it lies anywhere near its arc does not matter: it identifies the nearest point, at any distance.",
      "prefixItems": [
        {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        {
          "type": "null"
        },
        {
          "type": "null"
        }
      ],
      "items": true
    },
    "pass": {
      "type": "object",
      "required": [
        "arc"
      ],
      "description": "One pass of a walk (spec §3.3.3). Where `from` and `to` may appear, whether the walk is connected, and that `turn` and `pin` do not appear together are all rules over several values, which the reader checks.",
      "properties": {
        "arc": {
          "$ref": "#/$defs/identifier"
        },
        "from": {
          "$ref": "#/$defs/endpoint"
        },
        "to": {
          "$ref": "#/$defs/endpoint"
        },
        "turn": {
          "$ref": "#/$defs/walkPosition"
        },
        "pin": {
          "$ref": "#/$defs/walkPosition"
        }
      }
    },
    "walk": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/pass"
      }
    },
    "planPass": {
      "type": "object",
      "required": [
        "arc"
      ],
      "description": "A pass in a plan's walk: `from` and `to` are node keys only, and there is no `turn` or `pin`. A reader that meets one drops the plan (spec §6.2); the schema reports the shape as invalid.",
      "properties": {
        "arc": {
          "$ref": "#/$defs/identifier"
        },
        "from": {
          "$ref": "#/$defs/identifier"
        },
        "to": {
          "$ref": "#/$defs/identifier"
        },
        "turn": false,
        "pin": false
      }
    }
  }
}
