DEV Community: Jeff Tsai

Day 10: Multi-Database Support: CRUD and Structure Upgrades

Jeff Tsai — Tue, 03 Nov 2026 00:34:20 +0000

"Supports SQL Server, PostgreSQL, MySQL, Oracle and SQLite" is one line in a specification. Inside a framework it is a question that has to be answered before anything else: what exactly is being abstracted for them.

Neither direction works:

Wrapping up what every vendor can do has no end to it. Each item wrapped means filling the same gap five times over, and by the end every item is half finished
Sharing nothing but a connection object is not support for multiple databases, it means every form's statements get written five times

This framework's answer is narrow, narrow enough to be two things only.

This post covers:

Why there are only two shared behaviors
CRUD, where the differences are small enough for a lookup table to absorb
Structure upgrades, where the differences are large enough that each vendor really does get its own
Which vendor is used is registered by the application, and the framework ships none

1. Why there are only two shared behaviors

How many databases a framework should support has no general answer, because it depends on what is being sold. Supporting one buys depth, since that vendor's native types, bulk interfaces and dialect features are all directly available. TableSchema and Database Structure Upgrades said that for packaged software a short support list means a whole set of customers gone, which is what makes multi-vendor support a condition of entry.

What this layer faces is five commonly used relational databases, not everything that can store data. Those five share one data model: tables, columns and rows, all speaking SQL, all with transactions. Precisely because the layer underneath is shared, "CRUD" and "keeping the structure caught up with the definition" point at the same thing on all five.

Two tests, both of which have to hold:

Is this something every application does
Does it keep doing it

Measured with those two, not much is left:

What got in	Why
CRUD against a single table	There is no application that does not do it, and it happens once every time a user presses save
Keeping the structure caught up with the definition	No application can dodge it, and it comes round once at every deployment

What did not get in: partitioned tables, materialized views, full text search, each vendor's own analytic functions, query hints, and the dedicated interfaces for bulk loading. Every one of them is valuable, and they share one property. Not every application needs them, and the ones that do usually use them in only a handful of places.

Take bulk loading as the example. Most databases have a dedicated mechanism far faster than writing row by row, but no two of them are the same shape. One hands you a class of its own, another a special statement, another wants a file written out first for the database to read itself. Designing a common interface over those yields the smallest intersection and nothing more, and the smallest intersection is usually about as fast as writing row by row. Wrapping it gains nothing and leaves five implementations to maintain.

These two tests measure whether this layer should be doing something, not whether it matters. Partitioning may be a life or death question for a document table of a hundred million rows. It simply should not be an interface that has to hold for five vendors at once deciding how it is done.

Once the measuring is over, what is left is all of it. The framework's entire outward abstraction is one interface, and what gets asked of a database falls into two categories: how to produce CRUD statements for a table, and how to keep the structure caught up with the definition. The second splits into four smaller pieces, being read the current state, create a new table, alter in place, and rebuild when altering will not do.

The line is drawn narrowly, and what that buys is that it can be finished. One interface and two categories of question means connecting a new database is something you can read to the end of and write to the end of. If that interface had thirty members, this would never happen in practice.

The two jobs sit inside the same interface, though, and the abstraction over them is nothing like the same thickness.

2. CRUD, where the differences are small enough for a lookup table to absorb

The pain: the same query looks different on all five, and the places where it differs are extremely boring. What symbol wraps table and column names, how a parameter is written, how paging is expressed. Boring, but every statement has to be right, and one mistake is a run time syntax error, of the kind that never appears at all when the test environment runs a different database.

These differences are of a good kind. They are different spellings of the same thing, not different things.

The reason for collecting them into one lookup table is that the cost of not collecting them is scattered. Statements get assembled in more than one place, with separate stretches for listing, reading one row, counting, and each of insert, update and delete. Every stretch judging for itself which vendor is in play means every stretch has its own chance to miss one, and the one missed shows itself only when a customer happens to run that database.

Database	Identifier quoting	Parameter prefix
SQL Server	`[sys_id]`	`@`
PostgreSQL	`"sys_id"`	`@`
MySQL	`sys_id`	`@`
Oracle	`"SYS_ID"`	`:`
SQLite	`"sys_id"`	`@`

Oracle's row carries one extra thing. An unquoted identifier gets folded to upper case there, so what the framework sends is always quoted and upper case, and on the way back the framework folds it to lower case at the boundary, so that every layer above sees exactly the same column names on all five. Data and Definitions Split Apart, So Forms Need No Types of Their Own said there is one set of names the whole way through, and this is that rule's closing move at the lowest level.

One thing is left that a lookup table cannot solve, because the shapes really are different:

Database	Taking rows 21 to 40	Skipping the first 20 and taking everything after
SQL Server and Oracle	`OFFSET 20 ROWS FETCH NEXT 20 ROWS ONLY`	`OFFSET 20 ROWS`
PostgreSQL and SQLite	`LIMIT 20 OFFSET 20`	`OFFSET 20`
MySQL	`LIMIT 20 OFFSET 20`	`LIMIT 18446744073709551615 OFFSET 20`

MySQL matches the middle row only when a range is being taken. Given a starting point and no count, it will not accept an OFFSET standing on its own, so a ceiling has to be padded in, and that string of digits is the sentinel value its own documentation specifies, not something typed at random.

The conclusion is in the shape of the five implementations. The five classes matching the five vendors are all but identical, each one handing the query and the delete to the same shared code and mentioning on the way past which vendor it is. The three statements used for saving go further and do not even come in five: one class assembles them while holding an enumeration value.

That class is TableSchemaCommandBuilder, which takes which vendor and the table's structure at construction, assembles the three, and wraps them together with that table from the DataSet into one thing handed down:

var insertCmd = BuildInsertCommand();
var updateCmd = BuildUpdateCommand();
var deleteCmd = BuildDeleteCommand();

return new DataTableUpdateSpec()
{
    DataTable = dataTable,
    InsertCommand = insertCmd,
    UpdateCommand = updateCmd,
    DeleteCommand = deleteCmd
};

That same post said the state of each row decides which statement gets issued, and here is where it is honored. Inside the whole class, which vendor is in play arrives from exactly two places, being how identifiers are quoted and what prefix parameter names take, which are the two columns of the first table above. How the three statements are assembled has not one branch in it.

The differences all sink to the layer below, where what can be looked up is looked up and the one case left over is taken care of by shared code.

This half of the abstraction is very thin, and thin is good. Connecting one more vendor means almost nothing to write on this half.

3. Structure upgrades, where the differences are large enough that each vendor really does get its own

For "widen this column from 20 characters to 50", what differs between vendors is not the spelling but whether it can be done at all. That is no longer different spellings of one thing, it is a difference in capability itself, and a difference in capability cannot be absorbed.

Difference one: reading the current state

No two of the five are alike:

Database	Where it is read from
SQL Server	The `sys.*` set of system views
PostgreSQL	`information_schema` mixed with `pg_catalog`
MySQL	`INFORMATION_SCHEMA`
Oracle	The `USER_*` data dictionary
SQLite	`sqlite_master` plus a few `PRAGMA`s

The reason this cannot be pulled apart is not dialect, it is how each vendor regards its own structure. SQL Server treats a column default as an object in its own right, stored separately and named separately, so reading it means joining one more system view. SQLite goes to the other extreme. It does not enforce types, and keeps the VARCHAR(50) originally written down exactly as written, so for the framework to know how long a value can be, that string has to be taken apart and read again.

There is a step after reading, and it is harder than the query.

That post's rule that the definition holds no database's type names has its cost land here. Creating a table means translating framework types into native types, so comparing means translating the native types read back the other way, and that translation is many to one. On MySQL a Guid is stored as a fixed length character column of 36, and a fixed length character column is just one way of spelling a string, while auto number and long integer both land on BIGINT. Translating back, all the database reports is a char with a length, or a bigint. The meaning was already thrown away on the way out.

So the reverse half is not the lookup table read backwards, it is recognizing the meaning again from extra clues:

A fixed length character column of exactly 36 is a Guid
A numeric column of precision 19 and scale 4 is a money amount
A BIGINT gets a second look for an auto increment flag

These clues hold on the premise that the framework only ever emits those few spellings, so a table the framework built itself is always recognized again. The cost sits on that same premise. Take over a table the framework did not build and these inferences go wrong, with the symptom being a comparison that reports a difference which is not there, every time.

The forward mapping fits in one list, and the reverse half does not. Once an abstraction has thrown information away in the middle, there is no free route back.

Difference two: whether it can be altered at all

That post's rule, altering in place within a family and rebuilding across families, is all but void on SQLite, because its ALTER TABLE cannot touch an existing column. So the same change that takes seconds on another database copies the whole table's data on SQLite.

The framework does not choose to smooth this over. What it does is compute the difference and show it, which is what that post's dry run is for. The same definition against different databases can yield different plans, and whether to schedule a maintenance window was always a question for that plan to answer. Smoothing it over would be worse, because what gets smoothed away is exactly the thing the user most needs to know.

Difference three: the hardest to spot, because it reports no error

From 8.0.13 onward MySQL requires that a default value which is not a literal be written as an expression wrapped in parentheses. So for the framework to have a column generate a Guid automatically, what goes out is DEFAULT (UUID()). Writing it is fine.

But at the next comparison, what INFORMATION_SCHEMA reports back is uuid(). The parentheses are gone, and the function name has turned lower case.

So the literal comparison runs like this. The definition says (UUID()), the database says uuid(), the two do not match, a change is declared, one more ALTER goes out, it runs, the next comparison still gets uuid() back, and there is one more ALTER again.

An upgrade that never converges. It does not fail and it produces no error message. It quietly issues one more statement at every startup, altering a column that never changed.

The framework's answer is to normalize both sides to the same shape before comparing, stripping one layer of outer parentheses and ignoring case. SQLite has a problem of the same kind, since it stores the create statement as written and reads it back as written, and it needs a normalization of its own.

And one more kind: column descriptions

Every column in the definition has a line of description meant for people, and storing that in the database gets four answers out of the five vendors:

Database	How column descriptions are stored
MySQL	Written straight after the column definition
PostgreSQL and Oracle	A separate `COMMENT ON` statement
SQL Server	Hung on a set of things called extended properties
SQLite	Not kept at all, where writing is a no-op and reading always comes back empty

What the framework does about the last one is say outright that it cannot be done, and leave the description on the definition side. Pretending it had been stored is what would be the disaster, because it would never match when read back, which is that non converging loop over again.

These several kinds of difference are all branches off the same abstraction on its way down, and not one of a thousand definitions needs to know about any of it. The cost is that someone has to know for them.

That someone is this layer. Reading back and writing out are only the entry fee. The hard part is recognizing that what was written out and what comes back are the same thing.

4. Which vendor is used is registered by the application, and the framework ships none

The pain: your system uses one database, and the framework claims support for five. So five vendors' drivers sit in the output directory and the container image is that much bigger, and the day one of them ships a security update, your vulnerability scan lists it even though you never used a line of it. Versions are harder still. A framework that folds five drivers into its own dependencies has pinned five versions on your behalf.

A dependency that is not itself using something should not be the one making that decision for all of its users.

So the framework builds in none of them. An application registers whichever one it wants to support, at startup, and the case study's line comes from NorthwindBackend.cs:

DbProviderRegistry.Register(DatabaseType.SQLite, new SqliteProviderFactory(SqliteFactory.Instance));

What gets registered is the ADO.NET level factory, out of each vendor's own package. The same file has one more line, registering the set that produces statements and reads structures for it, which is the whole interface of the two sections above. Connecting a database the framework does not ship for means writing exactly that one part.

The framework never registers any vendor itself, and that sentence is written into the source comments.

Registration happens in code, not in configuration. What configuration carries is the database kind, an enumeration value, not a type name. Letting configuration name a type would mean the framework going off to find an assembly by name at run time, which moves the driver dependency out of the dependency list and into a string, where the build can no longer see it.

This discipline is verifiable in the source. Not one project in the whole framework references any of the five vendors' packages.

SQLite took one extra piece of work for this. Its driver does not provide the DataAdapter the framework needs for writing back, so the framework supplies one, wrapping the abstract factory type and handing every other member straight through, with the instance passed in by the application at registration. Even something needed for that one vendor does not reference that vendor's package.

The case study uses SQLite only, and the other four vendors' packages are not even referenced. The reason for choosing it has nothing to do with the framework's design: no database to install, one file and it runs, which is the least trouble for a demonstration.

The thickness of an abstraction

Five databases, two jobs. What got in is what every application has to do and keeps doing. What did not get in is not less important, it is only needed in a few particular places.

The two look nothing alike once abstracted. The CRUD half is thin enough that the five implementations are all but the same, because the differences between vendors are different spellings of one thing. The structure upgrade half is thick enough that each vendor gets its own, because the differences between vendors are differences in capability.

The thickness of an abstraction is not decided by its designer. It is decided by how far apart the things underneath it are.

This layer's return takes time to show. At the first delivery it is pure cost, being one more interface, two more lines of wiring and five more implementations. It pays back when a second customer names a different database and you find that not one word of a thousand definitions has to change.

Supporting one more database does not really cost those few hundred lines of implementation. It costs the gaps that no document tells you about in advance, and how many of those there are is something you only learn by walking into them.

The next post, Connections, Transactions and Query Conditions in the Data Access Layer, is about the stretch the framework decides not to do itself: when SQL is handed back to the application to write, which things the framework does not hand over along with it.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-10-two-common-jobs

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 9: Data and Definitions Split Apart, So Forms Need No Types of Their Own

Jeff Tsai — Mon, 02 Nov 2026 01:18:41 +0000

One request travels front end, API, business object, repository, database, and every layer has to receive the same record. What most systems put here are types they wrote themselves: an Entity per table, a DTO on each side, and a layer of Mapper configuration in between.

This framework puts two things there: a data container (DataSet) plus a definition running alongside it. The data is in the container, and everything said about the data is in FormSchema. What that split buys is one thing. Eight forms or a thousand, not one extra type appears in between.

This post covers:

Why a data container rather than strong typing
Writing no DTO means pulling data and definition apart
What crosses layers is data plus its description
What checks the things the compiler cannot, in two stops
These costs are paid for the sake of a thousand forms

Why ERP Needs a Definition-Driven Framework counted an expected delivery date on the order landing in thirteen places, four of which were the Entity, the DTO, the Mapper and the front-end type. Why those four can be empty is what these five sections add up to.

1. Why a data container rather than strong typing

The pain: a user asks for an expected delivery date on the order, with no calculation and nothing linked to it. You open the Entity and add a property, open the DTO and add one, open the Mapper and add a line, open the front-end type and add one more. Four files, one compile, one deployment.

That field does nothing at all in business terms, and it has left four signatures in the type system.

Then multiply by a thousand tables, and by dozens of requests like it a year.

Whether a cross layer container should be strongly typed has had two camps with their own reasons for years, and this is not judging between them. What strong typing buys is clear, namely that the compiler watches the names for you, and that is exactly what gets paid here. This section only answers what kind of thing this framework needs in this position.

The answer is a container that does not yet know how many fields it has at the moment of compilation, for two reasons:

When the shape is settled: which fields a form has is written in the definition, and the definition is data, read in at run time. At the moment of compilation, the fact of which fields an order has does not exist. It also carries on changing, because that data is there precisely so that consultants, tools and even users can edit it.
When the type has to exist: an earlier post, An Overview of Definition-Driven Architecture, drew a line between producing code at build time and producing objects at run time. A strongly typed cross layer container means that type has to exist at build time, so every definition change means regenerating, recompiling and redeploying. However cleanly everything upstream derives, one compile time type in the last mile grows the whole delivery path back.

The first post said that going from a definition change to it taking effect involves no compiling, packaging or deploying. Half of whether that sentence holds is staked on this layer.

2. Writing no DTO means pulling data and definition apart

The second pain is less glaring and costs more time.

What a field actually has to state goes well beyond what it is called and what type it is. Is it required? Does it show in the list? How wide? Is it currency, and to how many decimal places? It points at the customer form, so once one is picked which values get written back into which fields? When picking through a lookup window, should only the active ones be listed?

None of that has a place ready for it in a DTO. What a type can express is a property name and a property type, and everything else has to be stacked on as a pile of annotations, read by layers that are not this one. So they scatter:

This thing	Where it scatters to
Required field rules	The validation layer
List columns	Front-end configuration
Relationships	Foreign keys in the database
Display formatting	Some shared utility method

The cost of scattering is not more files, it is that no one place is authoritative. The same thing is declared separately in several places, any two of them can fall out of line, and when they do nobody reports an error.

The framework pulls the two apart: data goes in the container, and everything said about the data goes in the definition.

Once they are apart, the description no longer has to be squeezed into the type system. An earlier post sorted what a single field can declare into six categories, being structure, behavior, presentation, semantics, relationships and security, and what a property can write down by itself is the first two items of the first one: the field name and the data type.

Relationships among those six need a few more words. That they are declared between forms, pointing at the customer program, came up in The Northwind Case Study: Eight Forms and a Custom Business Object. A type can hold a reference to another type, but that reference says only that it points there. It cannot say which columns the list shows, what a person sees in a lookup window, which fields are queryable, or whether to add conditions of its own. The relationship between forms is wider than the relationship between types, and forcing it into types pushes those extra things somewhere outside the types.

Pulling them apart returns one more thing:

A description on a DTO can only be read by the compiler. A description pulled out of it can be read by anyone.

3. What crosses layers is data plus its description

Writing no DTO does not mean throwing the data into a shapeless bag. The shape is still there. It just is not a type, it is a description traveling with the data.

On the way out, one table carries:

Its own name
A field list
The values of each row

Whoever receives it does not have to know it in advance. Because the description arrives with the data, there is no such thing as a type mismatch, and because every layer receives the same object, there is not one turn A into B step between reading from the database and feeding a front-end control. What is gone is not just those few lines of Mapper configuration, it is every error those lines can make.

A container can hold more than one table, and almost every document in an ERP needs that:

The order's container holds two tables, one master and one detail, with the detail hanging back onto the master by sys_master_rowid
Open an order and master and detail come back together; press save and they go out together
How many tables to send, which one is the master, and which column the detail hangs back by, are all things FormSchema has already said

Every row also carries two more things: whether it is added, modified, deleted or untouched, and what its original values were. That lets the save trip travel with no explanation attached. The user changed two fields on the master, deleted one detail line and added another, and what goes out is the container itself, with the server deciding which statement to issue from each row's state.

