← C++

C++ · 22 / 24

Safely migrate versioned JSON files

Load older files, add defined defaults and reject unknown formats without changing existing data.

  • Large
  • Advanced
  • 90 min

Prerequisites: Test failure-tolerant file operations, Error handling and the strong exception guarantee

In this tutorial
  1. Understand the old format
  2. Define the current format
  3. Validate structure and limits
  4. Run a visible migration
  5. Prove compatibility and rejection
  6. Add a filtered export
  7. Exercise and solution
  8. Project context and sources

Download learning package

Setup and verification

GCC with C++20, CMake 3.25 or later, CTest and Python 3. Qt 6.8 with Core, Widgets and Test. Set CMAKE_PREFIX_PATH to your Qt installation if it is not discovered automatically. Locally checked with Qt 6.8.3. Extract the ZIP into a new folder. python3 run_checks.py checks example and solution in a temporary copy and preserves your files. Run python3 verify.py for your own build. The demo is then available at build/order_lab. Qt demos use English labels. Automated widget tests default to offscreen. Run the visible demo in a desktop session without QT_QPA_PLATFORM=offscreen. Native Windows execution is not verified.

Verified on 2026-10-21 on Linux x86_64. V1-to-v2 migration, JSON round trips, invalid structure and versions, size limits, file errors and preservation of a valid file when data is rejected. The exercise checks filtered export. No crash-durability claim.

Saved files often outlive the program version that created them. The Order Lab format starts with ID and title. Version 2 adds priority and status. The decoder translates both versions into the current domain model, while the encoder only writes version 2. This independent teaching format is not the FactoryForge application's project format.

Package contents and individual files

01Understand the old format

Each file explicitly names its format and version. appfabrik-order-lab distinguishes these order lists from other JSON documents. Version 1 only knows id and title. Missing new properties are supplied by a documented migration rather than guessed arbitrarily.

fixtures/orders-v1.json · jsonOpen file
{
  "format": "appfabrik-order-lab",
  "version": 1,
  "orders": [
    {
      "id": 7,
      "title": "Legacy delivery"
    }
  ]
}
Expected result

The legacy order loads with priority 0 and status open.

02Define the current format

Version 2 additionally requires priority from 0 to 2 and status as open or done. A version number such as 1.5 is not a valid substitute for version 1. Unknown future versions are rejected. The decoder ignores extra fields within a known version but requires every mandatory field.

fixtures/orders-v2.json · jsonOpen file
{
  "format": "appfabrik-order-lab",
  "version": 2,
  "orders": [
    {
      "id": 10,
      "title": "Deliver motors",
      "priority": 2,
      "status": "open"
    }
  ]
}
Expected result

The format can be checked without access to a particular app installation.

03Validate structure and limits

decode limits documents to 256 KiB and lists to 1000 entries. It checks integers, types, statuses and unique IDs. A successful result is returned only after full validation. saveFile uses QSaveFile with direct-write fallback disabled. Invalid data is rejected before opening the destination file.

json_orders.hpp · cppOpen file
#pragma once
#include "order.hpp"
#include <QFile>
#include <QJsonArray>
#include <QJsonDocument>
#include <QJsonObject>
#include <QSaveFile>
#include <cmath>

