When would you model a suite's results in a bespoke schema rather than an interchange shape existing tools already read?

## The decision is "who reads this", not "which format is better" A result model has two audiences and they pull in opposite directions. **Existing tools** — viewers, history stores, dashboards, review surfaces — already parse a small number of widely-adopted shapes, and emitting one of those buys integration you never write and never maintain. **Your own suite** produces facts those shapes were not designed to carry: a status vocabulary richer than pass and fail, an attempt list, typed attachments hanging off the right node, a case identity independent of the display name. So the real question is never "is a bespoke model better". It is: *how much of what my suite knows is worth the readers I would have to write, and keep writing?* ## What each choice actually costs | | Widely-parsed interchange shape | Bespoke model | |---|---|---| | Readers | Exist already, for free | Every one of them is yours to build | | Expressiveness | Limited to what the shape defines | Exactly your vocabulary | | Schema change | Not yours to make | Needs a version and a migration | | Onboarding | Recognised on sight | A vocabulary documented nowhere else | | Cross-team aggregation | Works by default | Works only if both teams agree first | | Longevity | Outlives your harness | Lives and dies with your harness | The asymmetry that decides most of these arguments: the interchange shape's limits are visible on day one, while the bespoke model's costs arrive in month nine — when the second reader is needed, when a field has to change meaning, and when somebody else's view has to include your suite. ## The answer that is usually right: emit both Treat the rich internal model as the source of truth and the common shape as a **projection** produced at the boundary: 1. The suite writes its full model — statuses, reason codes, attempts, attachment references, stable identities. 2. A projection maps that onto the common shape for everything that already reads it, collapsing what the shape cannot express and putting the lost detail into whatever free-text field the shape offers. 3. The projection is **lossy in one direction only**. Nothing consumes the projection to rebuild the internal model, and no field exists in the projection that the internal model does not already hold. That costs one mapping function and removes the argument entirely. The failure mode to guard against is the mirror image: teams that make the common shape the source of truth and then bolt their extra statuses into its free-text fields, so the real model exists only as a convention inside strings that nothing validates. ## When bespoke-only is genuinely right Conditions that favour it: - You already own the readers, because the output feeds a history store or an internal surface you built and maintain anyway. The marginal cost of one more reader is small; for a team with none, it is the whole cost. - The distinctions are **load-bearing for a decision people make daily**, and collapsing them into the common vocabulary would destroy that decision rather than merely blur it. - The suite's shape is genuinely unusual — long attempt chains, evidence at several levels, results merged from many independent sources. Conditions that argue against it, which teams talk themselves out of too easily: - **Nobody has named a reader yet.** A schema with no consumer is a guess about the future, and the guess is usually wrong in exactly the details that felt most important. - **The suite is one of several** that will eventually be looked at together. Two bespoke vocabularies are worse than one imperfect shared one, because the merge cost lands on whoever comes third. - **Turnover is high enough** that the vocabulary will outlive everyone who remembers why it has six statuses rather than four. ## If you go bespoke, three obligations - **Version the schema** from its first release, and treat a field's *meaning* changing as a version change rather than an edit. Silent meaning changes are the failure that readers cannot detect. - **Write the vocabulary down** beside the model: every status, its definition, and the action it implies. A status set without definitions drifts within two quarters, and the drift is invisible until someone builds a combined view. - **Keep a projection anyway.** The day someone asks for a view spanning teams, the projection is the entire answer; written after the fact it is a migration, written up front it is a function. The summary a lead should be able to give in one sentence: name the readers first, keep the rich model internal, project it outward, and pay for bespoke fields only where a decision depends on them.