The cost was recorded in an earlier post's boundaries of use: every response carries the container's field structure with it. For one order that is worth it. For an event stream at tens of thousands per second it is not.

4. What checks the things the compiler cannot

Once data and definition are apart, the joint between them is the field name, and a field name is a string.

row["amout"] is one letter short and the compiler says nothing, throwing only when that line is actually executed. Worse, failure has more than one shape. A typo in a list column just means one column missing on screen, while the same name going into a query fails outright when the SELECT is assembled. A typo in a lookup window column is silent from start to finish: the column does not appear, and the log is clean too.

The same name written inconsistently across layers is harder still to track down, and some front-end controls bind case sensitively. Column names in the container are therefore always lowercase, lined up with the definition files, the database columns, the expression identifiers and the front-end binding keys. There is one set of names the whole way through, so errors of the casing kind have no room to happen.

The compile time gate cannot be won back, and there is no need to pretend it can. Asking to check at compile time a shape that is decided at run time is a contradiction inside the request itself.

What can be done is to move the moment of discovery forward, to the point where the shape is already settled. Once the definition is written, the shape is settled. Moving it forward has two stops.

The first stop: build time

The framework puts these checks in Bee.Analyzers, shipped inside the definition layer package, in effect as soon as it is referenced, with nothing extra to install. Most of them read not code but the XML of the definition files themselves.

Nineteen rules in four groups:

Whether a single definition contradicts itself
Whether several definitions line up with each other
Whether the code holds to framework conventions
Whether the shape of types taking part in transport is right

The two below are actual output. Type ref_customer_name in the order's list columns as ref_customer_nmae:

error BEE1004: FormSchema 'Order' lists 'ref_customer_nmae' in ListFields,
but the schema declares no such field. The list layout drops the unknown
column, but the query keeps it: building the SELECT throws
InvalidOperationException at run time. Fix: correct the name, or declare
the field.

The message has three parts: where it is wrong, how it will fail at run time if left alone, and how to fix it. The middle one is what most has to be there, because how it breaks at run time is exactly what decides how easy the error is to track down.

The second answers a cost from TableSchema and Database Structure Upgrades, a field added to FormSchema and forgotten in TableSchema:

error BEE2006: FormSchema 'Order' declares persisted field 'required_date'
on table 'ft_order', but the table schema has no such column. Queries
touching that field fail at run time. Fix: add the column to the table
schema, or mark the field Type="VirtualField" if it is not persisted.

Both builds stop on that line of the definition file. Missing one of the three places the first post counted for adding a field now ends as one failed build, rather than a support ticket after go live.

The second stop: integration testing

The first stop catches a definition written wrongly. What it cannot catch is the definitions all being right while what this document produces comes out wrong, and that takes data. The approach:

From the definitions plus the existing data, export an Excel import format for each kind of data. Which columns this sheet needs, what type each is, which ones a relationship brings in, and which are computed and need no input, are all already answered in the definitions.
Work the test data up in full in Excel, one file per kind. This step is the key one: whoever does it does not have to be a programmer. How many kinds of customer an order should cover, how many discount combinations, which boundary values simply have to be tried, are known best by the people who understand the business, and Excel is what they already use.
The test imports them in order, master data first and documents after, which is the order of the real operation. The data can be fed to the API or straight to the business object, and the container both entry points receive has the same shape.
Finally take a few key reports, turn the results into Excel, and compare them cell by cell against an Excel file already known to be right.

The first three steps only prove the data goes in. The last one is what asks whether the result is right. Pin both ends once each and the whole stretch in between is under test, without an assertion written for every step of it.

This can be written as a tool because the description was pulled out. It is data a program can read, obtained by asking the API once, so the tool does not have to know any form in advance, and adding a form or changing a field does not move it either. After a release, run the whole batch again and you know whether anything broke.

The route skips the front end on purpose, and the reason is not to save effort. The controls on screen are a set the framework owns, which control a field uses is computed from the definition, and a field of a given type grows the same control on every form and runs the same code.

So the shape of how errors are distributed changes: when some control behavior breaks, it breaks across the board, not on one form.

A point everything converges on is what FormLayout and Screen Generation for Multiple Front Ends called the rendering layer, where a hand written screen gets one screen wrong at a time and the rendering layer gets all of them wrong at once. That was said about risk. In testing it is the other side of the same thing: something that goes wrong everywhere cannot hide, and opening any form at all runs into it. Clicking through screens one at a time is the same code on its Nth execution.

5. These costs are paid for the sake of a thousand forms

A complete packaged ERP routinely has thousands of business tables, heavily interlinked. At that scale a set of types per form is not an inconvenience, it is unmanageable, and the costs Definition-Driven asks for are only worth paying at that scale either.

The first return is that adding a form takes no code: three new files plus three rows of registration and it grows. Seven of the case study's eight forms came from exactly that, with data traveling from the database all the way to the screen through every layer in between and not one line written by the application. The remaining one is the order, which added a few rules the definitions cannot state.

The second return is cost turning from multiplication into addition. Add a field and FormSchema gains a line, TableSchema gains a line, FormLayout gains a line, and then the database has one more column, the CRUD statements one more, the container one more, the field list sent to the front end one more, and the screen one more control. There is not one intermediate type anywhere along it. Four of the thirteen places the first post counted are not easier to edit in this model, they do not exist.

Adding a relationship or a front end is addition too. In the world of types, every extra relationship means deciding how to express it, when it loads and who maintains it. Here it is one more declaration in the definition, and the display columns it brings back are a few more columns in the container. An earlier post said supporting one more front end costs one rendering layer, and that front end does not have to bring types of its own, because the data it receives carries its own description.

The three parts of the split, and that bill

Data and definitions splitting apart, so forms need no types of their own: what that sentence really says is not that a few files are saved. It is the sum of three things:

The container's shape is decided by the definition, so it does not have to exist at compile time
The description travels with the data, so no layer in between has to know it again
Once the description is pulled out, those kinds of statement are no longer readable only by the compiler

Take away any one of the three and the split does not hold.

The split has a cost. The compiler now watches one category less for you, and that bill has not disappeared, it has moved to those two stops to be paid. Errors visible from the definition itself are caught at build time. What cannot be caught there gets a run with data prepared from the same definitions, with the reports compared cell by cell at the end.

Whether a design is honest is not about whether it has a cost, it is about whether it knows where its cost lands.

The next post, Multi-Database Support: CRUD and Structure Upgrades, is about how this data finally gets into a database: how a framework that knows no database driver in advance still produces CRUD statements for every one of them, and can change their structures too.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-09-data-and-schema-split

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 8: Declarative Business Rules and Computed Fields

Jeff Tsai — Sun, 01 Nov 2026 02:35:00 +0000

What the last few posts grew out of definitions were concrete products: tables, CRUD statements, screens on four front ends. Today's item builds nothing. It takes the expressions written into the definition and evaluates them, either writing the result back into a field (ValueExpression) or stopping the whole save (FormRule).

Required fields, range checks, arithmetic between fields: the content differs at every company and the shape is identical. All of them are take a few fields on this row, work something out, and stop if it does not hold. An identical shape is something a mechanism can absorb, so changing simple rules and calculations of this kind takes no code at all.

What gets standardized is the shape, not the content.

This post covers:

Why FormRule and ValueExpression live in the same definition as the fields
The four points where evaluation happens, and the asymmetry of validation running only on the back end
How the front end and the back end share one expression
The two kinds an expression cannot state, and why they differ in nature
Declarative as the default rather than the only route, with application code stacking on top

1. FormRule lives in the same definition as the fields

Declarative logic has two homes. The two extracts below come from the case study's order form, Order.FormSchema.xml. One hangs off a field:

<FormField FieldName="amount" DbType="Currency" NumberKind="Amount" ReadOnly="true"
           ValueExpression="quantity * unit_price * (1 - discount)" />

The other hangs under the FormSchema as a whole:

<Rules>
  <FormRule RuleId="customer_required" Trigger="BeforeSave"
            When="status != &quot;Draft&quot;"
            Condition="customer_rowid != Guid.Empty"
            Message="Please select a customer for the order." />
  <FormRule RuleId="quantity_positive" Trigger="BeforeSave" TargetTable="OrderDetail"
            Condition="quantity &gt; 0"
            Message="Every detail line must have a quantity greater than zero." />
</Rules>

Both live in FormSchema, and there is no separate rules file. One FormRule reads as a single judgment, and the order of its attributes is the order of its meaning:

Trigger: when to check. Both rules in the example check before saving, and checking before a delete has to be marked separately
When: whether this check applies this time. If it does not hold, the whole rule is skipped
Condition: the condition that has to hold
Message: the sentence the user sees when it does not
ValueExpression: not part of that judgment at all. It hangs off a field, and what it computes is written back into a column

The When in the example means a customer can be left blank while the order is still a draft, and is required once it leaves draft. It is a separate attribute from Condition rather than folded into one sentence because the folded shape is easy to write backwards, and a rule written backwards does not report an error. It just passes, from then on, always.

Living alongside the fields is deliberate. Apart from Trigger, the subject of every one of those attributes is a field. Rename a field, delete it or change its type, and the FormRule has to move with it. Two separate files means one of them goes stale first, and the stale one does not report an error either. It quietly stops stopping anything, one day.

One effect is especially visible on FormRule. Among the things that change most often after a system goes live, validation conditions come near the top: the maximum discount used to be 20 percent and has been loosened to 30; this document used to be saveable at zero value and now is not. The change is small enough to state in one sentence, and going through code costs a whole round of compiling, packaging and deploying. FormRule is data, so what changes is one string.

2. Evaluation happens at only a few points

Point	Where	What happens
When a row is created	Front end	Default value expressions are evaluated once and filled into the fields still empty
When a field is edited	Front end	The computed fields that depend on it are recalculated immediately, and the amount on screen moves with them
Before a save	Back end	New rows get their still empty default values filled in first, then new and modified rows recalculate their computed fields, and last the rules whose `Trigger` is `BeforeSave` run. Rows nobody touched are not recalculated, because recalculating would mark them as touched
Before a delete	Back end	The rules whose `Trigger` is `BeforeDelete` run. What they check against is not the data in the user's hands, it is the record the framework reads back from the database separately

The front end is doing arithmetic too, which raises a question: at save time, should the values it worked out be trusted?

The framework's answer is no. That recalculation before saving is unconditional, and every ValueExpression result sent up from the front end is overwritten. Data integrity cannot be entrusted to the front end. It may have calculated wrongly, and it may not even be the front end you wrote.

That decision buys a property: the front-end half can be absent entirely. A front end that cannot run live evaluation is simply one where the amount does not move as you type. The operation is unchanged, and the value stored in the database is identical. Live preview is experience, not part of correctness.

An asymmetry: validation runs only on the back end

Computed fields are calculated on both sides. FormRule runs only at the business object step on the back end, and never once on the front end.

The difference is what happens when each one is wrong:

A computed field the front end got wrong costs nothing, because the recalculation before saving overwrites it.
Validation has no overwriting step. What the front end blocks, the back end never sees at all, and what the front end lets through, the back end blocks anyway.

So moving a copy of validation to the front end buys the user one round trip of waiting, at the cost of the same rule being evaluated in two places. Sooner or later the two stop lining up, and then there is one more question to answer: whose message counts.

FormRule has exactly one line of defense, the step before saving on the back end. What the front end is responsible for is letting the user watch the numbers move.

Where these points sit inside the save flow, and how they relate to the part that writes to the database, is the subject of Extension Points on a Business Object and When to Override Them.

3. One expression, and both sides have to get the same answer

If the same expression is written once on each side, then next year somebody changes only one of them, the screen shows one number and what gets stored is another. Each side looks correct on its own, which is what makes it take so long to track down.

The framework has both sides reference the same code. One line of ValueExpression applies to the front end and the back end at once. The evaluation code sits in the definition layer with no server only dependencies, so what the back end calls before saving and what the front end calls on every keystroke are the same method on the same class. Whether the two could produce different answers is structurally not a question.

That one line of expression gives something else as well. To recalculate live, the front end first has to know which computed fields to recalculate when a given field is edited, and that mapping is not configured separately. It is worked backwards by parsing the ValueExpression once and taking the names out of it.

4. The two kinds an expression cannot state

What an expression can see is the batch of data this operation is holding, and for now only this row of it is opened up. An amount is this row's quantity times this row's unit price, and a required field rule looks at whether this row filled it in.

That range decides what currently cannot be declared, and those things happen to fall into two kinds that are nothing like each other:

Kind	Examples	Nature
Cross row	There must be at least one detail line, or the master total equals the sum of the detail amounts	The data is already in hand, so this one is a matter of progress
Has to ask the database	A status cannot go back from shipped to draft, or assign an order number	The data is not in hand, and this one is left outside deliberately

The cross row kind is reachable by adding an aggregate function, letting an expression state the sum of the detail amounts, since those rows are in the same batch as the master to begin with. The hard part is that evaluation then has to queue up again: the master total depends on the detail amounts, a detail amount is itself an expression, and the ordering needs rules of its own. There is a solution for that. It is simply not implemented yet.

The other kind is what genuinely cannot be stated. The moment an expression can query the database it stops being portable, the front end can no longer evaluate it, and the property from the previous section, both sides referencing the same code, is the first thing to break. So the line is not drawn at one row versus several rows. It is drawn at whether the answer is inside this batch of data. What is inside will be reachable eventually. What requires leaving it to go and ask is withheld on purpose.

5. Declarative is the default, not the only route

The doubt raised back in The Northwind Case Study: Eight Forms and a Custom Business Object is at its most direct here: if validation can only be written as a Condition, what happens to whatever an expression cannot state?

Half the answer is in the previous section, which is that what cannot be stated gets written as code. The other half is that declarative was never the only route. It is the default.

That whole evaluation sequence is itself the default behavior of the business object's before saving step, and that step is open to being overridden.
An application that overrides it calls the default part first, so the rules still run and the computed fields are still calculated, and then continues into its own code. The two stack. It is not a choice between them.
One level further down there is a finer granularity again. FormRule is data, and each rule carries its own Enabled and Order, so a single rule can be disabled and the order within one point can be specified. Turning one rule off does not mean touching the whole definition, let alone changing code.

Flexibility sits in the same shape here as it does at the layout layer, covered in FormLayout and Screen Generation for Multiple Front Ends: not in the capability, in the granularity.

6. The case study: what the definition absorbed, and what stayed in code

One ValueExpression plus three FormRule entries is everything the case study currently declares. What they replaced was code that used to sit in the order's business object: the per row amount calculation, and three checks on customer, product and quantity.

Four things are still in code, and they split two and two across the two kinds above:

Cross row: at least one detail line, and the master total
Has to ask the database: the status transition, and the order number

The case study post cut the same pile once before, asking whether each thing ought to be written by the application. Today's line asks why each one cannot be declared. The two are not asking the same question, so an item does not have to land in the matching place. The status transition and the order number were on opposite sides back then, one being a business judgment that differs at every company and the other being something that should be absorbed and has not been yet, while today's line puts them both in the same kind.

That line has moved, and nobody will tell you

The order's business object does one more thing that the case study did not count: on create, it sets the order date to today. The framework already does that. A date typed field gets today's date when a row is created, with nothing declared at all. The difference is that when the other items moved into definitions somebody went back and deleted the code, and for this one nobody did. That line still runs, the tests are still green, and it simply has no reason to exist any more.

Every notch the declarative side moves forward turns a batch of things on the code side from necessary into residue.

The case study put it as what stays in code being partly what belonged there all along, and partly what has simply not been taken over yet. There is a third kind: already taken over, with nobody having gone back to remove it. Of the three that one is the hardest to find, because everything about it is fine. It is just written for nothing.

In closing

Of the four things left in the case study's code, only one is a rule this company set for itself. The other three are not business judgments, they are places where the declarative side failed to catch them. And that answer has a shelf life: the cross row half disappears once aggregate functions and evaluation ordering arrive, and only the half that has to ask the database is outside on purpose.

So which parts should be written as code is never a list, it is a line that moves. What a framework designer can do is not to draw it in the right place once, it is to make sure that when it does move forward, not one word of the hundreds of definitions already written has to change.

The next post, Data and Definitions Split Apart, So Forms Need No Types of Their Own, is about the data container that travels all the way across the layers: why a thousand tables do not each get a type of their own, and how the bill for losing compile time checking gets paid.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-08-declarative-rules

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

ERP Architect's Notes: Designing a Definition-Driven Framework · Series Index

Jeff Tsai — Sat, 31 Oct 2026 01:10:08 +0000

The complexity of an ERP is not in how hard any single feature is. It is in how many times the same fact gets restated, multiplied by how many tables, multiplied again by how many customizations.

A thirty-post series written for iThome Ironman 2026, a thirty-day technical writing challenge in Taiwan, published from 2026-08-17 to 2026-09-15. The series is complete.

This series is not about building one form with a framework. It is about designing a framework that can drive hundreds of forms: the single source of truth lives in definitions rather than code, and the database structure, SQL, screens for multiple front ends, validation and computation, multiple languages, multi-tenancy and customization are all derived from the same layer of definitions. The Northwind case study verifies it, but the case study is evidence, not the subject.

It is about mechanisms and trade-offs, not a usage tutorial, and the cost of every design is written as plainly as its benefits.

Chapter One · Why Definition-Driven

What the problem is, where the paradigms diverge, and the case study's first appearance. This chapter sets side by side how many places one field touches under each paradigm.

Day 1 · Why ERP Needs a Definition-Driven Framework
Day 2 · An Overview of Definition-Driven Architecture
Day 3 · The Northwind Case Study: Eight Forms and a Custom Business Object

Chapter Two · Definition Layer

What kinds of definition files there are, why their lifecycles differ, and how one structural description grows into the database structure, CRUD SQL, screens for multiple front ends and business rules.

Day 4 · The Purpose and Classification of Definition Files
Day 5 · How FormSchema Drives SQL
Day 6 · TableSchema and Database Structure Upgrades
Day 7 · FormLayout and Screen Generation for Multiple Front Ends
Day 8 · Declarative Business Rules and Computed Fields

Chapter Three · Data Access and Caching

Without writing DTOs, how data crosses layers; the only two things multiple databases have in common; and how a cache knows its source has changed.

Day 9 · Data and Definitions Split Apart, So Forms Need No Types of Their Own
Day 10 · Multi-Database Support: CRUD and Structure Upgrades
Day 11 · Connections, Transactions and Query Conditions in the Data Access Layer
Day 12 · Cross-Node Invalidation for Definition and Data Caches