namespace orders {
inline constexpr int maximumDocumentBytes = 262144;
inline bool integer(const QJsonValue &value, int minimum, int maximum) {
  if (!value.isDouble())
    return false;
  double number = value.toDouble();
  return std::isfinite(number) && std::floor(number) == number &&
         number >= minimum && number <= maximum;
}
inline Result<std::vector<Order>> decode(const QByteArray &bytes) {
  if (bytes.size() > maximumDocumentBytes)
    return Error{ErrorCode::invalid, "Document exceeds 256 KiB"};
  QJsonParseError parse;
  auto document = QJsonDocument::fromJson(bytes, &parse);
  if (parse.error != QJsonParseError::NoError || !document.isObject())
    return Error{ErrorCode::invalid, "Expected a JSON object"};
  auto root = document.object();
  if (root.value("format") != "appfabrik-order-lab" ||
      !integer(root.value("version"), 1, 2))
    return Error{ErrorCode::unsupported,
                 "Expected order-lab format version 1 or 2"};
  if (!root.value("orders").isArray() ||
      root.value("orders").toArray().size() > 1000)
    return Error{ErrorCode::invalid,
                 "Expected an array of at most 1000 orders"};
  std::vector<Order> result;
  for (const auto &value : root.value("orders").toArray()) {
    if (!value.isObject())
      return Error{ErrorCode::invalid, "Order must be an object"};
    auto object = value.toObject();
    if (!integer(object.value("id"), 1, 1000000) ||
        !object.value("title").isString())
      return Error{ErrorCode::invalid, "Invalid ID or title"};
    Order order{object.value("id").toInt(),
                object.value("title").toString().toStdString()};
    if (root.value("version").toInt() == 2) {
      if (!integer(object.value("priority"), 0, 2) ||
          (object.value("status") != "open" &&
           object.value("status") != "done"))
        return Error{ErrorCode::invalid, "Invalid priority or status"};
      order.priority = object.value("priority").toInt();
      order.status =
          object.value("status") == "done" ? Status::done : Status::open;
    }
    result.push_back(std::move(order));
  }
  auto valid = validateBatch(result);
  if (!succeeded(valid))
    return std::get<Error>(valid);
  return result;
}
inline Result<QByteArray> encode(std::span<const Order> batch) {
  auto valid = validateBatch(batch);
  if (!succeeded(valid))
    return std::get<Error>(valid);
  QJsonArray items;
  for (const auto &order : batch)
    items.append(QJsonObject{
        {"id", order.id},
        {"title", QString::fromStdString(order.title)},
        {"priority", order.priority},
        {"status", order.status == Status::open ? "open" : "done"}});
  auto bytes = QJsonDocument(QJsonObject{{"format", "appfabrik-order-lab"},
                                         {"version", 2},
                                         {"orders", items}})
                   .toJson(QJsonDocument::Compact);
  if (bytes.size() > maximumDocumentBytes)
    return Error{ErrorCode::invalid, "Encoded document exceeds 256 KiB"};
  return bytes;
}
inline Result<std::vector<Order>> loadFile(const QString &path) {
  QFile file(path);
  if (!file.open(QIODevice::ReadOnly))
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  auto bytes = file.read(maximumDocumentBytes + 1);
  if (file.error() != QFileDevice::NoError)
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  return decode(bytes);
}
inline Result<Done> saveFile(const QString &path,
                             std::span<const Order> batch) {
  auto encoded = encode(batch);
  if (!succeeded(encoded))
    return std::get<Error>(encoded);
  const auto &bytes = std::get<QByteArray>(encoded);
  QSaveFile file(path);
  file.setDirectWriteFallback(false);
  if (!file.open(QIODevice::WriteOnly) || file.write(bytes) != bytes.size() ||
      !file.commit())
    return Error{ErrorCode::storage, file.errorString().toStdString()};
  return Done{};
}
} // namespace orders
Expected result

A rejected save does not replace an existing valid file.

04Run a visible migration

Run ./build/order_lab after python3 verify.py. The program loads an embedded v1 order and writes it through the current encoder. It changes no original file. Compare the output with orders-v2.json and identify the two added properties.

main.cpp · cppOpen file
#include "json_orders.hpp"
#include <iostream>
int main() {
  auto migrated = orders::decode(
      R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"Legacy order"}]})");
  if (!orders::succeeded(migrated))
    return 1;
  auto encoded = orders::encode(std::get<std::vector<orders::Order>>(migrated));
  if (!orders::succeeded(encoded))
    return 1;
  std::cout << std::get<QByteArray>(encoded).toStdString() << '\n';
}
Expected result

The output contains version 2, priority 0 and status open.

05Prove compatibility and rejection

Tests cover v1 migration, a v2 round trip and the existing file after an invalid save request. Negative cases include malformed JSON, the wrong root type, unknown or fractional versions, duplicate IDs, missing v2 fields and oversized input. These checks do not claim power-loss safety.

