Preserve What You Don’t Understand

Content portability you can verify, not just promise. Publishing the open spec was one commitment; the harder one is making our own tool honor it on files we didn’t write.

June 3, 2026 — By Brent Miller

Everyone has met the small version of this problem. You open a file someone sent you in a different program from the one they used, change a line, save it, and send it back — and somewhere in that round trip, something you couldn’t see on screen quietly vanished. A field the receiving program had no box for, so it threw away. In learning content the small problem becomes a serious one: the accessibility metadata a colleague spent an afternoon on, gone; the unfamiliar question types in a course you’ve imported, silently dropped on the way back out. Whether you teach, build EdTech, or run a platform that promises portability, that’s the failure mode an open content specification has to prevent.

Last week the LC-JSON (Learning Content JSON) specification reached its first public release candidate. With the EdTech standards world gathered at 1EdTech’s conference this week, it feels like the right moment to write about what an open specification is actually for, beyond the document itself. Most of those 200-odd pages and JSON Schemas describe what the format covers and how each piece must be shaped. But one rule, within that body of work, is harder to test and easier to fail quietly than the rest: a conforming tool must preserve what it does not understand. It is the clause that protects the parts of a file Lesson Commons doesn’t understand — and this past week we made our own editor keep it.

What the spec is — and what it isn’t

LC-JSON is an open specification published at lc-json.org under Apache 2.0, with its schemas, examples, and conformance tests in a public repository. It describes a plain-text JSON file format for the things educators actually author: courses, lessons, exercises, quizzes, questions, learning objectives, accessibility metadata. It belongs to no vendor; its governance is independent of any single implementer; and it can be checked by anyone, against published rules, with an off-the-shelf validator.

Lesson Commons is our product — an editor and a delivery platform. It is also the first implementation of LC-JSON, and the reference one. “Reference implementation” is not a privilege; it is an obligation — we are the first tool held to the standard in public, the first that can be caught failing it. A format you can only trust because you trust the vendor is just a vendor's database with extra steps.

This is the oldest idea in the interoperable parts of computing. The web works in any browser because the W3C publishes specifications and browsers conform. Email crosses vendors because the IETF publishes the protocols. A learning tool from one vendor launches inside an LMS from another, and passes grades back, because 1EdTech publishes LTI. None of those standards are interesting because of their page count — they are interesting because you can hold a product you didn’t build to a rule you can read. LC-JSON applies that model to a layer the others were never meant to cover: the structured content itself — as a teacher understands it, and readable for teachers by design.

Anyone can write a file. The test is reading one.

A spec asks two different things of two different roles:

A producer writes files. To conform, the files it emits have to be in the shape the spec describes — structurally correct, no missing or invalid fields. The easy half, and the one Lesson Commons cleared first.
A consumer reads files — including ones made by tools that don’t exist yet. To conform, it has to read them, let a person work with them, write them back out, and not lose anything on the way through. The hard half.

The hard half is hard because of how editing software is usually built. Our Editor doesn’t keep your course as raw text. When it reads a file, it unpacks each piece into a known slot — this is a course title, this is a question prompt, this is a hint — and shows you a tidy interface built around the slots it knows. That structure (engineers call it a “typed model”) is what makes a good editor pleasant. It is also what makes it dangerous to a stranger’s file: when the reader meets a piece it has no slot for, the default behaviour is to silently throw it away. Out of sight on import, gone on export.

The specification names three kinds of data a conforming consumer must not discard — exactly what a typed editor is most likely to drop:

Fields from a future version of the format that this build is too old to know about. Tomorrow’s optional field must survive today’s editor.
Vendor extensions — extra data another tool hangs on a question to support its own features, clearly labelled with that tool’s name so we can tell whose it is (engineers call this “namespaced”). Not ours to understand; not ours to delete.
Question types we don’t implement yet — the format reserves room for kinds (image hotspots, drag-and-associate, others) our Editor can’t render. A teacher who imports a course full of them, fixes a typo in lesson three, and exports should get those questions back intact — not a course with holes where they used to be.

The careful translator

The behaviour the spec is asking for has a good human analogue: the careful translator. Hitting a proper name or technical term they don’t recognise, a careful translator does not guess and does not delete. They carry the word across untouched, so that the next reader — who may know exactly what it means — still has it. That restraint is the skill.

That is the discipline we built into the Editor this past week. When it now reads an LC-JSON file, every field it doesn’t recognise is set aside — kept with the question or lesson it belongs to, carried through the database, and written back out untouched on export. The reserved question types it can’t draw on screen are preserved whole. You can open a course made in a tool we’ve never heard of, change the parts we do understand, and the parts we don’t come back exactly as they arrived.

A note for the people who’ll ask the sharp question

Anyone who has implemented a preservation rule will ask the awkward question: “preserve” cannot honestly mean byte-for-byte identical. JSON, by its own definition (RFC 8259), does not promise that the keys in an object come back in the order they went in. So the obligation is semantic preservation: every member, every value, every nested structure that went in must come back out, intact and in the right place, even if the bytes are reshuffled. The release candidate published last week tightened exactly this wording — and the project ships a conformance corpus and reference validator, so “does this tool really preserve what it should?” is a question with a machine-checkable answer, not a marketing claim.

Why a teacher should care that we did this

None of this asks anything of you as a teacher. You will never see a vendor extension or a reserved question type, and you shouldn’t have to. Here is what it buys you.

A course is not a hostage. A colleague can build something in one tool and hand it to you in another, and the handoff doesn’t quietly cost you what neither of you was looking at. When you move your materials to a new tool, a new school, a new platform years from now, the move is not a slow leak that costs a little each time. The whole anxiety behind the eighty questions I lost on an old hard drive was that every tool I ever used treated my content as something to be consumed and forgotten. A format whose tools are required to hand your work back whole — including the parts they don’t understand — reverses that.

The distance is the point

It would be easy to tell this story as “our editor got a nice new feature.” The feature is real, but it isn’t the news. The news is that it exists to satisfy a rule we wrote, published, and gave up the right to bend — a rule with a validator anyone can run against us. The gap between the product we sell and the standard we conform to is the only thing that makes “your content is portable” a claim you have any reason to believe coming from a vendor.

If you build EdTech, the invitation is open: the specification, schemas, conformance corpus, and reference validator are all public at lc-json.org and on GitHub. Implement against it. Tell us where it’s wrong — the 1.0 release is being cut at the end of this month. And if your tool reads LC-JSON, read a stranger’s file, hand it back, and check what survived. That, far more than any page of documentation, is what an open content specification is for.

Lesson Commons is an educational software platform for teachers and trainers. The Editor, Learn platform, and the LC-JSON open format are in active development. LC-JSON is an independent open specification (Apache 2.0) published at lc-json.org; Lesson Commons is its first and reference implementation. Follow updates at lessoncommons.com/news.

This article was written with the assistance of Claude (Anthropic). The author defined the purpose, audience, and main ideas, directed the editorial approach, and edited the final text. Claude assisted with structure and drafting.