Chapter Four · Business Logic and API

Who takes over the part definitions cannot express, where the extension points open, and what a call passes through on its way from the caller to the business object.

Day 13 · Session Management and Lifecycle
Day 14 · Extension Points on a Business Object and When to Override Them
Day 15 · API Contract Layering and the Type Registry
Day 16 · JSON-RPC 2.0: Protocol Choice and the Request Pipeline
Day 17 · The Connector and the Convergence of Client Responsibilities
Day 18 · The Error Contract and User Visible Messages

Chapter Five · Multi-Tenancy and Customization

How one codebase lets every company look different without branching and without recompiling or redeploying. Where the customization work currently stops is stated plainly too.

Day 19 · The Scope of the Customization Layer and Overlay Granularity
Day 20 · Multilingual Customization and Resource Structure
Day 21 · Business Logic Customization and the Four Plugin Stages

Chapter Six · Transport, Security and Audit

What data looks like when it is sent, which protections it passes through, who is allowed to call, and what can be looked up afterward.

Day 22 · The Division of Labor Between XML, JSON and MessagePack
Day 23 · The API Payload Security Pipeline: Order, Protection Levels and Keys
Day 24 · The Three Axes of Permissions: Action, Row and Column
Day 25 · The Audit Trail and the Before and After Values of a Change

Chapter Seven · Data Semantics

Amounts, quantities, dates and times of day: how the meaning of these values is kept from the definition all the way to the database, without any layer quietly changing it along the way.

Day 26 · Numeric Semantics, Multiple Currencies and Units of Measure
Day 27 · The Semantic Boundaries Between Date, DateTime and Time
Day 28 · Time Zone Conversion of DateTime

Chapter Eight · Case Review and The Big Picture

The Northwind application examined item by item: which part definitions, the framework and application code each own. Then a single big picture, and the systems this design does not suit.

Day 29 · Which Part Definitions, the Framework and Application Code Each Own
Day 30 · Three Depths of Development and the Big Picture of the Framework

About the framework behind this series

The mechanisms discussed in the series are all built into an open source framework, bee-library. The case study is a separate repository, bee-northwind-avalonia, which pulls the framework in as a package and holds only the application's own definition files and code.

Update: Bee.NET (bee-library), the framework used when this series was written, has since been taken over by Polhem. The mechanisms carry over, the framework has been substantially refactored, and it is open source under the MIT license. The bee-library and bee-northwind-avalonia repositories are archived; type names and code in the posts follow bee-library as it was at the time of writing.

The framework's only role in this series is to show that these ideas are not just talk on paper. You can skip it entirely, take away only the idea of letting definitions be the source, and build that idea in the languages and tools you know.

📘 Original index on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/ironman-2026

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 7: FormLayout and Screen Generation for Multiple Front Ends

Jeff Tsai — Sat, 31 Oct 2026 00:55:16 +0000

TableSchema and Database Structure Upgrades ended at physical tables, where one change means moving data and working out beforehand whether you need downtime. Today is back on the screen side, where the character is the exact opposite. Changing a screen means changing a definition, with no new release, and one change lands on every front end at once.

The order form in the case study works exactly like that. Desktop, browser, iOS and Android all read the same FormLayout and each grows its own look, with not one screen written by hand.

This post covers:

Why FormLayout's vocabulary is deliberately small
From one field to one native control
One rendering layer per front end
Why this layer stands on its own: it expires
Why narrow screen reshaping is not written into the definition
Screens come in two kinds, automatic and manual layout, and the data binding is the same for both

1. FormLayout's vocabulary is deliberately small

A FormLayout is made of two kinds of section:

Master sections: there can be several, and they all share one column count
Detail sections: there can be several or none at all, and they always run the full width below the master

A master section holds fields, and about a field the layout states only this much: which group it belongs to, what it comes after, whether it takes extra width, which kind of control it uses, whether it is visible, whether it is read only, and whether it is required. A detail section holds columns, and it can state much the same set, plus a width.

The layout does not talk about position. There is not one coordinate in the whole definition, and nothing that says put this at row three, column two. Position falls out of the rendering layer following the order: fields fill in one after another, a full row moves on to the next one, and a field marked as spanning two columns takes two cells. Even the column count is not a promise. It is an upper bound, and a narrow screen pushes it down.

Here is an extract from the case study's order layout, the full file being Order.FormLayout.xml:

<LayoutSection Name="Main" Caption="Order">
  <Fields>
    <LayoutField FieldName="order_date" Caption="Order Date" />
    <LayoutField FieldName="customer_rowid" Caption="Customer" ControlType="ButtonEdit"
                 DisplayFields="ref_customer_id,ref_customer_name" />
    <LayoutField FieldName="total_amount" Caption="Total Amount" ReadOnly="true" />
  </Fields>
</LayoutSection>

A layout answers four questions and no more: which fields this form has, in what order, in which groups, and which kind of control each field uses. Visible, read only and required are states hanging off a field, and they do not change the shape.

A small vocabulary is this layer's specification, not a sign that it has yet to grow up. The layout is not the final thing to be drawn, it is the thing in the middle. Its downstream is not one kind of screen, it is each front end's own arrangement mechanism, and those mechanisms have nothing in common with each other: a layout control on the desktop on one side, the browser's grid on the other, and whatever the next front-end generation uses is unknown today. For an intermediate that has to feed all of them, the vocabulary has to be small enough that every one of them can translate it.

So the things that are not in it:

Placement, meaning alignment, margins and spacing
Styles, templates and animation, which are about what it gets drawn as, and belong to the rendering layer
Sections inside sections. A layout opened up is flat, so it can be scanned in bulk and checked programmatically

What is left out matters more than what is kept. A field pinned to a pixel position breaks on the next screen size, and if a definition can express that at all, what breaks is a thousand definitions.

Hundreds of screens that look the same

The users of an ERP, HRM or CRM system are almost all internal staff. They do not pick a screen to use, they are assigned a whole module, and before it goes live they have to learn dozens or hundreds of the forms in it.

If screens are written by hand one at a time, every one of them is free to look different. Details on the right here, underneath there. Picking a customer through a magnifying glass that opens a window here, a drop down there. The add button above the grid here, bottom right there. Each difference on its own is nothing. Added up, they are what the user has to remember.

With a small layout vocabulary, those differences have nowhere to happen. What the user learns is not hundreds of screens, it is one screen plus hundreds of sets of fields. Training cost therefore does not scale with the number of forms, and training has never been a small line in a rollout budget. Replace the staff or add a department and it gets paid again.

The cost: buying consistency means no screen is ever optimized for itself. A form used far more often than the rest can have its layout adjusted, but only within this vocabulary. Whether that trade is worth it depends on how many forms there are. Ten screens each optimized for itself is a good thing. Hundreds each optimized for itself is hundreds of operating habits.

2. Fields map to controls

If a field does not name a control, the kind of control is decided by its type in FormSchema:

Type declared in `FormSchema`	Default kind of control	Desktop	Web
Boolean	`CheckEdit`	Check box control	Check box input element
Date and datetime	`DateEdit`	Date input control	Date input element
Long text	`MemoEdit`	Multiline text control	Multiline text element
Small integer, integer, big integer, decimal and currency	`NumericEdit`	Numeric input control	Text input element
Everything else	`TextEdit`	Text input control	Text input element

The kind of control gets translated into each front end's native control, which is what the two right hand columns of the table above are, and beyond the name the two sides have nothing in common.

One rule outranks the type when picking a control. A field that declares a cross form relationship and does not name a control gets a lookup window editor by default. An earlier post, How FormSchema Drives SQL, said the same relationship declaration is also at work on the screen side, and this is where it lands. That one control binds several fields at once. The value goes onto the relation key, what shows on screen is the display columns it brings back, and one pick writes all of them back together, so those display columns do not each take a cell of their own.

When a control is bound it reads back from FormSchema. A text control fetches the maximum length, a drop down fetches the option list, and a lookup window editor fetches which program it should open. So the layout only has to record which kind of control, and never restates what the field means.

The only part tied to a UI framework is that translation into native controls, and all of it sits inside the rendering layer. The parts before and after deal only with definitions, so changing front ends does not move a single word of them. LanguageResource owns the text, FormLayout owns the arrangement, and the ViewModel handles data binding.

3. One FormLayout, one rendering layer per front end

The layout layer does not know that UI frameworks exist, and that claim can be checked the same way The Purpose and Classification of Definition Files checked it: the definition layer package has an extremely short reference list, and no UI framework is anywhere on it.

So what it turns into happens entirely inside each front end's own rendering layer:

The column count is just a number in the layout. The desktop turns it into equal width columns on a layout control, and the web turns it into a few lines of browser grid style declarations.
A list layout is handed to a grid control to draw on the desktop, and laid out as an HTML table on the web. The columns, the order and the widths both sides read are the same ones.

The case study's four front ends are put together exactly that way. Desktop, browser, iOS and Android share one UI project, and each platform entry point is down to startup and the few files of the platform shell.

Writing a rendering layer sounds vague. Taken apart it is four things:

Arrange the two kinds of section
Map control kinds onto this framework's native controls
Bind the controls to the ViewModel
Decide how it reshapes on a narrow screen

None of those is easy, but all of them are finite, and once they are done this front end runs every form.

How to communicate with the back end is not on that list, because that part does not get rewritten. Every front end goes through the same client layer, so one more front-end framework moves not one line on the server. That client layer is the subject of The Connector and the Convergence of Client Responsibilities.

The rendering layer those four share is Bee.UI.Avalonia, and even the browser front end is the same code compiled to run there. Supporting one more front end costs one rendering layer. Not zero.

4. This layer stands on its own because it expires

The comparison in Why ERP Needs a Definition-Driven Framework had a row for what a new front-end generation costs. Today makes good on it.

Packaged ERP and HRM products have life cycles of ten or twenty years and up, and over that time the system has to grow a different look with each turn of front-end technology. Desktop applications, web, mobile apps: every time a generation arrives the question is the same one. Those hundreds of screens, do they all get rebuilt?

If screens are written by hand one at a time, the answer is only ever rebuild, the volume is proportional to the number of forms, and it has nothing at all to do with whether the business changed. A company's order form gained two fields in ten years, and its screen has been rewritten three times.

That is the question the split is there to answer. Structure is stable and follows the business; layout is volatile and follows the front-end generation.

The two rhythms differ in the shape of the spending:

	Rhythm of change	Shape of the spending
Structure	Continuous	Small amounts: a few more fields and a few changed rules a year, touching one or two forms each time
Layout	Intermittent	One large amount: nothing for ten years, then all of it at once

Hand written screens tie both rhythms to the same file, so that once a decade large payment gets multiplied by the total number of forms every time. Once they are separated, what gets paid is a fixed cost, once.

This is not free. Somebody has to write the rendering layer and get it right, and it is a point everything converges on: a hand written screen gets one screen wrong at a time, and the rendering layer gets all of them wrong at once. Whether it is worth it depends on how many forms there are. On a system with a thousand the gap is too wide to need calculating, and on a system with ten, writing them yourself is quicker.

Do the layout files themselves expire? They do. The difference is that they are data. Changing a piece of data is not the same thing as changing screen code and then recompiling, repackaging and redeploying.

5. Narrow screens reshape themselves, with no second layout

The usual approach is a separate layout for phones, so one form has two layouts, and the two evolve apart.

This framework has the rendering layer reshape itself instead:

Single record screens: the master column count is pushed down to one, and detail sections switch from editing in place to tapping a row and opening a row edit form
Lists: wide, it is a table with one row per record; narrow, it is one card per record, with each field taking a line on the card, caption on the left and value on the right

iOS	Android

The fields on the card are not a second list written somewhere else. The wide table and the narrow card read the same list layout, the same set of columns in the same order, and the only difference is what it gets drawn as.

There are not two definitions kept in sync, there is one definition with two ways of drawing it, and that is its most practical value. One more copy is one more chance of the two not lining up, and a list missing a column is usually only found when a user asks why the amount is not visible on their phone.

Not one word of those reshaping decisions is written in the layout definition. The layout says which fields there are and how many columns they sit in; how narrow counts as narrow, and how details get edited once it is narrow, are the rendering layer's own judgment. The framework source leaves a comment right there: how details are edited is the UI layer's business, and the shared layout definition stays neutral.

There is a reason the line is drawn here. The moment a layout definition starts describing what happens on a phone, it has written a set of assumptions about screens into the definition. Today's assumption is two widths, phone and desktop. The next generation may be some other shape, and changing an assumption written into definitions means changing a thousand of them.

The cost: the same layout does not come out looking identical on different rendering layers. That is deliberate. Demanding pixel level sameness across front ends is demanding that every one of them give up its own platform conventions, and users expect platform conventions far more strongly than they expect sameness.

6. The standard is set, so where is the flexibility

The doubt raised in The Northwind Case Study: Eight Forms and a Custom Business Object, that a fully standardized flow leaves no room for flexibility, is sharper at this layer, because screens are what users look at every day. Screens come in two kinds, automatic layout and manual layout, and the part where data is connected is the same for both.

Approach	Where the screen comes from	The route for
Automatic layout	Goes through `FormLayout`. A layout is produced once at design time and adjusted as needed after that: how many sections, how many columns, which field spans two, which ones are hidden, which column is read only, and which columns a detail shows. It is data, so nothing is recompiled when it changes	Standard forms, which is to say the vast majority of them
Manual layout	Placing controls yourself and deciding positions yourself, without going through the layout layer at all	Shapes the layout vocabulary cannot arrange

Manual layout does not shut the framework out. Once the controls are placed, filling in the table name and field name is enough for reading and writing values, change notification, maximum length and option lists to connect as usual. The only difference between the two is whether the screen was arranged or placed by hand. The binding part is identical.

The layout vocabulary does not set out to describe every shape. It cannot, and it should not: dashboards, charts, drag and drop scheduling and maps all go through manual layout. Layout is where people most often ask for an exception to the line that a framework that can do anything has made no decisions for you. One more kind of section, one more style attribute, and one more kind of screen is covered. Every one added is one more thing every rendering layer has to deal with.

The flexibility is in the granularity, not in the capability. There is no cliff between automatic and manual layout, because the part where data is connected is the same on both sides.

7. The case study: what the order layout says and does not say

The case study's definition folder holds eight layouts, one per form, all produced at design time and adjusted afterwards. The order layout extracted earlier says this much:

One master section, two columns, one detail section
The three relationship fields on the master and the one on the detail all use a lookup window editor, and the display columns they bring back no longer take cells of their own
The amount column is marked read only in FormSchema and came across when the layout was produced, so on screen it simply cannot be typed into
Four front ends read the same one and grow four platform specific looks

What the order layout does not say outweighs what it does. It does not say where each field ends up on screen, what a lookup window editor looks like, how things are arranged on a phone, which language the captions get translated into, or how details are edited on a narrow screen. Precisely because none of that is its responsibility, it translates onto four front ends.

What gets rewritten that day

One layout definition growing into screens on four front ends: the real content of that sentence is not that screens can be described by definitions too. Being describable is only the entry ticket. The content is the sum of three things:

This layer's vocabulary is small, small enough for every front end to translate, and small enough that hundreds of forms look alike
It does not know what it will be translated into, so one more front end means one more rendering layer rather than going back to edit definitions
It is the part of the definition set most likely to expire, and when it does expire what gets replaced is the rendering layer, not the structure

I do not know what front ends will exist in ten years, and twenty years ago nobody guessed things would look like this. There is only one thing you can arrange in advance: that when that day comes, what has to be rewritten is finite, and unrelated to how many forms there are.

The next post, Declarative Business Rules and Computed Fields, covers computed fields and rules that run before saving, and how far both can be pushed into declarations.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-07-one-layout-many-uis

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 6: TableSchema and Database Structure Upgrades

Jeff Tsai — Fri, 30 Oct 2026 00:31:36 +0000

Yesterday's SQL was all about accessing data. Today is about something else: where those tables came from in the first place.

Which columns a table has, how long each one is, and which ones get an index, are authoritative in TableSchema. The physical structure in the database is a product made from it. This is the layer where that is hardest to honor, because the database already contains data, and data does not change shape just because a definition did.

This post covers:

Why TableSchema is separate from FormSchema
Why an upgrade compares the current state rather than running generated scripts
Why compare, plan and execute are three separate steps
How to work out how long this upgrade will take before starting it
ALTER or rebuild, and who decides
Five stages, each in its own transaction, and how a failure is cleaned up
The things deliberately not done, and the principle they share

1. Why `TableSchema` is a definition of its own

The two care about different things:

	`FormSchema`	`TableSchema`
What it cares about	Business semantics: what a field is called, what type it is, whether it is required, which form it points at	Physical storage: how long a column is, how many decimal places it holds, which columns get indexes and whether those are unique
Who decides	The people who understand the business	The people who understand this database

The same order number looks like this in the case study's ft_order.TableSchema.xml:

<DbField FieldName="sys_id" Caption="Order No" DbType="String" Length="20" />

<DbTableIndex Name="uk_{0}" Unique="true">
  <IndexFields><IndexField FieldName="sys_id" /></IndexFields>
</DbTableIndex>

The {0} in the index name is where the table name goes, producing uk_ft_order. An earlier post, The Northwind Case Study: Eight Forms and a Custom Business Object, said the framework guarantees the uniqueness of sys_id, and this unique index is where that guarantee lives.

The practical return on splitting them: tuning an index, changing a precision, or adding a composite index for one report touches only TableSchema. FormSchema is not involved, and neither is whoever originally wrote that form.

As mentioned yesterday, this file does not have to be written from scratch. The framework can produce a matching TableSchema straight from a FormSchema. After that the two are maintained separately, which is what gives those adjustments somewhere to live.

This definition contains no database's type names

What is written above is DbType="String" Length="20", not nvarchar(20), and the whole file is like that throughout.

The types a developer can write are a set the framework provides. The common ones are string, long text, small integer, integer, big integer, decimal, currency, date, datetime, boolean, Guid, binary and auto number. Which native type each becomes is decided at the moment a statement is generated, and the databases differ more than you would expect:

Framework type	SQL Server	PostgreSQL	MySQL	Oracle	SQLite
`Guid`	`uniqueidentifier`	`uuid`	`CHAR(36)`	`RAW(16)`	`UUID`
`Boolean`	`bit`	`boolean`	`TINYINT(1)`	`NUMBER(1)`	`BOOLEAN`
`Currency`	`decimal(19,4)`	`numeric(19,4)`	`DECIMAL(19,4)`	`NUMBER(19,4)`	`NUMERIC(19,4)`

