The metadata contract for AI

In this chapter

• Why in-platform AI cannot see what was never captured.
• Context as a governed setting, not a prompt pasted into a chat window.
• The contract, enumerated: seven kinds of metadata generation needs, each phrased as a question to ask any vendor.
• Receipts: prompts under change control, and runs with records.

Chapter 7 ended on a question templates cannot answer for themselves: a pattern renders from what it is allowed to read, so what exactly should it be allowed to read? This chapter writes the answer down as a metadata contract, and that contract reaches well beyond templates. Every generator you will meet produces its output from what it was given to read and nothing else, whether that is the assistant built into your platform, the template engine from chapter 7, or the new hire who starts Monday. Enumerate what the reading list must include and you hold two useful things at once: a specification for the metadata your team should be capturing, and an audit list for every “our AI does it” claim a vendor puts in front of you, including the one writing this book.

The AI cannot see what was never captured

Chapter 1 opened on the offer every platform makes: land your data, and our AI does the rest. The assistants behind that offer are real, and inside their lane they are genuinely good. The lane is the point. An in-platform assistant reads what the platform holds, and what the platform holds is the physical estate: table names, column names, data types, key constraints, and whatever descriptions somebody once remembered to write.

The vendors do not dispute this. As of September 2026, the documentation for the assistants on Databricks, Snowflake, and Microsoft Fabric each says plainly that answer quality depends on expressive names, good descriptions, and the curated context you supply. Each platform then ships a place to author that context: instructions and example queries on one, a hand-written semantic model on another, per-model AI instructions on the third. Give the industry its due, because that is a concession to this book’s argument: the model was never the bottleneck, and everyone now agrees the context is. Look closely at where those context surfaces sit, though. Every one of them describes a single platform’s physical estate, in that platform’s own format, readable by that platform’s assistant, authored after the data landed. The right idea has arrived, one tool at a time, at the wrong altitude.

Consider what happens while the deepest context available is the physical estate. Point the assistant at your source schemas, ask it for a business model, and what comes back is your source schema with better labels. That is the only thing it could produce, because the schema was the only thing it was given to read. Ask it to integrate two systems and it cannot, because integration is an agreement between systems and the assistant met your systems one at a time. Nothing in either schema records that the customer number in your sales system and the account identifier in your billing platform describe the same person. That fact is a decision somebody has to make, and reading either system harder will never surface it.

That is the quiet dependency under the pitch. The AI cannot see what was never captured, and what was never captured is exactly the work of the last five chapters: what your business means, what your sources actually hold, how the two map together, what shape the integrated middle takes, and which conventions govern the build.

Why is business context not an AI prompt?

The workaround everybody reaches for first is the chat window. You paste in the glossary excerpt, then the naming rules, then the warning about the three customer tables, and finally you ask the question. It works once, and that is its whole problem. Pasted context is unversioned, unreviewed, and gone tomorrow. Nobody approved it, nobody can compare Tuesday’s paste against Monday’s, and when a colleague runs the same task with slightly different text, they get a slightly different answer. That is not governing the AI’s input. That is privatizing it, one chat session at a time.

Treat context instead the way you treat any setting that matters: captured once, in your own words, reviewed like any other change, and read by every run rather than retyped for each one. Definitions handled that way compound, which is why an afternoon spent sharpening what your organization means by a customer is the cheapest AI improvement you will ever buy. It lifts every proposal and every review that follows it. A vague frame gives you plausible answers about somebody else’s business, while a sharp frame gives you proposals that already speak your language.

The contract, enumerated

So what must generation be able to read? Seven kinds of metadata, and five of them you have already met as chapters. Each item below closes with the question to take into your next vendor demo, and each one is a strand of how we use AI rather than a prompt to be typed.

Figure 8.1: the contract, enumerated. Seven inputs, one generation step, a review gate, and the platform downstream of all of it.

• The conceptual model. The entities, attributes, definitions, categories, and relationships you built in chapter 3, with their approvals attached. This is what separates a conceptual model from a schema with better labels: what your organization means, expressed in vocabulary a domain expert recognizes, decided by people with the standing to decide. Where does the generator read what my business means by a customer, and who approved that definition?

• The mappings. Chapter 5’s deliverable: which source column feeds which business attribute, with each pairing carrying its decider, its rationale, and its history. Without the mappings, a generator can reach your sources or your meaning, but never both at once. Can the generator read which column maps to which attribute, who decided each pairing, and which columns nobody has mapped yet?

• The conventions. Chapter 7’s placement rule, made enforceable: naming rules with their resolution order, system columns with declared roles, hash rules, and the type mappings for each platform, all stored as data the generator reads rather than logic sealed inside it. Are my conventions inputs the generator reads, or opinions compiled into its code?

