← All Articles

The NXL Format: Open Specification for a Human-Readable Notebook File

IWV Digital Solutions LLC

By IWV Digital Solutions — May 2026

---

NotesXML stores every notebook as a .nxl file — a single, self-contained, XML-based document that holds the entire notebook including all its pages, notes, images, and attachments. It is human-readable. It opens in any text editor. It can be parsed by any standard XML library on any platform.

Today, we are publishing the complete NXL Format Specification v2.6 as an open document under a Creative Commons Attribution 4.0 license. Anyone — individual developers, other software projects, integrators, archivists — can read it, implement it, build tools around it, and write content into .nxl files that NotesXML will read.

---

Why an Open Format Matters

When you put effort into a notebook — meeting minutes, research, journal entries, sketches, recipes, code — the question that should never trouble you is whether you can still read it five years from now. Most note-taking applications answer that question with a proprietary binary format and a service you have to keep paying for, or a SQLite database you can pry open but not really use because the schema is undocumented.

NotesXML answers it differently. Every NotesXML notebook is an .nxl file on your device. The format is XML, the schema is published, and the application is local-first by design. If NotesXML disappeared tomorrow, your notebooks would still be readable with any text editor and recoverable with a 20-line script in any programming language that has an XML parser. That guarantee is binding on us — it’s codified in our Software Requirements Specification as DC-006: NXL Format Openness, and the published specification you can download above is what makes the guarantee real.

What’s in the Format

An .nxl file is a single XML document with a <notebook> root element. Inside, it contains everything a notebook needs:

• Pages — ordered collections of notes. A notebook has one or more pages; each page has a title and metadata.
• Notes — the content. Each note has a type (one of 22 supported types: rich text, plain text, code, audio, image, PDF, video, drawing, checklist, list, table, calendar, link, file attachment, contact, quote, divider, and several specialized widget types), an ID, a timestamp, and type-specific content.
• Media — images, audio recordings, PDFs, file attachments. Stored Base64-inline in the same XML file, so an .nxl is genuinely self-contained — you can email a notebook to yourself and it carries every embedded photo and audio clip with it.
• Belongings — an ordering element that says which notes belong to which page and in what order. This lets the same note be referenced from multiple pages if needed, without duplicating storage.
• Sort order persistence — per-notebook and per-page sort preferences are saved alongside the data, so the way you organized a notebook on your laptop is the way it opens on your phone.

Each note’s type-specific data — the cells of a table, the steps of a checklist, the events of a calendar — is stored as JSON inside the XML element. This keeps the schema flexible (we can add new note types without breaking old files) while keeping the parsing simple (any consumer can pick out the parts it understands and ignore the parts it doesn’t).

The Specification Is Big Because Notebooks Are Real

The published v2.6 specification is 1,813 lines. That length isn’t accidental complexity — it’s what an honest open spec for a real notebook format requires. The document covers:

• The complete XML schema with worked examples for every element.
• Each of the 22 supported note types, with its full data schema and reference examples.
• Encoding, ID, timestamp, and size constraints.
• Sort order persistence rules across notebook, page, and note scopes.
• File location conventions across Android, Linux desktop, and Windows desktop.
• Import/export mappings for ENEX (Evernote), Markdown, and Backpack XML.
• Platform-specific considerations for WebView, Electron, and browser environments.
• Validation requirements (well-formedness, content integrity, JSON conformance).
• A JavaScript data model reference for implementors who want to mirror our internal representation.
• A migration history covering every schema change from v1.0 (2024) to v2.6 (2026), so old files always remain readable.
• A reference text-extraction algorithm for external consumers (search indexing, AI/LLM context, summarization).
• An External Writer Protocol that defines exactly how other applications can write into .nxl notebooks safely, including the inbox sidecar pattern for cooperating with a notebook that’s open in NotesXML.
• A Per-Notebook Lock File Protocol that prevents corruption when multiple applications might touch the same notebook concurrently.

What This Means for Users

Your notebooks are portable, durable, and recoverable. Three concrete consequences:

You can read your notebooks without NotesXML. Open an .nxl file in any text editor and you’ll see well-formed XML with your titles, notes, and content visible. Base64-encoded media looks like a long string of letters, but the structure around it — what each piece is, what page it belongs to, when it was created — is plain text.

You can recover your data from a 20-line script. Any programming language with an XML parser (Python, JavaScript, Java, C#, Go, Rust, Ruby, PHP, anything) can iterate over the notes in an .nxl file and extract text content with very little code. The text-extraction algorithm in Section 17 of the specification gives you the canonical recipe.

You don’t need to fear lock-in. If a better notebook application comes along tomorrow, you can migrate your data. If NotesXML stops being supported, you can write your own reader or use someone else’s. The format is not a moat — it’s a contract.

What This Means for Developers

The specification is published so that developers can build with it. Here are the concrete things you can do:

Write a reader. Build a tool that converts .nxl files to PDF, HTML, Word, plain text, or any other format you need. The spec gives you everything you need to enumerate every note in a notebook and extract its content.

Write a converter. Build a tool that converts into .nxl — from Markdown directories, from Evernote exports, from Notion exports, from OneNote dumps. Once your data is in .nxl, NotesXML will read it on any platform.

Write a backup / archive tool. .nxl files are self-contained — an archive that captures the file captures everything. Build content-addressed storage, deduplication, full-text indexing across many notebooks, whatever you need.

Build an integration. Your own application can generate notes for a user’s NotesXML notebook. The External Writer Protocol (Section 18) and the Inbox Sidecar Pattern (Section 18.9) define exactly how to do this safely — even when NotesXML is running and has the notebook open. Use the optional creator attribute to mark notes your tool generated, and they will survive round-trips through NotesXML untouched.

Coexist with NotesXML cleanly. The Per-Notebook Lock File Protocol (Section 16) defines a small JSON lock file that prevents corruption when multiple applications might touch the same notebook. Honour it, and your tool can run alongside NotesXML without risk.

Implement an alternative client. Nothing in the format ties it to NotesXML. The format is general enough that you could build a different notebook application that uses .nxl as its native file format. Compatibility with NotesXML would be a free side effect.

The License

The specification is published under Creative Commons Attribution 4.0 International (CC BY 4.0). In plain English:

• You can share the specification — copy, redistribute, host on your own site.
• You can adapt the specification — build on it, derive from it, write your own derivative spec.
• You can use it for any purpose, including commercial software products.
• The only requirement is attribution — credit IWV Digital Solutions LLC and link back to the original specification.

The format itself — the schema, the element names, the data model — is not patent-encumbered. You don’t need a license to read or write .nxl files. The CC BY license covers only the specification document; the format described by the document is open in the practical sense.

Versioning and Backward Compatibility

The format has a published version number visible at the start of every .nxl file (the version attribute on the <notebook> root element). The current shipping format is v2.x; the current published specification is v2.6.

Our commitment on backward compatibility is straightforward: a v2.0 file is still readable today, and will still be readable when the format reaches v3.0. The migration history table in Section 19 of the specification documents every schema change since v1.0 (January 2024) and the rationale for each. Where the format has changed, the spec describes how legacy files are interpreted — for example, the Calendar v1 to v2 schema migration in Section 15.4, or the removed-note-types handling in Section 15.5.

If we make a breaking change in the future, we will publish v3.0 of the specification ahead of releasing software that depends on it, and the v2.x format will continue to be supported as a read path indefinitely.

What’s Next

We’re publishing this specification now, ahead of NotesXML’s commercial release, because the open format is a foundational commitment, not an afterthought. The specification will evolve as the application does — new note types, new optimizations, new ecosystem features — and every revision will be published the same way: same license, same download URL pattern, with the migration history fully preserved.

If you build something that reads or writes .nxl files, we’d love to hear about it. Drop us a line at hello@iwvdigitalsolutions.com or open a discussion on our support page. We don’t maintain a formal third-party-tools directory yet, but if there’s a community of .nxl implementors building useful things, we’ll start one.

---

---

NotesXML is developed by IWV Digital Solutions LLC. Learn more at iwvdigitalsolutions.com.

---