STORAGE FORMAT

VxJSON

Conloca's git-friendly content storage format. Standard JSON with content-last field ordering for fast metadata indexing and deterministic ETags.

What is VxJSON?

VxJSON is standard JSON with a .vxjson extension and two guarantees: the content field is always last, and field order is deterministic. That is it. No special parser needed -- any JSON reader can open a VXJSON file.

home.vxjson
{
  // Metadata -- fits in first 4KB
  "id": "abc123",
  "type": "puck",
  "created": "2026-01-15T10:00:00Z",
  "modified": "2026-01-20T14:30:00Z",
  "meta": {
    "title": "About Us",
    "description": "Learn about our team"
  },

  // Content payload -- always last
  "content": {
    "puckData": { ... }
  }
}

Why Content-Last?

By placing the content field last, all metadata fits within the first 4KB of every file. This unlocks two performance advantages.

4K

4KB Index Reads

The system can index thousands of pages by reading only the first 4KB of each file. Metadata like title, dates, and ETags are always there -- no need to parse the full content payload.
→

Independent ETags

The dual metaEtag.contentEtag format lets the system detect staleness for metadata and content independently -- critical for content inheritance across locales.

Crash-Safe Writes

Every file write in Conloca uses an atomic write strategy. Content is written to a temporary file first, then atomically renamed to the target path. This is a Conloca runtime feature -- independent of the VxJSON format -- ensuring the original file is never corrupted if the process crashes mid-write.

1

Write to temp file

Content is written to a temporary file with a unique name: {path}.tmp.{pid}.{hrtime}
2

Atomic rename

rename() replaces the target file in a single operation. On POSIX systems, this is guaranteed atomic -- the file is either fully old or fully new.
3

Crash recovery

If the process crashes during step 1, only the temp file is left behind -- the original is untouched. If it crashes during step 2, the rename either completed or it didn't. No half-written files, ever.

ETag Concurrency

Every VXJSON file carries a dual-format ETag that prevents stale overwrites when multiple editors work simultaneously. The format is:

metaEtag.contentEtag   // e.g. a3f2c1.b7e4d9

When an editor saves, the CMS sends the expected ETag. If the file was modified since it was loaded, the server rejects the write with a STALE_WRITE error and presents a conflict resolution dialog. No content is silently overwritten.

See it in action

Get started with Conloca and see how VxJSON keeps your content safe, versioned, and git-friendly.

Get StartedBack to Home