The same Guid column is a built in type in one, text in another and binary in a third. Folding that decision into the mechanism buys four things:

Whoever writes the definition does not have to become an expert in this database first. Picking a native type takes experience. Using a floating point type for money, storing dates as text, or choosing too little precision for a timestamp are exactly where senior and junior diverge, and once it lands it grows into the data. The framework collapses the options into a set of types that talk about meaning, and the wrong one is not on the list at all.
The same kind of column looks identical across the whole system. You will not have a Guid stored as text in one table and as binary in another, and discover it when a cross table query refuses to line up.
One definition can run on several databases. Which ones a packaged product supports is stated openly, and the customer picks: their existing environment, the people who can maintain it, and the license fee a commercial database keeps charging. A short list is a whole category of customers you do not have.
Changing which native type a framework type maps to means editing one mapping table, not a thousand definitions. Writing native types into definitions would mean copying that decision a thousand times the moment it is written.

Comparison gets simpler for the same reason. Columns read back from the database are translated into framework types first, then compared against the definition. The definition says Guid, MySQL reports CHAR(36), translating back gives Guid, and identical means no change.

That type set is deliberately narrow. Vendor specific features are not in it, and using one means going outside definitions. Being able to express less buys the same definition holding everywhere.

The cost: the two have to line up

How FormSchema Drives SQL covered CRUD statements being assembled from FormSchema's field set, while table creation and upgrades go through TableSchema. So:

A field added to FormSchema but forgotten in TableSchema means the column is not in the database, while the save statement insists on writing it, and the error surfaces at run time
The other direction, an extra column, is harmless. It gets created, and the form path never touches it

Nothing reconciles those two definitions at run time. What holds it together is the order of edits: the field goes into FormSchema first, and TableSchema follows with the physical column. When The Purpose and Classification of Definition Files described that order it read like a habit. It is the operational version of this cost. There is a build time gate that watches for exactly this, covered in Data and Definitions Split Apart, So Forms Need No Types of Their Own.

2. An upgrade is not a generated script, it is a comparison against the current state

The usual approach is migrations: change the model, have a tool generate a script, commit it, execute in order, and have the database record which version it reached.

This framework has no scripts and no version numbers. Every upgrade asks the database what it looks like right now, compares that against the definition, computes the difference, and executes it.

The difference shows up in three places:

No need to know which version this database last stopped at
No need to guarantee every version's script ran, in order
Someone having edited the database by hand does not throw everything afterwards out of alignment, because the next comparison sees the edited state

What that buys is a very short contract for success:

When an upgrade returns successfully, the database has at least every column in the definition, with matching type, length and nullability.

Being safe to rerun is a consequence of the same thing. On a second run the current state is already the upgraded one, so the computed difference is empty. That property is used again when failure handling comes up.

Three costs:

Comparison has to ask the database about its own structure, and every vendor asks differently, so that part is written once per database
"Drop a column" cannot be expressed. A column absent from the definition is simply ignored, which the seventh section returns to
With no script, there is no file saying what this deployment will do to the database, available for review. On the migration route that script appears in the change list, and an experienced pair of eyes can see what it touches at a glance. Here the change list is a definition diff, where "a column went from 50 to 100" is readable but "does that trigger a rebuild" has to be asked separately

The third cost does have an answer, the compute without executing usage in the fourth section, except that the deployment process has to reach for it. It does not surface on its own.

3. Compare, plan, execute, cut into three

Step	Produces	Touches the database?
Compare	A structured difference: which columns to add, which columns changed definition, which one is being renamed, which indexes to create or drop. There is no SQL in it	Reads
Plan	How this will be done: the mode, how many stages, which statements per stage, and any warnings	No
Execute	Actually runs	Writes

The main reason for cutting it into three is not tidy layering. It is that the middle product is meant to be read by a person.

All three are called by the application. In production, the deployment tool runs through every table registered in DbCategorySettings at release time. The entry point is TableSchemaBuilder, and the case study's version is in NorthwindSchemaSeeder.cs:

var builder = new TableSchemaBuilder(category.Id, defineAccess, connectionManager);
foreach (var table in category.Tables)
    builder.Execute(category.Id, table.TableName);

That one Execute is the three steps run end to end. Computing without executing means taking them apart, which is called a dry run: CompareToDiff for the difference and TableUpgradeOrchestrator.Plan for the plan, then decide whether to go further.

4. Run the plan first and you know how long this will take

The plan computes one of four modes:

Mode	Impact	What to do
No change	No impact	Nothing to do
Create table	A new table with no data	Just run it
Alter table	Seconds, with at most a brief lock on a single column	It can run during normal hours
Rebuild	The whole table's data is moved and the table is locked throughout	Schedule a maintenance window and estimate the move time first

A rebuild works by creating a temporary table, moving the data in bulk, dropping the old table and renaming the temporary one. On a table with tens of millions of rows that can take anywhere from tens of minutes to hours. So what to look at before deployment is not the SQL, it is the mode. Do a dry run, see whether the mode is rebuild, and only then print the SQL for human review.

Besides the mode, the plan carries a list of warnings, such as which columns are being narrowed. So there are two things to read: the mode decides whether you need downtime, and the warnings decide whether you need to go check the data first. This question used to be answered by experience, as in asking whoever is more senior. Now it is a return value, and it can be written into a deployment script.

5. ALTER or rebuild, decided by the framework

The framework sorts column types into coarse families, being string, numeric, boolean, datetime, Guid and binary, with auto number in a class of its own. The mapping rules are short:

This kind of change	Route
Adding a column, adding an index, dropping an index	ALTER
A change within one family, such as lengthening a string or moving from integer to big integer	ALTER
Nullability and default values	ALTER
Crossing families, such as string to numeric, or anything to boolean	Rebuild
Turning auto number on or off	Rebuild

Then it checks each change in turn. If all of them can ALTER, it alters. If a single one needs a rebuild, the whole table is rebuilt. If a single one is something this database cannot do, it aborts and reports, rather than doing half of it.

This is deliberately not offered as a choice, because it has exactly one right answer and that answer is determined by the content of the change. Making it an option only hands something computable over to guesswork, and a wrong guess costs data.

The families are coarse on purpose, erring on the safe side. Judging something alterable when it actually needs a rebuild, and discovering that halfway through execution, is far worse than spending one more rebuild's worth of time. Differences in vendor capability are absorbed the same way. The extreme case is SQLite, whose ALTER TABLE can only add, rename and drop columns. Change a type, a nullability or a default and the whole table has to be rebuilt. The same definition and the same change is a seconds long ALTER on SQL Server and a rebuild on SQLite, and the calling code is identical.

6. Five stages, each in its own transaction

On the ALTER route the SQL is not sent in one go. It is cut into ordered stages, each in its own transaction:

Drop the indexes whose definitions are about to change
Modify existing columns, being name, type, length and nullability
Add new columns
Create new indexes, and rebuild the ones dropped in step one
Sync the column descriptions

There is no other possible order. A column cannot be modified while an index sits on it, so the index has to get out of the way and go back afterwards.

If a stage fails, that stage rolls back, the rest do not run, and the exception propagates. Stages already committed are not rolled back. That sounds dangerous, so why not wrap the whole thing in one transaction? Because for statements like creating and altering tables, wholesale rollback is not reliable on most databases, and some do not enroll them in a transaction at all. Wrapping them buys a promise that looks safe and does not hold.

So the framework does not make that promise. It allows stopping partway and cleans up by rerunning. The property held over from the second section is used here: fix the cause and run again, and the completed stages compare as no change and are skipped automatically. Being safe to rerun is more practical than being able to roll back. A flow that reruns safely lets you fix the problem at three in the morning and press the button again. One that claims wholesale rollback but partially takes effect only leaves you unsure where you are.

7. The things deliberately not done

For an automated upgrade mechanism, the boundary of its capability matters more than the capability, because it is automatic, and nobody shouts stop at the cut that goes too far.

No dropping columns. A column present in the database and absent from the definition is always kept. The reason is that it is not necessarily garbage. It could have been added by another system, or be an extension column not yet folded into the definition, and a deletion cannot be taken back.
No foreign keys, and no touching triggers or views. Business rules do not go into the database, which is the same decision carried through.
Narrowing a column is refused by default. It is honored only if that option is explicitly turned on, and even then it is recorded as a warning. The reason is that silent truncation is the worst failure mode: it reports nothing, it just cuts a piece off the data, and it is usually discovered months later when someone asks why half a line of this address is missing.
Renaming a column has to be stated. The framework does not guess that something is probably a rename. To rename, mark the old name in the definition. It also guarantees only a single hop, and a chain of renames accumulated across several versions is not supported.

A simpler way to say the no dropping rule: the database may have more than the definition, never less. "Definitions are the single source of truth" has a precise meaning at this layer. It guarantees that everything declared in the definition is in the database. It does not guarantee that there is nothing else there. Demanding the reverse, that the database equal the definition exactly, costs the framework being given the authority to delete columns it does not recognize, and nobody wants to hand it that.

Not creating foreign keys brings an incidental benefit. The circle between department and employee from an earlier post is not even a question on the table creation side. With no foreign keys there is no ordering, and tables are created one at a time. A world with foreign key constraints has to work out which comes first. This one does not.

Together those rules are one principle: automation may add, and subtraction is left to people. Add a column wrongly and you add another one to fix it. Drop a column wrongly and the data is gone.

Back to Northwind

The case study creates its tables at startup, running the loop from the third section, comparing and upgrading each registered table in turn.

So adding a table does not change that code. Two of the six places counted in the previous post live here, being the new TableSchema and the row in DbCategorySettings, and table creation follows.

The first run is a fresh creation. Every run after that is a comparison, and with no changes it does nothing. Change a column length or add an index during development and the next startup catches up, with nobody having hand written a create or alter statement in between.

The boundary of the truth

Back to the opening sentence: the definition is authoritative, and the structure in the database is the product. That says more than "the framework generates your create statements." Generating statements is the easy part. The real content is these things together. The structure is described once, and the description does not mention which database vendor it is for. To know what it should look like right now, reading the definition is enough. And when the two disagree, it is the database that gets changed.

This layer has one thing the earlier ones did not: there is data here, so the word truth needs a boundary. The database may have more than the definition, never less. At other layers, definitions being the single source of truth is about clearing away duplication. At this layer, it is about knowing what it must not touch.

The next post, FormLayout and Screen Generation for Multiple Front Ends, returns to the screen side: how one definition grows into screens on four front ends.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-06-schema-single-truth

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 5: How FormSchema Drives SQL

Jeff Tsai — Thu, 29 Oct 2026 04:56:27 +0000

The previous post, The Purpose and Classification of Definition Files, laid the definition files out one by one, and FormSchema is the hub among them. Today, a concrete question: when a form queries and when it saves, where do those SQL statements come from?

This post covers:

The six places a new form touches, with zero lines of code
Querying: the join list and paging, both decided on every request
Saving: how a set of fields becomes INSERT, UPDATE and DELETE
Why this is not an ORM, and why the missing pieces are not omissions
The difference between a thousand definitions and a thousand classes

1. One more form, six places to touch

The first post, Why ERP Needs a Definition-Driven Framework, counted adding one field to an existing form. This counts a form that is entirely new:

What to touch	Action
`FormSchema`	A new one, with fields, relationships, details and rules
`TableSchema`	A new one per physical table, with columns, lengths and indexes
`FormLayout`	A new one, arranging those fields on screen
`DbCategorySettings`	One row, saying which category this table belongs to and which database carries it
`ProgramSettings`	One row, the program identifier and a display name
`MenuSettings`	One entry, where the user clicks in

Three new files, three added rows, zero lines of code, plus one more TableSchema if the master has details. The only one that has to be written from scratch is FormSchema. The other two can be derived from it and then adjusted. Seven of the eight forms in the case study grew exactly this way.

None of those six is a restatement. Each answers a different question: what this form has, what the physical storage looks like, how it is arranged on screen, which database it belongs to, who executes it, and where you click in.

Given that not a line of code was written, what runs when you press query, or press save? The same FormSchema holds up both, using completely different parts of itself:

Querying uses the relationship declarations, to assemble joins
Saving uses the field set, to assemble INSERT, UPDATE and DELETE

2. Querying: the join is looked up, not written

An earlier post, The Northwind Case Study: Eight Forms and a Custom Business Object, covered relationships being declared between forms, with no table name in the declaration. What the framework does with it is short:

RelationProgId (the program identifier)
  -> fetch that program's FormSchema
    -> take its master table
      -> take the physical table name
        -> join on that table's sys_rowid

That extra hop returns two things.

One when writing. What you declare is that an order points at a customer, not that some column of ft_order points at the primary key of ft_customer. When relationships live between tables, the author has to translate the business relationship into storage terms first. Between forms, what you write down is the thing you had in mind, with one less translation in between.

One when changing. The physical table name is written only inside that form's own structure, and other forms point at it with a program identifier. Renaming the customer table means editing the customer's definition, and every form pointing at it stays untouched. With table names hard coded everywhere, that becomes a global search that nobody can certify as complete.

The join list is computed fresh every time

The order list shows six columns, and the query the framework assembles is:

SELECT A.[sys_id], A.[order_date],
       B.[sys_name] AS [ref_customer_name], C.[sys_name] AS [ref_employee_name],
       A.[status], A.[total_amount]
FROM [ft_order] A
LEFT JOIN [ft_customer] B ON A.[customer_rowid] = B.[sys_rowid]
LEFT JOIN [st_employee] C ON A.[employee_rowid] = C.[sys_rowid]

The order master declares three relationships, and this statement joins two tables. The list does not show the shipper, so that table never enters.

There is only one rule:

The framework first collects the fields this query will touch into one list, from three sources, being the fields to select, the fields appearing in conditions, and the fields used for sorting. Whichever relationship fields appear in that list decide which tables are joined.

So "used" is not the same as "displayed":

Filtering the list by customer name joins the customer table for the WHERE clause, even though it is not among the displayed columns
Opening a single record brings in all three joins, because all three columns are displayed
Selecting only the master's own columns produces no joins at all

Condition values always go through parameters and never into the SQL text.

Nowhere is the answer to "which tables does an order join" stored. The cost is moving "what does this SQL look like" from build time to every single request, which adds a statement assembly step per query. It is the fixed overhead of this route, not something that can be optimized away.

The same declaration is also at work on the screen side. A field with a relationship becomes a lookup window editor in that cell, picking one record from the source form. The declaration the join reads and the declaration the editor reads are the same one.

Display columns do not exist in the table

The ref_customer_name in that statement is an alias. The physical order table has only customer_rowid.

When the front end finishes picking, it writes the code and the name into the data it is holding, purely so the screen updates immediately
Those columns are not written to the database on save, and the next read has the server join them in again
The authoritative value is always on the query side

So there is never a case of a customer changing its name and old orders still showing the old one. The cost is one join per display.

Which is correct depends on whether the field wants the value as it was or the value as it is. A name for display wants the current one; the unit price agreed at the time wants the historical one, and that one should have been a column on the order itself anyway. This line has to be drawn by the framework first, or each form decides for itself and one system ends up with two behaviors.

Declared one level deep, executed several levels deep

The employee form brings in the department name, and also the manager's name. Its relationship field points at department, and one of the mappings names ref_manager_name as its source field, which on the department form is itself a relationship field pointing at employee, for the manager. So it has to go one level further down:

FROM [st_employee] A
LEFT JOIN [st_department] B ON A.[dept_rowid] = B.[sys_rowid]
LEFT JOIN [st_employee] C ON B.[manager_rowid] = C.[sys_rowid]

st_employee appears twice. A is the employee, C is their manager.

Every form declares only the level it points at directly, and that level is how the business already talks about it, so whoever writes the definition does not have to be a developer to read it. The field of view is fixed at one level, the framework expands along the chain of forms recursively, and the SQL depth is unbounded. In a system with thousands of forms this is decisive. Relationships weave into a very large graph, and nobody needs to hold it in their head.

If the department side changes its own relationship, the employee form does not change by a single character, and the next query picks up or drops a level on its own. Whoever writes the declaration describes only the business level relationship. How deep it reaches, and how many tables it touches, is the framework's problem.

The circular relationship is not a problem here

The circle left in earlier, from department to employee and back, was already traversed by the statement above.

It causes no problem, because queries are computed fresh every time. The most a circle leaves to decide here is how many levels this particular query joins, and the level count is decided by the requested fields, not by the shape of the model. When nobody asks for the manager's name, that level never appears.

Generate strongly typed classes at build time instead, and the same circle becomes types referencing each other and a question of initialization order. One circle, and in a run time derivation world it is the depth of one query, while in a build time generation world it is a structural problem that has to be solved first.

Paging is computed fresh too

Which page, how many rows, and whether to count the total are all sent by the caller, on the same object:

var result = bo.GetList(new GetListArgs
{
    SelectFields = "sys_id,order_date,ref_customer_name",
    SortFields = [new SortField("order_date", SortDirection.Desc)],
    Paging = new PagingOptions { Page = 2, PageSize = 20 },
});

The framework normalizes those values before using them. The page number and page size are clamped into a sensible range, and the result.Paging that comes back is the set that actually took effect. The total is not counted by default; fetching one extra row is enough to know whether more follow, and an exact number costs one more COUNT statement. Paging always requires a sort, and if none is given the master's sequence column is supplied. Only when even that is absent does the caller have to say what it wants.

3. Saving: the field set is the write statements

The framework builds a table description on the spot from the master's field set, and from each detail's, and all three write statements come out of it. The order's UPDATE:

Update [ft_order] Set
[sys_id]=@sys_id, [order_date]=@order_date, [customer_rowid]=@customer_rowid, ...
Where [sys_rowid]=@sys_rowid

There are four things going on in that statement:

The sequence column is not in it, because the database assigns it
Display columns are not in it either, since the previous section covered their not having physical columns
The condition is always sys_rowid, and DELETE is the same
The whole row is written, not only the columns that changed

The fourth is clearest on details. A document has ten detail rows, the user edits one and deletes one, and the whole set is submitted. Only two statements reach the database, and the other eight rows are never touched. The UPDATE that does run writes every column of the edited row, not only the one that changed.

When master and details arrive together, all changes are wrapped in one transaction, and the order of saving and deleting is exactly reversed:

Saving: master first, details after
Deleting: details first, master after

The framework does not need to know what this document means to the business. It needs to know which table is the master, which are the details, and which column hangs the details back on the master.

One more thing, and the naming makes it easy to get wrong: all three statements are produced from FormSchema, not read out of TableSchema. TableSchema governs how the physical table is created, how lengths and indexes are tuned, and how the database keeps up with the definition, which is the next post's subject.

4. Why this is not an ORM

This section is not saying ORMs are bad, nor comparing their merits. An ORM works well in the setting it was designed for. The problem is quantity, as an earlier post covered.

The difference is not in how much each can do. It is in what sits at the two ends of the mapping:

	ORM	This mechanism
The application side	Classes and properties	A structural description that exists at run time
The database side	Tables and columns	Tables and columns

Different starting points grow different things, and three things are missing here.

No entity classes

Query results are not restored into objects. Data travels as rows, carrying its structure with it. With no classes there is no "one more table means one more class," and the multiply by a thousand problem from the first post simply does not arise at this layer. The cost is that compile time type checking goes with it, and Data and Definitions Split Apart, So Forms Need No Types of Their Own covers how that is repaid.

No relationships expressed as properties, therefore no lazy loading

There is no equivalent here of walking from an order to its customer to that customer's salesperson in one expression. Which fields you want has to be stated at query time, so there is no accident where touching one extra property fires one database round trip per row. In the other direction, wanting a column that was never declared means adding a mapping to the definition first.

Change tracking did not disappear, it moved

An ORM holds loaded entities in a context object and compares properties at save time. Here there is nothing to compare. Each row records for itself whether it is new, edited, deleted or untouched, and an edited row keeps the old values of the changed columns too. The state is recorded on the row rather than per column, which is why the UPDATE in the previous section writes the whole row.

Those three are not half finished work. This mechanism has no place for them to begin with. There are also a few limits of a different nature: joins are always single column equality against a physical table, and subqueries and non equality joins are not in scope. Those are not impossibilities. This route only governs the standardized form segment. Reports, statistics and batch imports run on a different track, writing their own SQL, and Connections, Transactions and Query Conditions in the Data Access Layer takes that apart.

5. A thousand definitions versus a thousand classes

Thousands of business tables under an object mapping model are thousands of classes, plus their DTOs, mapping configuration and repositories. Those have to be compiled, maintained, and kept in step with the database structure, and no tool can fully take that last part over, because it involves what a column means to the business.

The same thousands of tables under Definition-Driven are thousands of structurally identical pieces of data. The difference is not the count. It is who can process them in bulk.

A definition is structured data, and that has three direct consequences:

A batch script can sweep them. "Are the decimal places set correctly on every amount column" is one global search plus one test.
Tools can produce them. TableSchema and FormLayout are both derived from FormSchema, and that is a transformation program, not a code generation step followed by a compile.
AI can work with them. Asked to produce an eleventh definition following the pattern of ten existing ones, what it reads is a document with relationships and rules already declared, not a pile of classes whose intent has to be inferred from code.

Checking can move earlier too. A thousand definitions will still contain mistakes, pointing at a form that does not exist, mapping to a column that does not exist, or misspelling a field name in a rule. The difference is that those are errors a program can find at build time, and the framework does find some of them, as a later post covers.

A thousand wrong definitions are as bad as a thousand wrong classes. Being data does not make a definition automatically correct. What changes is how it gets fixed: edit one piece of data, rather than edit code and go through compilation, packaging and deployment again.

Definitions have not left ordinary engineering practice either. They sit in the same source tree as the code, go into version control the same way, show which lines changed the same way, and go through review before merging the same way. How they are changed is different. How they are governed is not.

One more item is not on the cost sheet at all: a thousand definitions share one set of conventions. Understanding how one form declares a relationship means understanding all of them, and whoever inherits the system does not have to learn each module's original author's habits one at a time. On a system maintained for ten or twenty years, where people have turned over several times and modules have been added in batches, that piece of work is paid again every time. That is how maintenance cost accumulates.

6. Back to the order form

The most complex form in the case study is one file in definition terms, Order.FormSchema.xml: a master with one detail, three relationships on the master, one per detail row, three validation rules and one computed field, with how those last two are evaluated being the subject of Declarative Business Rules and Computed Fields. Multiple relationships, master and detail, and a lookup window on every detail row, all declared, with no UI or CRUD code.

It is also the one form that needed code. Its repository exists for two SQL statements, reading the order's state in the database and finding the highest order number this month. What the declarations cannot express, you write. The standardized segment is definition driven, and those two statements do not have to take a detour because of the framework. Inherit a repository, add them, done.

Whether a form can avoid code does not depend on how clever the framework is. It depends on whether the framework recognized the part that is the same on every form and converged it into one mechanism. Which tables a query joins, and which statements a save issues, both fall inside that part.

The next post, TableSchema and Database Structure Upgrades, is about how a FormSchema becomes one, and how the physical database safely keeps up with the definition.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-05-schema-drives-sql

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 4: The Purpose and Classification of Definition Files

Jeff Tsai — Wed, 28 Oct 2026 00:41:19 +0000

"Definitions are the single source of truth" sounds like there is one file holding all of the truth. Open a project's definition directory and what you actually see is thirteen definition types. Some are a single file at the root, and some are one file per program, scattered through subdirectories.

This post is a map. Every mechanism discussed later uses a few of these, so meeting them here means not having to stop and explain each time. At the end of the fourth section there is a quick reference covering all thirteen, marked with which post expands each one. If a name is unfamiliar later, come back here.

This post covers:

The three boot files: SystemSettings, DatabaseSettings, DbCategorySettings
The three files for one form: FormSchema, TableSchema, FormLayout
Binding and navigation: ProgramSettings, MenuSettings, PluginSettings
The four shared by every form: LanguageResource, PermissionModels, CurrencySettings, UnitSettings
Four things all thirteen have in common: storage, caching, immutability, and what happens when one is missing

Each name below links to its source.

1. The three boot files: what this deployment runs on

Definition	Stored as	What it governs
`SystemSettings`	A single file	Where the master key comes from, how the payload is packed and encrypted, and debug mode
`DatabaseSettings`	A single file	Which physical databases this deployment has, and how to connect to each
`DbCategorySettings`	A single file	Which category a table belongs to, and which database carries that category

These three are the precondition for the system starting at all, and they are read in a fixed order:

SystemSettings (names where the master key is)
  -> the master key decrypts the key that protects settings
    -> which decrypts the connection passwords in DatabaseSettings
      -> only then do the database identifiers in DbCategorySettings resolve to anything

The order is not a convention. It is the only solution the dependencies allow. The reverse path does not exist: before a database can be reached, there is no opportunity to look a key up in a database.

The first link in the chain has to be readable when nothing else has started, so it cannot be encrypted itself. That is why the master key is not stored inside SystemSettings. That file records only where the key is:

<MasterKeySource>
  <Type>Environment</Type>
  <Value>BEE_MASTER_KEY</Value>
</MasterKeySource>

The framework separates that one startup read accordingly: no service, no cache, straight off the file, because at that moment nothing else exists yet.

Why the database concerns are two files

They answer different questions:

	`DatabaseSettings`	`DbCategorySettings`
What it answers	Which databases this deployment has and how to connect	Which category of data lands in which database
What it is	A fact about the deployment environment	A fact about the application's structure
When it changes	Moving data centers, swapping database servers, repointing a test environment	Adding a table or moving a body of data to a different database
How sensitive it is	Holds connection passwords and needs encryption and access control	Holds no secrets, and developers edit it daily

Splitting them lets each side change on its own, and separates the sensitive from the everyday as a side effect.

How many databases the data actually lands in, and how that relates to the table name prefix, is the subject of Connections, Transactions and Query Conditions in the Data Access Layer.

The definition layer holds database settings without knowing databases exist

A file recording connection strings, filed under the definition layer, looks like a layering violation. It is not, because what it holds is a description, not a connection.

The definition layer package has an extremely short reference list. It does not know a database exists, or HTTP, or a UI. A connection string, as far as it is concerned, is a piece of text with an identifier attached. What actually opens a connection is the data access layer. The definition layer only declares an interface that can hand over DatabaseSettings, and lets the data access layer use it.

2. The three definitions of one form

Definition	Stored as	What it governs
`FormSchema`	One per program	The hub: fields, types, cross table relationships, master and detail, computed fields and validation rules
`TableSchema`	One per table	The physical table's columns, types, lengths, nullability and indexes
`FormLayout`	One per layout	How those fields are arranged on screen

The three edits for adding a required date to orders in Why ERP Needs a Definition-Driven Framework are these three files.

FormSchema is the hub. The other two each face one direction, one toward the database and one toward the screen.

FormSchema declares which fields exist, what type each is, which ones point at other forms, which details hang off the master, which values are calculated, and what to check before saving. The framework uses it to assemble CRUD SQL and to decide the shape of data crossing layers.
TableSchema cares about physical storage rather than business semantics, so lengths, indexes and precision can be tuned separately by whoever knows the database.
FormLayout is the only one of the three that concerns the screen alone. How things are arranged is a design time decision, written into a layout definition and followed at run time.

The relationship between the three also fixes the order of edits. FormSchema describes which fields the form has, so a change starts there. TableSchema follows with the physical column. If it needs to be visible, it then goes into FormLayout.

3. Binding and navigation: who handles this program, and where it appears

Definition	Stored as	What it governs
`ProgramSettings`	A single file	Which business object and which repository a program identifier binds to. Left blank, the framework default applies
`MenuSettings`	A single file	The navigation tree's grouping, ordering, captions and visibility, with each item pointing at a program
`PluginSettings`	A single file	Which plugins run at save and delete for each program, executed in declaration order

ProgramSettings is a registry, one row per program, deciding who handles that program's requests. Leave the two binding columns blank and the framework's default CRUD flow applies. Name a class and that class takes over. When The Northwind Case Study: Eight Forms and a Custom Business Object said that of the eight forms only the order needs code, this registry is what it was reading.
MenuSettings is separate from the registry because the two are read by different ends. The registry is read by the server and holds class names from the code. The menu is read by the front end and holds ordering, captions and visibility. On top of that, the same program can legitimately appear at several places in the menu, so a node carries its own identifier rather than using the program identifier as its key.
PluginSettings records which plugins run before and after save and delete for each program, and in what order. The difference from inheritance and overriding came up in an earlier post: inheritance replaces and there can be only one, while plugins layer and there can be several. The details get their own post later.

4. The ones every form reaches for

Definition	Stored as	What it governs
`LanguageResource`	One set per language, split by form or category	Localized captions and option text
`PermissionModels`	A single file	Which permission models exist, which actions each governs, and how data scope is delimited
`CurrencySettings`	A single file	The decimal places and smallest circulating denomination of each currency
`UnitSettings`	A single file	The display decimal places of each unit of measure

These four belong to no particular form, and every form reaches for them.

LanguageResource is applied one entry at a time. FormSchema already carries field captions; the language resource supplies per language versions. Where one matches it replaces the caption, and where none matches the original stands. A project that does not need multiple languages never has to touch it, and adding it does not force you to translate every entry.
PermissionModels registers what permissions there are to talk about. Which actions require authorization and how data scope is delimited are models. Who has been granted what is data rather than definition, and does not live in this file. A later post takes that apart.
Currency and unit of measure are system level: how many decimal places a currency has, how many a unit displays, consistently across the system. Which currencies a given company may use, and what its cash rounding is, are company level settings that come from the database with the company's data rather than from a definition file. Both levels have their place, and a later post on numeric semantics uses them.

The thirteen at a glance

The four sections above group by purpose. Here all thirteen are laid out together in the same order:

Definition	What it governs	Where it is expanded
`SystemSettings`	Master key source, payload options, debug mode	This post
`DatabaseSettings`	Which databases this deployment has and how each connects	This post
`DbCategorySettings`	Which category of data lands in which database	This post
`FormSchema`	The hub, being fields, types, relationships, master and detail, rules and computed fields	The next post
`TableSchema`	The physical table, being columns, lengths, nullability and indexes	TableSchema and Database Structure Upgrades
`FormLayout`	How this form is arranged on screen	FormLayout and Screen Generation for Multiple Front Ends
`ProgramSettings`	Which business object and repository a program binds to. Server side only	API Contract Layering and the Type Registry
`MenuSettings`	The navigation menu's grouping, ordering, captions and visibility	API Contract Layering and the Type Registry
`PluginSettings`	Which plugins hang off each program, in declaration order	Business Logic Customization and the Four Plugin Stages
`LanguageResource`	Captions and option text, one set per language	Multilingual Customization and Resource Structure
`PermissionModels`	What permissions there are to talk about, being actions and data scope policy	The Three Axes of Permissions: Action, Row and Column
`CurrencySettings`	Decimal places and smallest circulating denomination per currency	Numeric Semantics, Multiple Currencies and Units of Measure
`UnitSettings`	Display decimal places per unit of measure	Numeric Semantics, Multiple Currencies and Units of Measure

These names recur over the next twenty odd posts, always in their original form. A descriptive phrase cannot identify which one is meant. "The category file" could be DbCategorySettings or it could be PermissionModels, and "the settings file" fits eight of the thirteen.

5. Four things all thirteen have in common

They are all XML, and where they are stored is a separate question

The content is XML. Where it lives can be swapped: a file on disk, or a row in a database table with the XML in a column. The framework reads through one interface, so changing the storage means no layer above has to know.

What gets used at run time is not that XML. The framework reads it and restores it into a definition object, and everything after that is a question asked of the object. The XML is only what it looks like while lying on a disk or in a database.

Once read, they stay in memory

What sits in the cache is those restored objects, one slot per definition, evicted by usage. Reading one resets its timer, and only a definition nobody has touched for a while is dropped.

The forms in daily use keep their definitions in memory almost permanently
The one opened twice a year is evicted not long after
The server does not carry the definitions of forms nobody opens

This is one of the returns on cutting definitions into separate pieces. The unit of caching is the unit of reading, so memory tracks actual usage rather than the total volume of definitions.

Keeping them does create one obligation: what happens when the source changes. Each cached definition watches its own source. A file is watched by modification time, and a database goes through a different notification mechanism. When the source changes, the next use reads a fresh copy. Cross-Node Invalidation for Definition and Data Caches takes this apart.

A definition you were handed must not be modified

Asking the framework for a definition gets you the shared one, not a copy. On the same server, every user gets the same object.

The price is that the object cannot be touched from then on:

Want a view for one user only, with captions in their language? Copy first, then modify.
Want to persist a change? Go through the framework's save method, which writes the file and invalidates the cache.

The only thing forbidden is modifying the shared copy in place, and that was always wrong anyway, since what it modifies is everyone's.

Missing comes in two kinds

The framework embeds a set of default definitions, and at run time they take no part at all. The framework reads only the definition directory you point it at. The embedded set is a starting point for a new project, copied in with a tool, once.

Not falling back is deliberate. If a missing FormSchema silently switched to the embedded one, the system would start up fine and then run on a definition you never deployed. "You forgot to deploy that file" would be rewritten into "the system does not behave the way you think," and the second one costs an order of magnitude more to track down.

But missing does not mean only one thing, so all thirteen are sorted into two kinds:

Kind	Behavior	Which ones
Missing means misconfigured	Report it immediately with a message naming the file	`FormSchema`, `TableSchema`, `ProgramSettings`, `PermissionModels` and the three boot files
Missing is a legitimate answer	Return nothing and let the caller take it from there	`FormLayout`, `LanguageResource` where the caption in the structure is used, `CurrencySettings` and `UnitSettings` where default decimal places apply, `MenuSettings` and `PluginSettings`

That classification lives in the code, and it has to be decided by the framework rather than interpreted by each application. Otherwise the same oversight shows up differently in different modules, one reporting an error and one quietly using a default, which is much harder to diagnose than both reporting errors.

6. The case study: copy it in, then add on top

Northwind uses the department and employee forms the framework provides, and the way it does that is the one time action from the previous section: copy the default definitions into the application's own definition directory.

After copying, the application added two fields of its own to employee. Those two lines are in the case study's Employee.FormSchema.xml:

<FormField FieldName="title" Caption="Title" DbType="String" />
<FormField FieldName="hire_date" Caption="Hire Date" DbType="Date" />

Once added, that definition belongs entirely to the application and can be changed however you like. Conversely, fields the framework later adds to its default definition will not appear on their own, and there will be no notice. Whether to follow along is your edit to make.

The framework's system fields cannot be removed. They are what the permission and organization mechanisms recognize.

This is what "definitions are data" looks like from a maintenance point of view. Copying a piece of data out and maintaining it yourself and branching a program and maintaining it yourself cost different things. The first has no merge conflicts and no need to carry trunk fixes across version by version, and the price is that new things do not follow along automatically.

Thirteen files, one truth

The shape of the thirteen is roughly this. Three decide what the system runs on, three describe one form, three decide who executes and where the entrance is, and four are shared data every form reaches for.

These are not thirteen configuration files. They are thirteen aspects of one truth. They point at each other, with DbCategorySettings pointing at DatabaseSettings, a FormSchema pointing at another FormSchema, and ProgramSettings and MenuSettings each pointing at the same program, and they do not collide, because each one answers only the question that belongs to it.

The next post, How FormSchema Drives SQL, is about which tables a query joins and which statements a save issues.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-04-definition-files

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 3: The Northwind Case Study: Eight Forms and a Custom Business Object

Jeff Tsai — Tue, 27 Oct 2026 02:01:08 +0000

The first two posts were about the argument. Today the case study comes on stage.

The case study is Northwind, Microsoft's sample database that has been passed down since the Access era. The reason for choosing it is practical: customers, suppliers, products and orders are tables most people recognize without explanation, so the conversation can go straight to what this structure puts the framework through, without first explaining what the business does.

This post covers:

The four conditions a case study has to meet before it can test a framework
Eight forms in three shapes, and the framework's system fields
Why relationships are declared between forms rather than between tables
The one form that needed code, and why it also came with a repository
What is inside that business object
The framework runs the standard flow; the application takes over only the part it cannot reach

First, what it looks like. This is the order, the most complex of the eight, rendered from one definition on four front ends.

Desktop	Browser

iOS	Android

One master with one detail. Customer, employee and shipper are all lookup windows that bring one record back, each detail row picks a product, and the amount is not typed by anyone. The four front ends share one UI project and read the same definition. Not one of those screens has screen code behind it. The only difference is the thin platform shell on the outside.

