Design a compatibility matrix

1325. Lesson identity

Module

3.13 — Schema and build versioning

Lesson

2 of the module

Academic type

Guided Build

Schema type

Practical

Estimated time

45–60 minutes

Purpose

Make version assumptions explicit.

Primary concept

Schema stamps, build stamps, operation direction, and supported combinations.

1326. Learning objective

After this lesson, you can produce a compatibility matrix that maps source schemas, target or output schemas, build stamps, and operations to explicit support decisions. You can also define a round-trip invariant and write a diagnostic plan for an unsupported or unknown combination.

1327. Why this matters

A version label is useful only when a team can act on it. A schema stamp identifies the data shape and interpretation rules involved; a build stamp identifies the executable behavior involved. A compatibility matrix turns those identities into an explicit support policy.

Migration and round-trip checks need more than a source schema. A migration must name its target schema, while a round-trip must state its sequence and what must remain unchanged. Without those details, a matrix can appear precise while leaving the most consequential transformation assumptions unstated.

1328. Prior knowledge

You should have completed Version identity has more than one meaning in Module 3.13. You should be able to distinguish a schema version from a build version and explain why one build may read a record that another rejects. Use only a small fictional or local data format whose assumptions you can verify.

1329. Core concept

Compatibility is a property of a specific schema/build/operation combination, including the operation's direction.

A useful compatibility record includes:

• Source schema stamp: the schema of the input data.
• Target/output schema stamp: the intended output schema for a write, migration, export, or round-trip step; use N/A only when no output schema applies.
• Build stamp: the program performing the operation.
• Operation: read, write, migrate, or a precisely defined round-trip sequence.
• Result: supported, supported with migration, unsupported, or unknown.
• Evidence or rule: a test result, migration rule, or documented reason.
• Diagnostic action: the observable signal and safe response for unsupported or unknown cases.

Direct reading and migration are separate decisions. A build may read an older schema without changing it, migrate that schema to a newer one, support writing only the newer schema, or reject a requested output schema.

1330. Mental model

Use the model SOURCE × TARGET × BUILD × OPERATION → DECISION:

For each row, ask:

1. Can this build interpret the source schema for the named operation?
2. Does the operation produce output, and if so, is its target schema explicit?
3. If this is a migration, does a defined source-to-target migration exist?
4. If this is a round-trip, what exact sequence is performed and what invariant must hold?
5. What observable diagnostic should appear when the combination is unsupported or unknown?

A round-trip is not merely “save and load again.” Define its direction. For this lesson, one valid example is read S1 → write S2 → read S2. Its named invariant is that the credits and items values from the original S1 record remain equivalent after the final S2 read. The new heat field follows the documented migration default and is not part of that preservation invariant.

1331. Concrete example

Assume a small save record begins at schema S1 and later adds a heat field in schema S2:

• B1 understands S1 only.
• B2 understands S1 and S2 and can migrate S1 to S2 by assigning a documented default to heat.

The target/output column prevents “migrate” or “write” from hiding the intended output schema. The explicit round-trip sequence prevents opposite directions from being treated as equivalent.

1332. Common mistakes

Avoid these errors:

• Treating direct reading and migration as the same capability.
• Assuming a newer build supports every schema or operation.
• Writing “migrate” without naming both source and target schemas.
• Writing “round-trip” without naming the sequence and preservation invariant.
• Marking an untested cell as supported instead of unknown.
• Treating silent field loss as an acceptable reverse migration.

1333. Guided practice

Create a compatibility matrix and plan of diagnosis for this fictional format:

• Schema S1 contains credits and items.
• Schema S2 adds heat and records a schema stamp.
• Build B1 can read and write S1.
• Build B2 can read S1, migrate it to S2, and read and write S2.
• No migration from S2 to S1 has been defined.

Complete these steps:

1. List schema stamps and build stamps as separate sets.
2. Include read, write, migrate, and round-trip operations.
3. For every row, name the source schema and build. Name the target/output schema whenever the operation produces or transforms data; otherwise enter N/A.
4. Define the required round-trip as read S1 → write S2 → read S2.
5. Name its invariant: the final record must preserve the original credits and items values. Record the expected rule for heat separately.
6. Mark every result as supported, supported with migration, unsupported, or unknown.
7. For every unsupported or unknown result, create a diagnostic record that captures together:
   • source schema stamp;
   • relevant target/output schema stamp;
   • build stamp;
   • operation and direction;
   • expected failure or warning;
   • evidence that would confirm the diagnosis;
   • safe next action.
8. Separately state which recorded field you would inspect first during triage and why. This sequencing choice does not remove the requirement to capture the complete diagnostic record.
9. Decide whether the S2 → S1 path is supported, rejected, or pending evidence. Do not design or implement a reverse migration. If you reject it, state why silent loss of heat is unacceptable.

Use this structure:

Do not replace missing evidence with a guess. Unknown is an appropriate decision when verification is still required.

1334. Validation / evidence

Your work is valid when it includes:

• Separate schema-stamp and build-stamp lists.
• Source and target/output schema fields, using N/A only when no output schema applies.
• At least one row for read, write, migrate, and round-trip.
• Operation-specific decisions for the important S1/B1, S1/B2, S2/B1, and S2/B2 cases.
• The explicit sequence read S1 → write S2 → read S2.
• A named invariant requiring preservation of credits and items, plus a separate expected rule for heat.
• At least one explicitly unsupported combination.
• Evidence or a documented rule for each supported decision.
• A complete diagnostic record for every unsupported or unknown result.
• A safe next action that avoids silent data loss.
• A written policy decision for S2 → S1 without implementing a reverse migration.

Submit the completed matrix and diagnostic plan through the attached practical assessment. The quiz checks conceptual understanding; the practical assessment evaluates your ability to produce and defend the artifact.

1335. Key takeaways

• Compatibility belongs to a source-schema, target-schema, build, and operation combination.
• Migrations must name both source and target schemas.
• Round-trips must name their sequence and preservation invariant.
• Direct-read, write, migration, and round-trip support are separate decisions.
• Unknown is preferable to unsupported assumptions.
• Diagnostic records should capture all relevant identities together and lead to a safe next action.

1336. Next lesson

Continue to 3.14 — Professional Git.

1337. Knowledge check