• The source register and its profiles. Chapter 4’s observations promoted to decisions: which systems exist, who owns each one, how each delivers its data, and the accepted profile facts about what that data actually does. Does generation know how my sources behave, or only how they are declared?

• The shape decision and its rulings. Chapter 6’s choice, written down: which integration shape the middle takes, along with the rulings that keep it consistent, including every exception you allowed and the reason you allowed it. Where is the shape decision recorded, and how does the generator learn about the exceptions?

• The knowledge documents. The standards, dictionaries, requirements, and meeting transcripts your organization already wrote, extracted and addressable so that a run reads the relevant passage in your words rather than a summary of it. Can I hand over the documents my team already maintains, and will the generator read what they say or a paraphrase?

• The environment and dependency facts. The unglamorous item that breaks builds the moment it goes missing: which layers exist, which targets receive which artifacts, and what must already exist before each object loads. Does the generator know which layer it is writing for, on which platform, and in what order?

Score yourself against that list today. For most teams the honest result is a few items captured, a few scattered across wiki pages and people’s heads, and at least one that exists nowhere at all. That is not a failing grade; it is the backlog.

Self-sufficiency is the test

How do you know a contract is complete? Borrow the sharpest test template engineering has produced: if an author, human or machine, cannot produce the artifact from the declared context alone, the contract is incomplete, and the gap gets filled by guessing. Chapter 7 showed the miniature version of this failure, a generator that recognizes a column’s role by matching its transformation code and then breaks silently the day someone wraps that transformation in a time-zone conversion. The general rule deserves stating on its own: sniffing and inference are contract debt. A generator that quietly reads beyond its declared context is not being resourceful, it is borrowing facts nobody agreed to supply, and every borrowed fact fails without an error message on the day it moves.

Regardless of stack. The contract is identical whatever sits in the generation seat. A language model, a template engine, and a contractor hired for the quarter all need the same seven items, and all three fail the same way without them, by producing something plausible built on guesses. That makes the new-hire framing an honest self-audit: could a competent stranger produce a correct artifact from what your team has actually written down? If the answer is no, the machine cannot either, and unlike the stranger, the machine will not ask follow-up questions on its way to being wrong.

Receipts

If generation is part of your method, it needs the discipline you give any production process, and that discipline produces two artifacts.

The first is the prompt. The instructions a generator runs are where its opinions live, so they belong under change control like any other source file: versioned, readable, testable before publication, and different from yesterday only because somebody decided to change them. If you cannot read the instructions your generator runs, you cannot review its opinions, and you are shipping them anyway.

The second is the run record. Every generation run should leave behind what was asked, what context was resolved for it, what came back, and who approved the result. Three weeks later, when somebody asks why the model proposes a concept nobody remembers discussing, that record is the difference between an answer and a shrug. It is also what makes machine-written changes governable at all, because a proposal that passes the same permission checks and lands in the same audit log as a human edit means “what did the AI change” has exactly the same answer as “what did your colleague change”.

The people part. Neither artifact helps if nobody tends the contract, and the contract does not curate itself. Owning the definitions, the conventions, and the choice of which documents count is steward and architect work, and it is continuous rather than a one-off setup. The review seat is where that work compounds, because a decision made on one proposal becomes context the next run reads. Teams that treat review as a formality get a generator that stays exactly as wrong as it was on day one, while teams that treat it as curation get a generator that improves every week without a single model upgrade.

The contract is buildable this quarter

Notice what is absent from the seven items: not one of them waits on a platform feature or a model release. Every item is metadata, and chapters 3 through 7 showed how each one is captured, whether that is the conceptual model drawn out of conversations, the source register built from profiling, the mappings recorded as deliberate decisions, the shape settled by a reasoned choice, or the conventions fixed by writing the rules down once. The platforms will keep shipping smarter assistants, and every one of them will make the same trade this chapter opened with: it reads what it can see. Widen what is captured and every generator you own improves at once, whichever vendor ships it.

Metadata to capture. Here is the score sheet: the conceptual model with approvals; the mappings with deciders and history; the conventions as declared data; the source register with accepted profiles; the shape decision with its rulings; the knowledge documents, extracted and addressable; and the environment and dependency facts. Then there are the two receipts, which are prompts under change control and a record for every run.

Look at what those receipts quietly demanded: who decided, who approved, and which context fed which output. Capture the facts as the work happens and they cost you nothing, but reconstruct them later and they become a project with a budget. That trade, records written at creation against records rebuilt under audit pressure, is the whole subject of chapter 9.