1. What a case study has to put a framework through

Framework demos almost all look the same: one table, fields in a row, create, read, update and delete work. That demo proves nothing, because every framework can do it. Not one of the places that actually break is on that screen.

A case study worth using as verification has to satisfy four conditions at once:

Forms have to vary in difficulty. A plain master, a master with cross table relationships, and a document with a master and details all have to be present. A framework that only holds up on the simplest of those is just a form generator.
Relationships cannot have only one shape. One table pointing at another is the basic case. You also need two tables pointing at each other, and an application table pointing at one of the framework's own tables, before the design of the relationship mechanism is forced into the open.
There has to be one form that needs custom logic. If a framework claims most things need no code, and its case study contains no code at all, that is not proof of the claim. It is avoidance of it.
It has to run on more than one front end. A layout definition that claims not to be tied to a UI framework does not get to make that claim until one definition has actually grown two or more different screens.

Northwind holds up on all four. Its complexity sits in a good place: complex enough to test the mechanisms, small enough that the whole thing can be laid out and reconciled item by item.

2. Eight forms, three shapes

Shape	Count	Forms
Plain master, meaning fields, a list and CRUD, with no relationships and no rules	4	Category, supplier, customer, shipper
Master with cross table relationships	3	Product, pointing at supplier and category; department, pointing at employee as its manager; and employee, pointing at department
A document with a master and details	1	The order

Department and employee point at each other. That circle was left in deliberately.

Eight forms map onto nine tables, since the order takes two. Two of those nine are tables the framework provides: department and employee. The permission and organization mechanisms use them, and the application copies their definitions over and uses them as they are. How framework tables and application tables are told apart, and which database each lands in, is the subject of Connections, Transactions and Query Conditions in the Data Access Layer.

These nine tables are not Northwind's original shape

What is borrowed is the business case and the sample data, not the table structure. The original Northwind uses business columns as primary keys, with CustomerID='ALFKI', integer product ids and a composite key on order details. This application kept none of that.

What went in instead are the framework's system fields, and the framework's mechanisms hang off these exact names:

Field	What the framework uses it for
`sys_rowid`	Cross table joins, the WHERE clause of UPDATE and DELETE, auditing, data scope permissions, and the row the user clicked on. All of them compare against this column
`sys_master_rowid`	How details are fetched, and how a whole document is saved together
`sys_no`	The primary key and the default sort order
`sys_id`	Gets a unique index automatically at table creation, which is what guarantees business code uniqueness
`sys_name`	The column shown in a lookup window

So these names cannot be changed, and that is not a naming convention issue. Everything listed above is what the framework uses them to recognize.

Two design decisions, and what they cost:

The primary key and the relation key are separate. The primary key is an auto incrementing sys_no; the relation key is a Guid in sys_rowid. A relation key has to be immutable, because a changed code must not break old documents, and it has to exist before anything is written to the database, because an order is saved in one go and the details need to point at the master first. The cost is one more unique index, and a fatter key.
Details do not use composite keys. If the shape of master and detail differed from case to case, the mechanism that reads and writes a whole document could not be common to every form.

One more cost, and this one is heavier: an existing system has to change its table structure before it can be brought in. Writing the definitions is not enough to run on the original database.

3. Relationships are declared between forms, not between tables

Traditionally a relationship is a table concern: the order table gets a customer column and a foreign key pointing at the customer table's primary key. What that declaration expresses is exactly what it says on its face, that the value in this column must be findable in that one.

The framework moves the relationship up a level:

<FormField FieldName="customer_rowid" Caption="Customer" DbType="Guid" RelationProgId="Customer">
  <RelationFieldMappings>
    <FieldMapping SourceField="sys_id" DestinationField="ref_customer_id" />
    <FieldMapping SourceField="sys_name" DestinationField="ref_customer_name" />
  </RelationFieldMappings>
</FormField>

RelationProgId="Customer" points at the customer program, not at the ft_customer table. No table name appears anywhere in that declaration. Which table to join is something the framework works out by taking that identifier and looking up the customer's own FormSchema.

Pointing at a form and pointing at a table can connect to very different amounts of information:

A table knows only which columns it has
A FormSchema also knows which columns the list displays, what a person sees when picking from a lookup window, which fields are queryable, and whether it wants to add conditions of its own, such as listing only active suppliers

So once that one declaration is written, four things are in place at once:

The field automatically becomes a lookup window editor on screen
Picking a record fills the customer code and name back in
When querying the list, the framework assembles the join that fetches those two columns
What the database stores is the relation key

Traditionally those four are recorded in three places, the foreign key in the database, the picker configuration on the front end, and the join in the query layer, and all three can disagree.

There are no foreign keys in the database

The framework does not create foreign key constraints. Those three relationship columns on the order have only indexes in the database.

That follows necessarily from moving relationships into the definition layer. The relationship's authority is the definition, and the database is a projection of it. Creating a foreign key as well would give that one declaration two sources, and two sources eventually disagree.

The cost: the database will not block orphaned rows for you. If someone deletes a customer with raw SQL, the orders pointing at it are not stopped. Whether that is acceptable depends on whether your database is written to by this application alone. The assumption that definitions are the single source of truth has to be carried all the way down to the database. You cannot give half of it to definitions and half to constraints.

Display columns are not the authoritative value

The two fields ref_customer_id and ref_customer_name do not exist in the table.

The physical order table holds only the customer's relation key
The code and the name are joined in by the server at query time
When the front end finishes picking, it writes the values into the data it is holding, purely so the screen updates immediately. They are not persisted on save
If the customer changes its name, the value shown on the order is correct on the next read

A typical trade-off: one more join per query, in exchange for the screen always showing the current value. The cost is that there has to be an explicit rule about which side is authoritative, and that rule has to be set by the framework rather than decided by each form separately.

How many this application declares

Eight, counted directly. Three on the order master, being customer, employee and shipper; one per order detail row, being the product; two on product, being supplier and category; one on employee, being department; and one on department, being the manager.

The three cross table relationships mentioned in the first post are the three on the order master, and that is also the scope used for reconciliation later.

One of the eight crosses a line. The employee an order points at is one of the two framework tables mentioned above. The salesperson on an order is the framework's employee, and the application does not build an employee table of its own.

Why the circular relationship was left in

Department points at employee, for the manager, and employee points at department. In the data model that is a circle. It was left in deliberately, because any mechanism that grows something out of definitions needs a defined answer for circles:

Generating strongly typed classes at build time: the circle forces a type initialization ordering problem into the open
Assembling queries dynamically from definitions at run time: the circle only affects how many levels that one query joins

This is the first post's build time versus run time distinction, projected onto the data model.

4. The order: the one form that needed code

Seven of the eight forms have zero lines of application code. On the registry those seven declare only a program identifier and a display name, which means they run the framework's default flow. Only the order row names two types:

<ProgramItem ProgId="Order" DisplayName="Orders"
             BusinessObject="...OrderBO, Bee.Northwind.Server"
             Repository="...OrderRepository, Bee.Northwind.Server" />

The two types cover one area each. The business object holds this form's business logic, and the repository holds its data access.

That repository exists for exactly two SQL statements: reading the order's current state as stored in the database, and finding the highest order number this month. The rest of CRUD is still assembled by the framework from the definition.

Putting those two in the repository rather than in the business object is not layering fastidiousness. A business object would have to name the database it connects to itself, whereas a repository is resolved from the FormSchema category plus the current session, and lands automatically in the right company's database. Whoever writes it does not need to know how many companies the system has.

5. What is inside that business object

The order's business object overrides two methods, and the step before saving does four things:

Check that there is at least one detail row
Sum the detail amounts back into the master total
Generate the order number
Check that the status transition is legal

All four look like business logic. Run them through the test from An Overview of Definition-Driven Architecture, would every ERP in the world do this the same way, and only the last one is.

The first three are general. That a document needs at least one detail row, and that the total equals the sum of the details, is established practice. An order number of a prefix plus year and month plus a sequence is the kind of numbering rule most ERPs turn into a configurable mechanism. All three should converge into mechanisms. They live in the application today because the framework has not absorbed them yet.

The last one is the business judgment. Status goes from draft to confirmed to shipped, no skipping and no going back, and details lock once confirmed. That rule differs at every company, since some allow quantities to change after confirmation and some have two more intermediate states, so the application should own it.

That line has moved before

The business object used to do more than those four. Two batches have already moved out:

The amount on each detail row used to be calculated in code. It is now one expression on the field
Three checks, that customer and product are required and quantity is greater than zero, used to be in code. They are now three rules in the FormSchema

<FormField FieldName="amount" DbType="Currency" NumberKind="Amount" ReadOnly="true"
           ValueExpression="quantity * unit_price * (1 - discount)" />

What was saved by moving them is more than those lines. The expression is recalculated the moment the user changes the quantity or the discount, so the front end does not have to write the same calculation a second time to make the amount update live. One formula, declared once, computed correctly on both ends.

One of them went further still: who is able to change it also changed. How the amount is calculated now lives in a definition, so adjusting it means editing a definition file rather than going back to the code side. Every time something moves from code into definitions, the people who can change it move one step closer to where the requirements are. What used to need a slot in the development schedule becomes one line of arithmetic that someone who understands the business can read, and edit.

So the line between what needs code and what does not was never drawn once at the start. It moves forward as the framework's declarative power grows. Of those four items, the first three will be absorbed sooner or later, and only the last will remain.

What stays in code is partly what belonged there all along, and partly what has simply not been taken over yet. Mixed together they look alike. Separated, you can see which one to absorb next.

6. The framework runs the standard flow, the application takes over what it cannot reach

What the framework owns is everything that is the same on every form: query the list, open a record, create, update, delete, pick from a lookup window, validate before saving, and deliver data to the front end. The shape of those does not change with the form. What changes is which fields exist, and the fields are in the definition. Governance is the same story: who may access it, which rows they can see, and who changed what and when.

That is why those seven forms have no application code.

At this point a doubt usually surfaces, and it should. If the whole flow is standardized, what happens to flexibility?

That question matters far more than how much a framework can do. Setting a standard is not hard. What is hard is still having room for exceptions afterwards. Without that room, the first special requirement means carving out the entire flow yourself, and everything saved earlier is handed back. In the case study, the form that runs into this is the order.

There are two ways to take over:

Approach	Mechanism	Nature
Inherit and override	The framework's business object cuts the whole flow into a sequence of overridable steps, being fetch a new record, before save, the save itself, and after save, with delete cut the same way. The application changes only the steps it needs. The order changed two	Replacement, and there is one implementation per program
Hook in a plugin	The framework opens four points around save and delete for external logic	Layering, several can stack, and the customization chain runs after the packaged one without touching the original program

What the two have in common is the answer to that doubt: what you take over is one short segment of the flow, not the whole flow. Overriding "before save" does not suddenly make you responsible for assembling SQL or delivering data to the front end.

Flexibility is not about the framework being able to do everything. It is that you only have to handle the part that differs from how the mechanism does it, or that the mechanism does not support yet. Whether a standard flow and its exceptions can coexist comes down to that granularity. Cut too coarsely and one exception means rewriting the whole thing. Cut finely enough and the standard parts keep working for you.

Back to a claim from the first post

The first post, Why ERP Needs a Definition-Driven Framework, said that across the whole Northwind application, only one of the eight forms needs code written for it. That form is the order, and it needs to take over not because it is more complex, but because it runs into the few things the current mechanisms cannot reach. A case study needs a form like that, or the claim that most things need no code has never been tested.

And handling them takes overriding the two steps the framework cut out, without leaving the standard flow. That room is necessary. A mechanism must not standardize a flow by taking flexibility away. Many of the special cases in an ERP are not badly written requirements. They are what that company's structure and working habits actually look like, and they do not disappear because a framework set a standard. How deep a takeover can go is cut into several levels, and Three Depths of Development and the Big Picture of the Framework lays all of them out.

This is the state definition-driven design is aiming at. Not writing no code, but writing it only where a judgment is genuinely required, and taking over only that one segment when you do.

The next post, The Purpose and Classification of Definition Files, moves into the definition layer, starting with an account of all thirteen kinds of definition file.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-03-northwind-case

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 2: An Overview of Definition-Driven Architecture

Jeff Tsai — Mon, 26 Oct 2026 03:11:15 +0000

The previous post, Why ERP Needs a Definition-Driven Framework, ended by promising this one would be about which decisions a framework should make on its users' behalf.

The difference between a framework and a library is usually explained as "you call a library, a framework calls you." That describes the mechanism, not the price. The real price is that once control is inverted, the framework's defaults become your defaults. It decides what data looks like, how a request flows, and where the extension points are. You are free to disagree, and the cost of disagreeing is working around it, which is usually more expensive than not using it at all.

So the question to ask about a framework is not what it can do. The more things it can do, the fewer decisions it has made for you, and the same decision has to be made again for every single form.

This post answers the four questions a definition-driven framework has to settle first. Every other design choice is a consequence of these four answers:

Which layer holds the single source of truth
Which layers are derived from it
What is left to the application
Where this whole approach does not hold

None of the four can be left blank. If the framework does not answer them, the people using it will answer them individually, and their answers will not agree. This module puts the truth in an entity, that one puts it in the table, a third puts it in a form configuration file on the front end. A good part of the three long-standing problems from the previous post grows out of exactly that.

1. Which layer holds the single source of truth

First, a distinction that is easy to blur: a Code-First stack is not short of definitions. The API contract is a definition, the migration script is a definition, so is the database's own metadata. The difference is not whether definitions exist. It is which way the arrow points. Those definitions are dumped out as products. Editing them is meaningless, because the next generation run overwrites them.

So the question is not whether to have definition files. It is where the arrow should point, and there are only three candidates:

Candidate	Paradigm	The catch
Code	Code-First	A type system is wide enough to hold any semantics you can think of. The price is that the only reader of the truth is the compiler, and changing the truth means going through compilation, packaging and deployment
The database	Database-First	Data is the final fact, but the type system is too narrow
Definitions	Definition-Driven	Has to satisfy two conditions at once

Where the database is narrow: it knows that total_amount is a decimal(18,4), but not whether that number is an amount, a quantity or an exchange rate. It does not know whether the value should be rounded, how many digits to show, whether it is required, whether it can be edited, or whether it belongs in the query list. Those semantics have nowhere to live, so they end up somewhere else, and the truth has scattered again.

For definitions to be the truth, two conditions, neither optional

Wide enough to carry semantics beyond structure
They are data, not code, which was the whole subject of the previous post

In this framework, what a single field can declare falls into six categories:

Category	What is declared	Can the database hold it?
Structure	Field name, data type, length, default value	✅
Behavior	Required, read only, visible	Partly
Presentation	Caption, control type, display format, width	❌
Semantics	What kind of number this is, which field carries the currency, which field carries the unit of measure	❌
Relationships	The related form, the field mapping, the display field	❌
Security	Data scope roles, sensitive data classification	❌

Code can hold all six, but only as a stack of attributes, and once they are stacked someone still has to parse them back into data before anything can use them.

The width of that declaration is deliberate. It has to cover the UI, the database and validation in one pass.

A single source of truth is not a claim, it is a dependency direction

Any framework can write "this framework treats X as the single source of truth" in its documentation. To verify it, the dependency direction is enough: the layer holding the truth should depend on nobody, and everybody should depend on it.

The definition layer package has an extremely short reference list. It does not know a database exists, or HTTP, or a UI. In the other direction, data access, business logic, the API contract, the client, and every front end all reference it.

That direction buys two things:

The definition layer can be processed by tools on its own. A definition editor, a generator, a batch checking script: each needs to reference only this one package, without dragging in the entire database and API stack. The claim in the previous post that a thousand definitions can be swept by one script rests on this.
AI benefits too. To make it understand a system, feeding it the definitions is more efficient than having it scan the whole code base, and the conclusions are more reliable. The difference is not file size. It is whether relationships are declared or inferred. Ask which forms an order touches, and reading the definitions means reading relationships that were already declared; reading the code means chasing types, chasing queries, chasing configuration, and then inferring intent, and inference gets things wrong.

The tokens saved are a side effect. As for the business judgments that definitions do not cover, the code still has to be read.

2. Which layers are derived from definitions

The previous post used plain language: the UI, the database, CRUD SQL, validation rules. The precise list comes in two kinds. Most of it is generation:

What is generated	From
The single record form layout	The form structure (master block plus detail block)
The list layout	The list fields the form structure declares
The lookup window layout	The queryable fields the form structure declares
The physical table structure	Every table in the form structure
INSERT / UPDATE / DELETE	The form structure's field set
SELECT, including cross table joins	The form structure's fields and declared relationships
The structure of the data container that crosses layers	The form structure's field set

The other kind is evaluation. Here the framework does not build anything; it takes the rules and expressions declared in the definition and evaluates them. Validation rules are evaluated at save and delete. Computed fields are recalculated the moment the user changes a field they depend on.

When a requirement converges into a new shared behavior, a matching mechanism grows. The query criteria screen for a report, for example, is essentially a set of fields plus editors, and a layout definition can describe it.

Grouped by who consumes it:

Form structure definition
│
├─ Generates
│   ├─ Three layouts: single record / list / lookup window  ->  screens on every front end
│   ├─ Physical table structure  ->  the database
│   ├─ Two kinds of SQL: write / query, including cross table joins  ->  data access
│   └─ The cross layer data container structure  ->  transport
│
└─ Evaluates
    ├─ Validation rules  ->  at save and delete
    └─ Computed fields  ->  the moment a dependent field changes

Generating code, or generating objects

Growing something out of a definition at build time and at run time produces completely different results:

A build time generator produces code. When the definition changes, you regenerate, recompile and redeploy. Not one step of the delivery path from the previous post has been removed, and everything saved earlier is handed back at the final gate.
Run time derivation produces objects in memory. Swap the definition, and the next read is the new one. This is exactly where "no compilation, packaging or deployment between changing a definition and having it take effect" holds.

Two things are paid for it:

Compile time type checking is gone. A misspelled field name is not discovered until run time, and how that debt gets repaid is the subject of Data and Definitions Split Apart, So Forms Need No Types of Their Own.
Cache invalidation goes from an optimization to a problem that must be solved. Definitions will be cached for performance, so the framework needs a notification mechanism that carries a definition changed on one node out to every other node.

3. What is left to the application

Where the framework should stop has two rules, one positive and one negative.

The positive one: any behavior that is standardized and repetitive should converge into a framework mechanism.

