Practical course authoring
What makes a course-content JSON export genuinely portable?
The fields, guarantees and validation a course-content JSON export needs to remain useful outside its original authoring tool.
Written by Martin Kruger · Updated 19 July 2026
Direct answer
A portable course export preserves the full hierarchy, stable identifiers, ordering, content, format version and enough metadata to validate or migrate the file. It should be readable without the original database and import as a new copy without damaging the source.
Portability is more than a download button
A file is not portable merely because it is JSON. Portability means another tool—or a future version of the same tool—can determine what every object represents, where it belongs, what order it has and how its prose is encoded.
The export should describe the programme as a complete document rather than leak database tables or require undocumented server state.
Preserve these minimum facts
A robust export carries an explicit schema version and one root programme. Every hierarchy item needs a type, title, content body, position and stable identifier. Parent-child relationships must be unambiguous, and the character encoding and content format should be known.
- Schema version and export timestamp
- Programme metadata and all descendant items
- Stable IDs, item types, parent relationships and ordering
- Markdown source rather than presentation-only HTML
- Optional provenance fields that do not expose secrets
Validate before accepting an import
Import should reject unknown major versions, duplicate identifiers, cycles, illegal upward nesting and malformed content before writing anything. Validation should report a useful path to the failing item. A partial import that silently drops content is worse than a clear rejection.
Importing as a fresh copy is usually safer than overwriting an existing programme. It preserves the source, avoids identifier collisions and gives the creator a visible comparison point.
How to test an export
Create a small programme that deliberately skips one level, includes Markdown at every level, uses non-ASCII text and contains sibling items with a meaningful order. Export it, inspect the file without the application, import it as a copy, then compare titles, bodies, parentage and order. That round trip is the practical portability test.