tests.cpp · cppOpen file
#include "json_orders.hpp"
#include "test_support.hpp"
#include <QTemporaryDir>
#include <QtTest>
using namespace orders;
class FileTests : public QObject {
  Q_OBJECT
private slots:
  void migrationAndRoundTrip() {
    auto migrated = decode(
        R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":7,"title":"Legacy"}]})");
    QVERIFY(succeeded(migrated));
    auto batch = std::get<std::vector<Order>>(migrated);
    QCOMPARE(batch[0].priority, 0);
    QCOMPARE(batch[0].status, Status::open);
    auto encoded = encode(batch);
    QVERIFY(succeeded(encoded));
    QVERIFY(std::get<QByteArray>(encoded).contains("\"version\":2"));
    QVERIFY(std::get<std::vector<Order>>(
                decode(std::get<QByteArray>(encoded))) == batch);
    QTemporaryDir directory;
    auto path = directory.filePath("orders.json");
    QVERIFY(succeeded(saveFile(path, samples())));
    QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
    auto invalid = samples();
    invalid[0].title.clear();
    QVERIFY(!succeeded(saveFile(path, invalid)));
    QVERIFY(std::get<std::vector<Order>>(loadFile(path)) == samples());
    QVERIFY(
        !succeeded(saveFile(directory.filePath("missing/file.json"), batch)));
    QVERIFY(!succeeded(loadFile(directory.filePath("absent.json"))));
  }
  void malformed_data() {
    QTest::addColumn<QByteArray>("input");
    QTest::newRow("syntax") << QByteArray("{");
    QTest::newRow("root") << QByteArray("[]");
    QTest::newRow("unknown") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":3,"orders":[]})");
    QTest::newRow("fraction") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":1.5,"orders":[]})");
    QTest::newRow("wrong-format")
        << QByteArray(R"({"format":"factory-forge","version":1,"orders":[]})");
    QTest::newRow("duplicate") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":1,"orders":[{"id":1,"title":"A"},{"id":1,"title":"B"}]})");
    QTest::newRow("missing-fields") << QByteArray(
        R"({"format":"appfabrik-order-lab","version":2,"orders":[{"id":1,"title":"A"}]})");
    QTest::newRow("oversized") << QByteArray(maximumDocumentBytes + 1, ' ');
  }
  void malformed() {
    QFETCH(QByteArray, input);
    QVERIFY(!succeeded(decode(input)));
  }
};
QTEST_GUILESS_MAIN(FileTests)
#include "tests.moc"
Expected result

Valid legacy files migrate successfully. Every negative case returns an error.

06Add a filtered export

encodeOpen constructs a new list containing only open orders and then uses the regular encoder. The same format and validation rules apply. The original batch remains untouched. The solution decodes the export again rather than merely searching for a text fragment in its output.

solution.cpp · cppOpen file
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
  std::vector<orders::Order> open;
  std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
    return order.status == orders::Status::open;
  });
  return orders::encode(open);
}
int main() {
  const auto original = samples();
  auto result = encodeOpen(original);
  require(orders::succeeded(result), "encode");
  auto decoded = orders::decode(std::get<QByteArray>(result));
  require(orders::succeeded(decoded), "decode exported file");
  require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
          "only open exported");
  require(original == samples(), "source unchanged");
  require(std::get<QByteArray>(result).contains("\"version\":2"),
          "current version");
  require(orders::succeeded(encodeOpen({})), "empty export");
}
Expected result

The export contains two open orders in the current format.

Your exercise

Write encodeOpen. Export only open orders as version 2 without changing the source list. Check decoded output and an empty export.

Show the solution and explanation

The solution filters into an owning vector and calls encode. Tests check two open orders, version 2, unchanged original data and a valid empty export.

solution.cpp · cppOpen file
#include "json_orders.hpp"
#include "test_support.hpp"
orders::Result<QByteArray> encodeOpen(std::span<const orders::Order> values) {
  std::vector<orders::Order> open;
  std::ranges::copy_if(values, std::back_inserter(open), [](const auto &order) {
    return order.status == orders::Status::open;
  });
  return orders::encode(open);
}
int main() {
  const auto original = samples();
  auto result = encodeOpen(original);
  require(orders::succeeded(result), "encode");
  auto decoded = orders::decode(std::get<QByteArray>(result));
  require(orders::succeeded(decoded), "decode exported file");
  require(std::get<std::vector<orders::Order>>(decoded).size() == 2,
          "only open exported");
  require(original == samples(), "source unchanged");
  require(std::get<QByteArray>(result).contains("\"version\":2"),
          "current version");
  require(orders::succeeded(encodeOpen({})), "empty export");
}

Project context and sources

Independent teaching project using FactoryForge's logistics theme. The existing FactoryForge source revision provides architectural context. SQLite, networking and import features introduced here belong to the teaching project. Order Lab JSON is a separate format.