This is not merely about writing fewer lines:

There is one way to do each thing, and a fix goes in one place, which saves maintenance
New joiners, consultants and whoever inherits the system learn it once, and understanding one form means understanding all of them, which saves training and is the most commonly underestimated of the two

The symptoms of losing control listed in the previous post are all invoices issued by the absence of a general mechanism, and they are reissued per person, per year.

The negative rule is a single test: would every ERP in the world do this the same way? What is the same belongs to the framework. What differs belongs to the application.

By that line the framework stays out of three areas:

Business judgment: how a status transitions, when shipping must be blocked. Every company differs.
SQL for reports and batch jobs: multi table joins, aggregation, dynamic criteria, performance tuning. Forcing these into definitions only makes them more complicated.
The application shell: the login screen, connection settings, navigation menu, windows and theme.

Staying out is not the same as ignoring. Having handed those three over, the framework picks up two obligations it must get right:

A registry that maps a form identifier to the class you wrote
A few extension points at unambiguous positions, so your logic can hook into the save and delete flows

How well those two are done decides directly whether the application is pleasant or awkward to write, and a later chapter takes them apart.

Handing work over does not reduce complexity either. What definitions can absorb is repetition, not the inherent difficulty of the business. The hard parts have not disappeared. They have been concentrated in one place and given to whoever knows why they are hard.

The third area is clearest in the case study. The Northwind front end has one UI project shared by every front end, and only four hand written screens: the main window, login, connection settings, and the layer that hosts forms. All four are shell. Not one of the eight business forms needs screen code.

You can see where the line is drawn at a glance: the hand written part is precisely the part definitions did not take over.

4. Architectural patterns: three sources, one piece from each

With the first three questions answered, the shape of the framework is fixed. Before the fourth, one description that gets applied to it deserves handling: a hybrid of N-Tier, Clean Architecture and MVVM. "Hybrid" turns into a decorative word very easily, so here is what was taken and what was not.

Source	What was taken	What was not
N-Tier	The layer boundaries and the cross layer data container. One request travels front end, API, business object, repository, data access infrastructure, database, and each layer knows only its neighbor. The most completely taken of the three	Nothing
Clean Architecture	The inward dependency direction from the first section, verifiable by opening the project reference lists	Its requirement on the domain. The pure approach gives every business concept its own strongly typed domain entity, and modeling a thousand tables one at a time is the scale cost from the previous post itself
MVVM	All three roles are present. The model is the cross layer data container, the view is rendered from the layout definition, and the view model is a framework provided `DataObject`	Nothing; the only difference is who writes the view model

That DataObject carries the full job: wrapping the data container, exposing field reads and writes for screen binding, raising notifications for value changes and unsaved state, managing the start and cancellation of detail row editing, and loading, saving and deleting against the back end. The difference is that it is not hand written per form. Its shape comes from the definition. The price is that the screen binds not to a property like order.CustomerId but to a field name.

The cross layer data container is not a custom type either, and a later post is devoted to what that choice costs.

5. Systems this should not be applied to

Three questions before you commit. If any one of them does not survive, seriously consider not applying this.

Q1: Are your screens standardized forms?
Definitions can drive layout only because the layout patterns converged, and what converged here is a block of master fields plus a detail block. Dashboards, charts, drag and drop scheduling and maps are not in the pattern. The framework's answer is not "we support those too." It is that this road does not go through definitions, and you write it yourself.

Q2: Is your request a single document?
The cross layer data container is self describing, and the price is that every response carries the field structure with it. For one order that is worth it. For an event stream at tens of thousands per second it is not.

Q3: How long does your system have to live?
The cost is concentrated up front and the return does not show for three to five years. A system that ships, closes and gets rewritten wholesale three years later pays the cost and never collects.

Not many scenarios satisfy all three at once, and internal enterprise management systems happen to hit every one. Finance, purchasing, inventory, sales, HR, customer relations: the screens are almost all standardized forms, the requests are almost all documents, and once it goes live it lives a long time.

These boundaries are not "the framework has not got there yet." They are places where getting there would make things worse. A framework that can do anything has made no decisions for you, and the decisions are exactly where a framework's value is.

The Northwind case study: how much one definition does

The order in the case study has a single form structure definition, and it states:

One master with one detail
Three cross table relationships on the master, to customer, employee and shipper, each a lookup window that brings one record back
Each detail row picks a product
Amounts are not typed by anyone. They are calculated from quantity, unit price and discount
Three validation rules have to pass before saving

Once that one definition is written, everything in the table from the second section is in place. The tables are created from it, the list and lookup window layouts grow directly out of it, the write and query SQL is assembled by the framework, the data carries its structure with it across layers, and the validation rules are checked at the moment of saving. Not one of those requires additional code.

The same definition is read by four front ends: desktop, browser, iOS and Android, all sharing one UI project.

The value of a framework is not how much it can do. It is whether it can tell which decisions belong to it: the thing that is identical a thousand times over is its, and the thing that differs every time is yours. Draw that line crooked and both sides carry the weight. Draw it too conservatively and you redo the same work a thousand times. Draw it too greedily and you spend more effort working around it.

The next post, The Northwind Case Study: Eight Forms and a Custom Business Object, brings the case study on stage.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-02-framework-decisions

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 1: Why ERP Needs a Definition-Driven Framework

Jeff Tsai — Sun, 25 Oct 2026 05:35:42 +0000

This is the first post in a thirty-part series, ERP Architect's Notes: Designing a Definition-Driven Framework.

What follows is not about building one form with some framework. It is about designing a framework that can drive hundreds of forms: which decisions it should make on your behalf, which ones it should leave to you, and why each mechanism ended up shaped the way it is. Every claim is checked against a working application built on the Northwind sample database, but the case study is evidence, not the subject.

This post covers:

The three layers of ERP development cost: a single change, scale, and delivering customization
The three long-standing problems those layers converge on, and why tooling does not remove them
The point where the paradigms diverge: is the single source of truth code, or definitions?
A controlled experiment: how many places does one field touch under each paradigm?

Who I am

I have spent more than twenty years as a software architect in packaged ERP and HRM products. Packaged software has a very long product cycle, ten or twenty years is normal, and over that span the system is not merely maintained. It has to grow a new face every time the front-end generation turns over. I have been through three of them: desktop, web, and mobile apps. Each time the question was the same. Do we rebuild all several hundred screens?

On a product line like that, an architectural decision does not get rewritten by someone else three years later. You watch it grow for ten years and then keep maintaining it. I stayed in the same role the whole time. I never moved into managing projects or teams and left the code behind, so I did not miss the consequences of a single one of those decisions.

About the framework, and about this series

Some of the ideas I accumulated over those years were built inside real projects. More of them were only ever thought through, because writing all of it alone was never worth the cost. That cost is different now. I used Claude Code to build the ones I never got to, and the result is an open source framework, bee-library. The Northwind case study in later posts runs on it.

The case study itself lives in a separate repository, bee-northwind-avalonia. The framework repository holds the mechanisms; the case study repository holds only the application's own definition files and code, with the framework pulled in as a package. If you want to know what applying this framework actually requires, which definition files you prepare and what code you still have to write, the case study repository shows it more clearly than the framework does.

The framework is still moving. Things that deserve to become mechanisms will keep being folded in, interfaces will change with them, and breaking changes will happen. If you want to reference the packages directly today, that has to be part of your calculation. You can also clone the whole thing and shape it into what you need.

This series is not a manual for it. The framework has exactly one job here: to show that these ideas are not just talk. What the thirty posts discuss is the mechanisms that already exist, what problem each one ran into, how it was solved, what it cost, and why that option rather than another. Implementation details are not walked through line by line. You are entirely free not to use it, and to take only the idea that definitions should be the source, and build it in whatever language and tools you already know.

The whole series rests on one sentence:

The complexity of an ERP is not in how hard any single feature is. It is in how many times the same fact gets restated, multiplied by how many tables, multiplied again by how many customizations.

1. The cost of a single change: how many places one field lands in

The requirement: orders need one more field, Required Date. No calculation, no dependent behavior, no effect on existing logic. The user says this is "just one field, it should be easy," and the user is right.

In a typical Code-First stack, ORM plus web API plus front end, that field lands in thirteen places:

#	Location	What changes
1	Entity class	Add a property
2	Type mapping configuration	Precision, nullability, column name mapping
3	Migration	Generate it, review it, commit it, run it at deployment
4	Query projections	The `Select` for list queries, the column list for reports
5	DTOs	Once for the request, once for the response
6	Mapper configuration	Entity to DTO
7	Validation	Required, range, ordering relative to the order date
8	API contract	The OpenAPI schema, republished to consumers
9	Front-end types	A TypeScript interface or a C# model
10	Front-end form	Control, label, position in the layout
11	Front-end list	Column, width, sorting
12	Localization resources	One per language
13	Test data	Fixtures, seeds, fake data generators

To be fair, several of those can be generated. Migrations come from a tool, OpenAPI is produced by scanning assemblies, front-end types can be generated from OpenAPI. The number you actually hand write is closer to five or six.

But the number you hand write is not the point:

The single fact that "Required Date is a date, it is required, and it shows after the order date" has been restated thirteen times in this stack.

Every restatement is a place where the copies can disagree:

Forgot the DTO, and the value reaches the database but never the front end
Forgot the validation, and users submit it empty
Forgot the list column, and users ask why they cannot see it on the query screen

None of these are hard problems. They are counting problems, and each inconsistency has to be found by a test or by a user report.

A team boundary runs straight through that table

Items 1 through 8 are back end. Items 9 through 13 are front end. If those are two teams, the line cuts through the middle of the table, and every item that crosses it changes character. It stops being editing and becomes coordination.

A request to add one field then grows into this:

A meeting to agree the contract first, then separate scheduling on each side
Sequencing: until the back end ships there is nothing for the front end to consume, so starting early means hand rolling a mock
Release windows: whichever side goes first has to cope with the other not having caught up
And during integration, the discovery that one side read "required" as a front end block and the other read it as a back end block

Not one of those activities is writing the field. What they consume is not effort, it is waiting. The user counts the time from asking to shipping; the engineer counts the time actually spent working. So one side asks why changing a single field takes this long, and the other side does not feel it was slacking. Both are right, because the cost is real, it just does not land on the part where anyone is typing.

2. The cost of scale: multiply that table by a thousand

A full packaged ERP covers finance, purchasing, inventory, manufacturing, sales and HR. Business tables run into the thousands.

The founding premise of an ORM is that objects map to tables, so:

thousands of business tables
  -> thousands of entity classes
  -> plus DTOs, usually more than one: List / Detail / Create / Update
  -> plus mapper configuration
  -> plus repositories

The overwhelming majority of those classes resemble each other. The entity for Supplier and the entity for Shipper differ in field names and field count; structurally they came from the same mold.

This is not an argument that ORMs are bad. An ORM works well in the setting it was designed for. The problem is quantity. When the same pattern has to be copied a few thousand times, the copying itself becomes the dominant cost.

Relationships then multiply that quantity again:

ERP tables are densely connected by nature. An order points at a customer, a salesperson and a shipper; a shipment points at an order, a warehouse and a lot number.
Every one of those relationships needs someone to decide how it is expressed, how it is loaded, and who maintains it. Each decision is reasonable on its own. Spread a few thousand tables out at once and nobody can hold the whole picture.

Take the thirteen slots from the first section and multiply them by a few thousand, and multiply the team boundary along with them. Cross team coordination is not paid once per table, it is paid once per request, and the number of requests is itself proportional to the number of tables.

This is not inconvenience. It is loss of control. Anyone who has maintained a large system recognizes the symptoms:

Nobody dares touch shared classes, because nobody is sure who depends on them
New joiners take a long time before they will go near core modules
The same concept has several different spellings across modules, because different people grew them at different times

3. The cost of customization: how do you deliver it once it is done

The first two layers are about how much work a change takes. The third one is more fundamental, and there is no way around it, because:

An ERP that gets installed and simply used essentially does not exist.

Every rollout comes with customization. This client numbers documents differently, that one calculates cost differently, this department wants two extra fields, that report needs a different grouping. The only variable is the path the customization travels down.

Under Code-First, all thirteen of those places are code, and code has exactly one delivery path:

edit -> compile -> test -> package -> deploy

The same path hurts in three different ways depending on the deployment shape:

Deployment shape	Where customization hurts
A single organization's internal system	The simplest case: schedule one maintenance window. But changing a decimal scale from 2 to 4 still means a full build, test and deploy
Packaged software sold to many customers, each with their own deployment	Only two options. Put it in the trunk behind a switch, and the switches accumulate until nobody dares delete any of them. Or branch, and every branch evolves on its own while every fix in the trunk has to be carried across one at a time
Multi-tenant SaaS on shared assemblies	Tenant A changes one formula, and that means coordinating a maintenance window across all tenants and regression testing every tenant's functionality. If any one tenant breaks, the whole batch rolls back

Three shapes, one conclusion:

The size of the requirement and the cost of delivering it have come completely apart.

Whether the requirement is changing a decimal scale from 2 to 4 or reworking an entire module, it travels the same delivery path and carries the same deployment risk. The result is that small requirements have to be scheduled into the release rhythm too, and the engineering team is forced to treat every change as a significant event.

The root of that decoupling is that customization was expressed as code. The deployment shape only decides how much it hurts. It does not decide whether it hurts.

This layer is what definition-driven design is actually for:

Definitions are data, not code. Changing data requires neither recompilation nor redeployment of assemblies.

4. Three problems that never got solved

The costs from the first three sections converge into these:

Long-standing problem	Symptom
Specifications scattered across three layers	The same field is defined once in the UI, once in the DTO and once in a database migration, and they drift apart easily
Business logic scattered	Different modules are maintained by different engineers, styles diverge, and the same work gets done more than once
Customization that resists standardization	Custom logic cannot flow back into the standard product, and accumulates as technical debt nobody can govern

For the past twenty years the usual answer has been more tooling: code generators, project templates, smarter mappers, more automatic migrations. Those tools genuinely made each restatement cheaper.

What they did not change is the structure in which one fact gets restated thirteen times. They only made restating it faster.

For the third layer, customization cost, tooling helps even less. Generated code is still code, and still has to be compiled and deployed. The reason the third problem has been open for twenty years is right here.

5. Where the paradigms diverge

The problem is not the tooling. It is the paradigm. There is only one question to answer:

Is the single source of truth in this system the code, or the definitions?

Code-First: the entity class is the source. The database is derived from it through migrations, the API contract is derived from it through OpenAPI, and front-end types are derived from that. Definition files are a by-product.
Definition-Driven: a structural description is the source. The UI, the database, the CRUD SQL and the validation rules are all derived from it. Code appears only where a real business judgment has to be made.

The difference is not that a file extension changed from .cs to .xml. It is the nature of the source:

	Code is the source	Definitions are the source
How a thousand tables are represented	A thousand classes	A thousand definition records
What you can bring to bear on them	Compilers, IDEs, refactoring tools	All of that, plus batch scripts, generators, programmatic checks, and AI
The delivery path for a change	Compile, package, deploy	Swap in a different definition
How customization is represented	Branches or switches scattered through source	A layer of data stacked on top of the standard definition
How the front end learns which fields exist	A second, hand-written set of types kept in sync by contract and by people	Fetching the same definition at run time
What a new front-end generation costs	Rebuilding every screen	Writing one new rendering layer
Who can change it	Developers	Developers, consultants, tools, and even users

Two of those rows deserve more than a line:

A thousand classes and a thousand definition records are the same count, but managing them is not the same order of magnitude. A thousand structurally identical XML files can be swept by one script that checks whether every amount field has the right decimal scale. That takes minutes. Doing the equivalent check across a thousand classes is considerably harder.
Generational cost is the one I feel most strongly. Front-end technology turns over roughly every ten years. If screens are written by hand one at a time, a generation change means rebuilding all of them. If screens grow out of definitions, a generation change means writing one new rendering layer. The more forms you have, the wider the gap.

That is also the reason layout deserves to be its own layer of definition. Structure is stable and follows the business; layout is volatile and follows the front-end generation. Once they are separated, what gets rewritten at generation change is the rendering layer, not the thousands of structural definitions.

6. A controlled experiment: how many places for the same field

Back to adding Required Date to orders. I counted it in this series' case study application, and the answer is three definition edits and zero lines of code.

Table structure:

<DbField FieldName="required_date" Caption="Required Date" DbType="Date" />

Form structure:

<FormField FieldName="required_date" Caption="Required Date" DbType="Date" />

Layout:

<LayoutField FieldName="required_date" Caption="Required Date" />

What follows automatically after that: the database column, the form control, the list column, the SQL for insert, update and delete, and transport across layers.

No entity class to keep in sync, because the SQL is assembled from the definition at run time
No DTO or mapper to keep in sync, because the data crossing layers carries its own structural description

The count moves by one in either direction depending on the situation, but the count is not the point. The point is that all three places are definition data.

What happened to the team boundary

The front end no longer declares the field a second time. It asks the back end for that definition at run time and renders accordingly:

front end starts -> asks the back end for the definition -> grows controls, list columns and validation from it

The contract does not have to be negotiated, because the contract is that definition. There is no second copy that could disagree with it.
There is nothing to wait for. The back end changes the definition, and the front end gets the new one the next time it asks.
The coordination, scheduling, sequencing and release windows from the first section mostly just disappear.

What is left is half of the first step: what this field is called in business terms, where it goes, and whether it is required. Somebody was always going to decide that. It is a business judgment, not communication overhead.

The boundary has not vanished, though. It moved.

The front end still needs a rendering layer that knows how to read definitions, and somebody has to build it. The difference is that it gets built once, and after that every form and every field is free.
The team boundary drops from "every field" down to "the rendering layer," and the frequency of conversation changes from "every request" to "whenever framework capability changes."
Anything that genuinely cannot be declared as a definition still has to be discussed. A rule about when a document may not be shipped still needs someone to decide who blocks it, at which layer, and what the message says. No architecture escapes that. What definition-driven design can eliminate is structural restatement, not semantic negotiation.

After the change lands

Two practical problems remain, and the framework has to absorb both:

The physical database does not have that column yet. The framework compares the definition against the actual structure and adds the column, so nobody hand writes a migration. A later post takes this apart.
The system is running, so how does it know the definition changed? The node that edited the definition has to be able to notify the others so their cached copies are invalidated. Cross-Node Invalidation for Definition and Data Caches covers that.

