Blog

The invoice changed. Why does the C# project have to?

The Data Model Is an Intent File, Part 1 of 5

Acme wants three things from an invoice email: the invoice number, the currency, and the total. So we write an InvoiceSummary record with a string for the invoice number, a string for the currency, and a decimal for the total.

A second customer, Globex, wants the purchase order number too. Sometimes it appears on the invoice. Sometimes it doesn’t. The customer wants to see the field either way, with an empty value when it was not supplied.

Do we add a property to Acme’s record? Write a second record? Keep adding nullable properties until one record covers every customer? All three can work. The awkward part is that a change to what the intake desk asks for is now a change to the C# project.

If the next step is to show the extracted fields in a review screen, export them as JSON, or hand them to another component that already reads the customer’s schema, there is another option: put the result contract in the same file as the intent. Let the C# application select the operation and handle the outcome. Let the intent file say which fields the operation returns, what types they have, and what makes an answer unacceptable.

What the file takes over

An intent file can say: read the invoice, keep the invoice identifier as text, require a currency from an approved list, and return a nonnegative total. It can also say what the model should do when it cannot find a purchase order number. The model uses the instructions and the requested shape; IntentSharp Catalog checks the reply against the schema in the application process. If an answer fails a check, the findings can go back with a retry, within the configured limit.

That moves the contract from a per-customer C# class to a document the application can load. The caller can receive the checked result as a JsonNode. The fields still have meaning: a total is a number and an invoice identifier is text. An identifier like 000184 is a good reminder of why those decisions matter. Make it an integer and you’ve lost part of the identifier before the rest of the workflow has even started.

The contract is also readable without following a chain of method calls. When someone asks why the extractor rejected a euro symbol, they can see the list of allowed currencies next to the instructions. A coding agent can read the same file to understand what this operation does before proposing a change.

What the application still owns

The application decides which customer’s intent to use, who can change it, and what happens after a reply passes or fails. A valid total does not prove that the total appeared on the invoice. An extraction that passes the schema can still need human review or a check against an authoritative system before anyone posts it.

I would keep the C# record if downstream code depends on that exact shape. I would move the contract into an intent file if the shape varies by customer and the downstream path can already work with JSON. The practical payoff is a smaller change: a new extraction field can be a change to the customer’s contract instead of a new class and a new branch in the application.

Next in the series: two invoice shapes, one C# caller. We’ll run both customers through the same program and see what happens when one reply fails.

Try an intent from a file.