Version identity has more than one meaning

1311. Lesson identity

Module

3.13 — Schema and build versioning

Lesson

Version identity has more than one meaning

Academic type

Concept

Schema type

text

Order

Lesson 1 of the module

Estimated time

30–45 minutes, including practice

1312. Learning objective

After this lesson, you can select the correct version identity for four situations: interpreting data, identifying an executable build, identifying a content set, and tracing a source-control change.

1313. Why this matters

A label such as v2 is not precise enough to answer every production question. A schema can remain compatible while the executable changes, and content can change without a new data format. If these identities are mixed, an AI assistant may diagnose the wrong layer or recommend an invalid migration. Separating them gives you a reliable language for compatibility checks, release notes, debugging, and rollback decisions.

1314. Prior knowledge

You should already be able to describe an integration check in terms of ownership, configuration, test mode, failure behavior, and evidence. This lesson builds on 3.12 L2 — Write an integration check without secrets and applies the same evidence-first discipline to version identity.

1315. Core concept

“Version” is a family of identities, not one universal number. Four dimensions must be distinguished:

These identities can be related without being interchangeable. One build may package a particular source commit and content manifest while still using an older schema. Conversely, two builds can use the same schema and content but differ in code.

Compatibility is also dimension-specific. A schema compatibility claim concerns data readers and writers. A build compatibility claim concerns the runtime artifact and its environment. A content compatibility claim concerns whether the content set can be loaded and used by that build. A source-control identity provides traceability; it does not by itself prove that the resulting artifact was packaged correctly.

1316. Mental model

Use the four-question version filter before choosing a version identity:

1. What is being interpreted? Choose the schema version when the subject is data shape, fields, encoding, or migration.
2. What is being run? Choose the build version when the subject is a packaged executable or deployable artifact.
3. What is being authored or included? Choose the content version when the subject is rules, assets, levels, tuning, or configuration data.
4. What exact project state must be inspected or reproduced? Choose the source-control identity when the subject is a commit, tag, or repository state.

A useful record can show the relationships explicitly:

Build:        build-0.8.4
Source state: commit 7f3c1a2
Schema:       save-schema-3
Content:      content-set-17

Read this as a traceability record, not as four competing claims that the whole game is simply “version 3.”

1317. Concrete example

Imagine a test report stating: “The inventory data failed after the update.” The sentence is incomplete. Apply the filter:

• If the item record contains a field the reader does not recognize, investigate the schema version and its migration or compatibility rule.
• If the tester needs to identify the exact executable that produced the error, record the build version.
• If a new item balance or item definition caused the behavior, record the content version.
• If an engineer needs to inspect the exact implementation that generated the build, record the source-control identity.

A precise report might therefore identify all four dimensions while assigning each a separate role: the failing artifact was build-0.8.4, built from source state 7f3c1a2, reading save-schema-3, with content-set-17 loaded. The report does not assume that changing any one of these identities changes the others.

1318. Common mistake

The common mistake is treating a build number, schema number, content label, and commit identifier as interchangeable because they appear in the same release note. A build number tells you which artifact ran; it does not tell you whether a save format is compatible. A commit identifies source history; it does not prove which content files were packaged. When a compatibility question is vague, first name the object whose identity is needed, then record that dimension explicitly.

1319. Guided practice

Classify the primary version identity for each situation. Write one sentence explaining your choice.

1. A loader must decide whether it can read a saved record containing a newly added field.
2. A tester reports a defect and must identify the exact executable used.
3. A designer wants to compare two sets of enemy tuning and encounter data.
4. An engineer needs to inspect the exact source state from which a test artifact was produced.

Then complete this traceability record with distinct labels rather than one generic version field:

Build: ____________________
Source state: ______________
Schema: ____________________
Content: ___________________

For each blank, state what evidence would support the value. Do not invent a value if the evidence is unavailable; mark it as unknown and identify the missing evidence.

1320. Validation / evidence

Your evidence is a completed classification with four correct choices and a traceability record whose fields are not conflated. You should be able to point to:

• the schema identity used for data interpretation;
• the build identity used to identify the runnable artifact;
• the content identity used to identify authored data;
• the source-control identity used to inspect or reproduce project history; and
• one sentence explaining why a source-control identity alone does not prove build or content compatibility.

A strong result uses the four-question version filter and distinguishes “which artifact ran?” from “which data can it interpret?”

1321. Key takeaways

• Version identity depends on what is being identified.
• Schema version answers data interpretation and migration questions.
• Build version answers which runnable artifact was used.
• Content version identifies authored data and configuration sets.
• Source-control identity provides precise project traceability but does not replace artifact or compatibility evidence.

1322. Next lesson

Next: 3.13 L2 — Design a compatibility matrix

1323. Next lesson

Continue to 3.13 L2 — Design a compatibility matrix / Diseñar una matriz de compatibilidad.

1324. Knowledge check