The point is one sentence: between changing a definition and having it take effect there is no compilation, no packaging and no assembly deployment.

7. A map of the thirty posts

Chapter	Theme
One (posts 1 to 3)	Why Definition-Driven
Two (posts 4 to 8)	Definition Layer
Three (posts 9 to 12)	Data Access and Caching
Four (posts 13 to 18)	Business Logic and API
Five (posts 19 to 21)	Multi-Tenancy and Customization
Six (posts 22 to 25)	Transport, Security and Audit
Seven (posts 26 to 28)	Data Semantics
Eight (posts 29 to 30)	Case Review and The Big Picture

Every post is written roughly the same way. First what the problem requires you to weigh, then how the framework is designed and why it was designed that way, and where a case study can verify it, a closing section with the actual Northwind definitions.

Two things to be clear about up front:

The subject is long term cost, not development speed. In the short term Code-First wins almost every time: mature tooling, a complete ecosystem, a fast start. The cost of definition-driven design is concentrated at the beginning, and the return does not show until year three or year five. If your system ships, closes, and gets rewritten wholesale three years later, this series is of limited value to you. It is written for people who know they will be maintaining something for a long time.
Trade-offs and costs will be written as plainly as benefits. The value of a framework is not in what it claims to do. It is in knowing precisely what it does not do, and why. Highly dynamic UIs, dashboards, reports and anything that is not form-shaped will only hurt more if you force them into this model.

A thread to pick up later

The next post, An Overview of Definition-Driven Architecture, is about which decisions a framework should make on its users' behalf. The one after that, The Northwind Case Study: Eight Forms and a Custom Business Object, brings the case study on stage.

The case study builds a complete application out of Northwind: eight forms, master-detail, three cross-table relationships, validation, all of it. Exactly one of those forms needs code written for it. What is inside that one, and which places we deliberately chose not to express as definitions, gets reconciled item by item in Which Part Definitions, the Framework and Application Code Each Own.

The enemy of ERP is not complexity. It is restatement. And the reason tooling cannot eliminate restatement is that restatement is a product of the paradigm. As long as code is the source, the same fact is condemned to be said many times over.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-01-why-definition-driven

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

Jeff Tsai — Tue, 13 Oct 2026 12:09:53 +0000

JSON-RPC 2.0 is a small specification: the client sends {"jsonrpc":"2.0","method":"...","params":{...},"id":1}, and the server answers with a result or an error. REST makes you decide on routes, HTTP verbs and status codes; JSON-RPC only cares about which method to call and with what parameters. For an API where you own both the front end and the back end, that is pleasant to work with.

Polhem.JsonRpc is a set of .NET packages for JSON-RPC 2.0: a transport-independent server, an ASP.NET Core endpoint and a client, built on System.Text.Json alone. It started as the API layer of the Polhem framework. I have now extracted it into standalone packages that do not depend on the framework, so other projects can reference them directly. The source is on GitHub under the MIT license, and the packages are on NuGet.

1️⃣ What it covers

Full JSON-RPC 2.0: ordinary calls, notifications (calls that expect no response), and batches (several calls in one message). An id can be a string, an integer or null.
A transport-independent server: the dispatcher (the part that finds and runs the method) knows nothing about HTTP. The ASP.NET Core endpoint is a separate package.
A client: an HTTP transport, batches, notifications, and interceptors that can rewrite the parameters and result of each call.
Optional payload encryption: the parameters and result go into an envelope that can be compressed and encrypted, and replayed calls can be rejected.

It is split into several NuGet packages, so an application references only what it needs:

Package	Use
Polhem.JsonRpc	Message types, error codes and the transport abstraction shared by the server and the client
Polhem.JsonRpc.Server	The dispatcher: method resolution, parameter binding and filters
Polhem.JsonRpc.AspNetCore	The ASP.NET Core endpoint, `MapJsonRpc`
Polhem.JsonRpc.Client	The client, `JsonRpcConnector`
Polhem.JsonRpc.Payload	Optional: the payload envelope, compression, encryption and replay protection
Polhem.JsonRpc.Payload.Client	Optional: a client that seals the parameters and opens the result of every call
Polhem.JsonRpc.Payload.Server	Optional: opens the envelope and checks for replays on the server

The server references Polhem.JsonRpc.AspNetCore, and the client references only Polhem.JsonRpc.Client. The split keeps a client, whether a desktop app or a mobile app, from pulling in ASP.NET Core and the reflection-based dispatcher.

Native AOT compiles an app to native code at publish time, so nothing can rely on reflection at run time; iOS and WebAssembly both need it. The shared package, the client and the payload packages are marked AOT-compatible, and CI publishes a test program with Native AOT and runs it. The server package finds methods by reflection, so it does not support AOT. The target framework is net10.0.

2️⃣ Getting started

ASP.NET Core server (Minimal API)

The server uses ASP.NET Core Minimal APIs (endpoints mapped directly in Program.cs with MapXxx, without MVC controllers). MapJsonRpc creates a POST endpoint at the given path, and every JSON-RPC call comes in through it. AddControllers is not needed.

Program.cs needs three things: register the object factory, register the JSON-RPC services, and map the endpoint.

using Polhem.JsonRpc.AspNetCore;
using Polhem.JsonRpc.Server;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IJsonRpcObjectFactory, AppObjectFactory>();
builder.Services.AddJsonRpcServer();

var app = builder.Build();
app.MapJsonRpc("/api");
await app.RunAsync();

AddJsonRpcServer takes two sets of options. The first configures the server itself, such as filters, the method policy, the batch limit and serializer options. The second configures the HTTP endpoint, such as the request body size limit and which HTTP status code an error returns. Leave them out and the defaults apply.

builder.Services.AddJsonRpcServer(
    options =>
    {
        options.MaxBatchSize = 50;
        options.Filters.Add(new ApiKeyFilter(apiKey)); // see section 5
    },
    http => http.MaxRequestBodySize = 1024 * 1024);

MapJsonRpc returns the same thing as any other Minimal API endpoint, so authorization, CORS and rate limiting chain on the usual way, for example app.MapJsonRpc("/api").RequireAuthorization();.

The object factory and the class that handles the calls:

public sealed class AppObjectFactory : IJsonRpcObjectFactory
{
    public object? CreateObject(string progId, JsonRpcRequestContext context) => progId switch
    {
        "Calculator" => new Calculator(),
        _ => null,
    };
}

public sealed class Calculator
{
    public AddResponse Add(AddRequest request) => new() { Sum = request.A + request.B };
}

Client

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5080/api") };
var rpc = new JsonRpcConnector(new HttpTransport(http));

var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", new AddRequest { A = 1, B = 2 });

That is enough to call Calculator.Add. Note that the server has no AddMethod or similar registration, and Calculator carries no attribute.

3️⃣ With no registration, which methods can be called?

Skipping registration is convenient, but it raises a worry: if one day I add a public method to the class for internal use, can it be called from the network too? When the server receives Calculator.Add, it runs the following checks in order.

Name format. The method name must be ProgId.Action. A ProgId (program identifier) may contain letters, digits, underscores and hyphens; an action letters, digits and underscores; each at most 64 characters. A malformed name is rejected before any lookup.

The application decides the object. The ProgId is passed to your implementation of IJsonRpcObjectFactory.CreateObject, which decides which object to create; returning null means the ProgId is unknown. The packages keep no registry of names, so which ProgIds exist is entirely up to the factory. After the call, the object is passed to ReleaseObjectAsync to be released.

Method signature. An action maps only to a public, non-generic instance method with exactly one parameter. Static methods, property accessors and methods declared by object do not count. If two or more methods with the same name qualify, the server does not pick one; it treats the method as not found.

Naming convention. The parameter type must be named {Action}Request, and the return type (or the result type of Task<T> or ValueTask<T>) must be named {Action}Response. Add takes an AddRequest and returns an AddResponse. This is the default method policy; any public method that does not follow it is treated as nonexistent and answered with -32601 Method not found. An internal helper method that does not follow this naming cannot be called from outside.

The rule can be replaced through JsonRpcServerOptions.MethodPolicy. The Polhem framework replaces it with one that reads its own access-control attribute.

Policy before filters. The method policy runs before every filter, so filters such as authorization checks or decryption only ever see calls that are allowed to run.

Only after these checks are the params bound. params must be a JSON object, deserialized into the request class with camelCase names by default; missing params or an array (positional parameters) are answered with -32602 Invalid params. To return a custom error, a method throws JsonRpcErrorException; any other exception is answered with -32603 Internal error, and the exception message is not sent to the client.

4️⃣ The client

An error returned by the server becomes a JsonRpcErrorException, which carries the error code and message:

try
{
    await rpc.InvokeAsync<DivideResponse>("Calculator.Divide", new DivideRequest { Dividend = 1, Divisor = 0 });
}
catch (JsonRpcErrorException ex)
{
    Console.WriteLine($"Error {ex.Code}: {ex.Message}");
}

Notifications and batches:

// The server runs it but does not respond.
await rpc.NotifyAsync("Calculator.Log", new LogRequest { Message = "Hello" });

// Two calls sent in the same message.
var batch = rpc.CreateBatch();
var first = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 2, B = 3 });
var second = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 4, B = 5 });
await batch.SendAsync();
Console.WriteLine($"{(await first)!.Sum}, {(await second)!.Sum}");

The request and response classes usually live in a project shared by both sides, which is how the samples in the repo are arranged.

5️⃣ Extension points: filters and interceptors

A server filter wraps every call. It can reject the call, rewrite the parameters before the method runs, and rewrite the result afterwards. For example, checking an API key:

public sealed class ApiKeyFilter(string expectedKey) : IJsonRpcFilter
{
    public ValueTask InvokeAsync(JsonRpcRequestContext context, JsonRpcFilterDelegate next)
    {
        context.Transport.Headers.TryGetValue("X-Api-Key", out var key);
        if (!CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(key ?? ""), Encoding.UTF8.GetBytes(expectedKey)))
        {
            throw new JsonRpcErrorException(-32001, "Unauthorized");
        }
        return next(context);
    }
}

builder.Services.AddJsonRpcServer(options => options.Filters.Add(new ApiKeyFilter(apiKey)));

To add an HTTP header on the client, use HttpClient's own DelegatingHandler; the packages add no layer of their own. To rewrite the parameters and result of every call, add an IJsonRpcClientInterceptor.

The Polhem framework plugs its sessions and authorization checks into these extension points (the object factory, the method policy and filters). None of that logic is in the packages themselves.

6️⃣ Encrypted payloads

HTTPS protects the connection. If the parameters and results also need end-to-end protection, or a call must not run a second time when it is resent, add the optional payload packages.

They put params and result into an envelope with three formats: plain JSON, encoded (serialized, then gzip-compressed), and encrypted (AES-256-CBC with HMAC-SHA256, encrypt-then-MAC). A frame carrying a timestamp and a sequence number can also be put in front of the content, so the server can reject expired or repeated requests; that is the replay protection.

// Server: the application's policy decides the keys and which methods must be encrypted or replay-protected.
builder.Services.AddJsonRpcServer(options => options.UsePayload(payloadOptions, new MyPayloadPolicy()));

// Client: called the same way as an ordinary call; each call seals its parameters and opens its result.
var rpc = new PayloadConnector(connector, new PayloadProcessor(payloadOptions),
    new PayloadConnectorOptions { KeyProvider = () => sessionKey });
var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", request);

A few more security details:

The HMAC is compared in constant time and verified before anything is decrypted.
The HMAC covers the method name and the direction, so an intercepted call cannot be redirected to another method, and a response cannot be sent back as a request.
A method can require a minimum format; a request in a lower format is rejected before any key is asked for.

How keys are negotiated (exchanged after sign-in, provisioned in advance, and so on) is outside the packages and left to the application.

7️⃣ How it differs from common libraries

There are quite a few JSON-RPC libraries for .NET; here are two common ones for comparison. The version in each column header is the latest stable release on NuGet as of October 2026, and the details come from that release's documentation and NuGet dependency list. Later releases may differ.

	StreamJsonRpc 2.25.29	Tochka.JsonRpc 7.4.1	Polhem.JsonRpc 1.2.0
JSON library	Newtonsoft.Json by default, switchable to System.Text.Json; the package still depends on Newtonsoft.Json and MessagePack	System.Text.Json	System.Text.Json, with no other dependencies
Transport model	Full duplex over a Stream, WebSocket or Pipe	HTTP on ASP.NET Core MVC	HTTP request and response on ASP.NET Core Minimal APIs
Client	Yes, with proxies generated from interfaces	Yes	Yes
How methods are registered	`AddLocalRpcTarget` adds a target object whose public methods become callable	Controllers that inherit `JsonRpcControllerBase`; each action is a method	No registration; found by `ProgId.Action` and the naming convention
Native AOT	Partially supported, within the limits its documentation lists	Tied to MVC, not supported	The shared package, the client and the payload packages support it; the server does not
Good fit	Two-way communication, such as Visual Studio extensions or LSP	You already use MVC and want to keep writing controllers	An API where you own both ends, possibly with desktop or mobile clients

StreamJsonRpc is the most complete, with cancellation, progress reporting and server-to-client calls, but it is designed for streams and full duplex; turning it into an HTTP request/response API means building the endpoint yourself.

Tochka.JsonRpc is the closest in scope to Polhem.JsonRpc. It builds on MVC controllers, so MVC filters and model binding work as they are, at the cost of sharing MVC's lack of AOT support.

Polhem.JsonRpc goes in a different direction: it trades a fixed call shape for "no registration" and "an API that can evolve", as the next section explains.

8️⃣ Design trade-offs

The fixed call shape is there so the API can evolve. The ProgId.Action name, one request class and one response class are a deliberate restriction. When a member is added to a request or response class, a member an older front end does not send binds to its default on the server, and a result member an older front end does not know is simply skipped when read. Old and new front ends call the same method, with no v1 and v2 endpoints to maintain. Positional parameters cannot do this: add, remove or reorder one parameter and every caller has to change.

Defaults follow the specification. The internal error code is -32603, a response carries only jsonrpc, result or error, and id, and id is always written, as null when it cannot be determined. The Polhem framework's original response format differed from the specification in places; when the packages were extracted, it was the framework that changed to follow the specification, not the packages that bent to the old format.

The reasoning behind each decision is recorded as ADRs (Architecture Decision Records) in the repo's maintainers/adr/, and the security design is summarized in docs/security.md.

✅ Wrapping up

Install the server and client packages:

dotnet add package Polhem.JsonRpc.AspNetCore
dotnet add package Polhem.JsonRpc.Client

The repo includes samples: an ASP.NET Core Minimal API server, a console client (ordinary calls, error handling, notifications and batches), and a server and client using encrypted payloads.

These packages do convention-based JSON-RPC, not general-purpose JSON-RPC. Protocols whose method names and parameters are defined by someone else, such as the Language Server Protocol, MCP or an Ethereum node's API (names like textDocument/didOpen and eth_call with positional parameters), cannot be implemented with them; StreamJsonRpc or the MCP C# SDK fit those better. Nor do they offer a full-duplex connection where the server calls the client: one call is one HTTP request and its response.

If you own both ends of your API, want JSON-RPC that relies on System.Text.Json alone, or have clients that run as desktop or mobile apps, give it a try. Feedback, issues and pull requests are welcome.

DEV Community: Jeff Tsai

Day 10: Multi-Database Support: CRUD and Structure Upgrades

1. Why there are only two shared behaviors

2. CRUD, where the differences are small enough for a lookup table to absorb

3. Structure upgrades, where the differences are large enough that each vendor really does get its own

Difference one: reading the current state

Difference two: whether it can be altered at all

Difference three: the hardest to spot, because it reports no error

And one more kind: column descriptions

4. Which vendor is used is registered by the application, and the framework ships none

The thickness of an abstraction

Day 9: Data and Definitions Split Apart, So Forms Need No Types of Their Own

1. Why a data container rather than strong typing

2. Writing no DTO means pulling data and definition apart

3. What crosses layers is data plus its description

4. What checks the things the compiler cannot

The first stop: build time

The second stop: integration testing

5. These costs are paid for the sake of a thousand forms

The three parts of the split, and that bill

Day 8: Declarative Business Rules and Computed Fields

1. FormRule lives in the same definition as the fields

2. Evaluation happens at only a few points

An asymmetry: validation runs only on the back end

3. One expression, and both sides have to get the same answer

4. The two kinds an expression cannot state

5. Declarative is the default, not the only route

6. The case study: what the definition absorbed, and what stayed in code

That line has moved, and nobody will tell you

In closing

ERP Architect's Notes: Designing a Definition-Driven Framework · Series Index

Chapter One · Why Definition-Driven

Chapter Two · Definition Layer

Chapter Three · Data Access and Caching

Chapter Four · Business Logic and API

Chapter Five · Multi-Tenancy and Customization

Chapter Six · Transport, Security and Audit

Chapter Seven · Data Semantics

Chapter Eight · Case Review and The Big Picture

About the framework behind this series

Day 7: FormLayout and Screen Generation for Multiple Front Ends

1. FormLayout's vocabulary is deliberately small

Hundreds of screens that look the same

2. Fields map to controls

3. One FormLayout, one rendering layer per front end

4. This layer stands on its own because it expires

5. Narrow screens reshape themselves, with no second layout

6. The standard is set, so where is the flexibility

7. The case study: what the order layout says and does not say

What gets rewritten that day

Day 6: TableSchema and Database Structure Upgrades

1. Why TableSchema is a definition of its own

This definition contains no database's type names

The cost: the two have to line up

2. An upgrade is not a generated script, it is a comparison against the current state

3. Compare, plan, execute, cut into three

4. Run the plan first and you know how long this will take

5. ALTER or rebuild, decided by the framework

6. Five stages, each in its own transaction

7. The things deliberately not done

Back to Northwind

The boundary of the truth

Day 5: How FormSchema Drives SQL

1. One more form, six places to touch

2. Querying: the join is looked up, not written

The join list is computed fresh every time

Display columns do not exist in the table

Declared one level deep, executed several levels deep

The circular relationship is not a problem here

Paging is computed fresh too

3. Saving: the field set is the write statements

4. Why this is not an ORM

No entity classes

No relationships expressed as properties, therefore no lazy loading

Change tracking did not disappear, it moved

5. A thousand definitions versus a thousand classes

6. Back to the order form

Day 4: The Purpose and Classification of Definition Files

1. The three boot files: what this deployment runs on

Why the database concerns are two files

1. Why `TableSchema` is a definition of its own