Metadata Annotations

Requires metadata-starter as a dependency of your app for these annotations to take effect. softa-orm defines the annotations; metadata-starter contains the scanner and checker that read them and reconcile with sys_*. Without metadata-starter the annotations exist on your classes but no scanner consumes them — sys_* rows are never written and no DDL is generated.

Softa describes models, fields, option sets, option items, and indexes through Java annotations on the entity classes. A boot-time scanner reads these annotations, reconciles them with the sys_* catalog tables managed by metadata-starter, and (for packages in scanner-scope) converges the physical schema to the annotations — declared changes and hand-made drift alike, so a restart always ends with schema ≡ annotations for everything the scope owns.

Five annotations — @Model / @Field / @Index live in io.softa.framework.orm.annotation; @OptionSet / @OptionItem live in io.softa.framework.base.annotation (so framework-level enums in softa-base can carry them without a module cycle):

@Data
@EqualsAndHashCode(callSuper = true)
@Model(
    label = "Customer",
    businessKey = {"code"},
    description = "Customer master"
)
@Index(indexName = "uk_customer_code", fields = {"code"}, unique = true)
@Index(fields = {"status", "createdTime"})
public class Customer extends AuditableModel {
 
    @Field(label = "ID")
    private Long id;
 
    @Field(label = "Customer Code", required = true, length = 32)
    private String code;
 
    @Field(label = "Customer Tier")
    private CustomerTier tier;   // enum → FieldType.OPTION (inferred)
}
 
@OptionSet(label = "Customer Tier")
public enum CustomerTier {
    @OptionItem(label = "VIP Gold") GOLD("g"),   // explicit: "VIP Gold" ≠ humanize("GOLD")
    SILVER("s");                                 // bare: label defaults to humanize("SILVER") = "Silver"
 
    @JsonValue private final String code;       // itemCode = @JsonValue
    CustomerTier(String code) { this.code = code; }
}

Inference rules (no annotation needed)

@Model ↔ SysModel

Audit fields (createdTime / createdBy / createdId / updatedTime / updatedBy / updatedId) come from AuditableModel and are not declared via @Field — they are auto-injected by DdlGenerator when the class extends AuditableModel.

@Field ↔ SysField

Copy field-selection contract (applies regardless of the copyable flag): ONE_TO_ONE FKs are always excluded — copying one would make two rows share an exclusively-owned related row, corrupting the 1:1 (or hard-failing on its unique index); dynamic fields (ONE_TO_MANY / MANY_TO_MANY / computed / cascaded) are excluded because they are not stored columns; MANY_TO_ONE stays copyable — a shared reference is exactly its semantics. Historical trap: the nonCopyable → copyable rename was done as a migration (V6), NOT via renamedFrom, because the rename inverts the value’s meaning — a value-preserving rename would have carried wrong values.

Delete strategy (onDelete)

On a MANY_TO_ONE / ONE_TO_ONE FK, onDelete declares what happens to the referencing rows when the referenced (“One”) row is deleted. Enforced application-level in ModelServiceImpl.deleteByIds — no physical DB FOREIGN KEY ... ON DELETE is ever emitted. Why app-level and never a real DB FK: soft delete is an UPDATE, invisible to a DB ON DELETE (the FK would simply never fire); a DB cascade bypasses permissions, change logs, audit stamping, soft-delete conversion and tenant scoping; a DB FK cannot express “count only deleted=false referrers”, “block regardless of tenant”, or “null only on hard delete”; and physical FK constraints sit outside the annotation-driven DDL governance (the scanner neither declares nor manages them). Strategies:

• RESTRICT — block the delete if any live (deleted=false) referrer exists.
• CASCADE — delete the referrers in the same transaction (each follows its own soft/hard delete). Rejected at boot if a soft-delete One would cascade to a hard-delete Many (a recoverable parent must not irreversibly delete children — make the Many soft-delete too, or use RESTRICT/SET_NULL).
• SET_NULL — null the referrer FK; only on a hard delete of the One (no-op on soft delete, so a restore still resolves the link). Requires a nullable FK (required = false).
• unset ({} / on_delete NULL) = KEEP (default) — the framework does nothing.

CASCADE soft/hard-delete matrix — the cascade on each Many follows the Many’s own delete mode (not the One’s); the one unsafe combination is rejected at boot:

A CASCADE from a shared (non-multi-tenant) parent to a multi-tenant child is likewise rejected at boot — one delete would cascade across all tenants (use RESTRICT).

Runtime safety — a CASCADE / SET_NULL affecting more than MAX_BATCH_SIZE referrers per cascade level is rejected: referrerIds fetches at most MAX_BATCH_SIZE + 1 ids in one LIMIT-ed query, so an over-limit delete fails fast without loading the full set (bounded memory, no extra count). Large deletes are chunked to DEFAULT_BATCH_SIZE to bound the SELECT/DELETE statement + IN-clause size (same transaction — chunking bounds statement size, not lock duration).

For a OneToMany “delete parent → delete children”, put CASCADE on the child’s back-reference FK (the FK is the single source of truth; onDelete is not declared on ONE_TO_MANY).

Boot-time guards (fail-fast): onDelete is valid only on TO_ONE; SET_NULL requires a nullable FK; a cyclic / self-referential CASCADE is rejected (delete such hierarchies — org trees, BOM, category trees — in application code); a CASCADE chain deeper than MAX_CASCADE_DEPTH models is rejected (bounds recursion; the error names the full chain); and a CASCADE from a soft-delete parent to a hard-delete child, or from a shared parent to a multi-tenant child, is rejected (see the matrix above).

A timeline target is allowed: the inbound-FK strategy fires on entity deletion (deleteByIds, which removes all slices of the logical id — referencing FKs store that logical id, so RESTRICT counts / CASCADE deletes / SET_NULL nulls by it, no effective-date resolution involved); slice-level deleteBySliceId keeps the entity alive and deliberately does not trigger it.

Field-level overview for product/metadata authors: onDelete in Field metadata.

@OptionSet ↔ SysOptionSet

@OptionItem ↔ SysOptionItem

@Index ↔ SysModelIndex

@Index is @Repeatable — stack multiple declarations on one @Model class.

Note: @Model.businessKey does not auto-create a UNIQUE index. Multi-tenant models typically want UNIQUE (tenant_id, businessKey...) which has tenant-aware semantics not expressible by @Index alone — declare such indexes explicitly:

@Index(fields = {"tenantId", "code"}, unique = true)

Renames (renamedFrom)

The scanner’s diff is keyed by modelName / fieldName / optionSetCode / itemCode, so an undeclared rename looks like “drop old + add new” — and under an active scanner-scope the convergence pass executes exactly that: the new column is added empty, and the old column, no longer declared by anything, is dropped together with its data in the same boot. Nothing arrives in the new column.

Declare the immediately-prior name instead:

@Model(renamedFrom = "OldCustomer")          // model rename
public class Customer extends AuditableModel {
 
    @Field(renamedFrom = "customerName")     // field rename
    private String name;
}

The DiffEngine then pairs the two sides into a single rename modification, auto-executes CHANGE COLUMN (field) / ALTER TABLE … RENAME TO (model), and updates the sys_* row in place (id preserved) — data is carried, not divorced. A model rename cascades onto its fields and indexes, so it shows no field churn. @OptionSet / @OptionItem support the same attribute.

Rules and guards:

• renamedFrom is a single String — the immediately-prior name only (single-step, no chain). A skipped-version chain needs a manual migration.
• Declaring a prior name that is still a live field/model, or two siblings claiming the same prior name, fails at parse time.
• “Both the new and the prior name already exist” fails fast — resolve the half-applied rename manually.
• An @OptionItem code rename that also carries business-data UPDATEs still needs a hand-written migration.

scanner-scope (which packages the scanner manages)

scanner-scope is a list of regex patterns full-matched against each @Model / @OptionSet class’s package name. "*" (sole entry) = all packages; empty / unset = manage nothing. It should never be non-empty in production — in production, Studio / connector publish applies the app-scoped design catalog instead.

# application-dev.yml
system:
  metadata:
    scanner-scope:
      - "*"          # manage every package; on a shared dev DB, narrow to
                     # your own packages, e.g. ["io\\.acme\\.app.*"]

On a shared dev database, give each developer a narrow scope (their own packages) so the scanner only reconciles — and converges — the Java packages they are actively changing. Scope is per-package, not per-class; app identity is still app_code, and physical table-name collisions remain a database-level concern.

Catalog row policy

The catalog is an aggregate: sys_model / sys_option_set are the roots, sys_field / sys_model_index / sys_option_item their attributes.

A code-less root is a first-class state: Studio no-code and seed-authored models never have a Java class, and nothing in the catalog records row ownership — so “orphan” and “deliberately code-less” cannot be told apart, and auto-deleting would silently destroy hand-authored definitions on every boot. Note the contrast with the physical schema below: an undeclared column on a table the scope owns has no legitimate author (the owner’s annotations are its single source of truth) and is converged away, while a code-less root may be someone’s deliberate definition and is only ever named in the WARN.

DDL execution policy (physical convergence)

With an active scanner-scope, the physical table of every in-scope owned model is a pure function of the annotations — every boot converges it, declared changes and hand-made drift alike:

If physical introspection fails, the boot degrades to conservative metadata-only planning: additive changes and declared renames auto-execute; every destructive verb defers to a warn-only copy-paste SQL block — without facts, drift and intent are indistinguishable. Destructive convergence can never reach production, because production runs the empty scope (checker-only): the gate is the existing scanner-scope posture, not a separate switch.

Projection models are outside this table entirely: a model declared @Model(projection = true) (a read-only model over a table it does not own — another model’s table, or one created externally, e.g. by a BI pipeline) generates no DDL for any change. Its sys_* rows still reconcile, but the table’s shape belongs to its owning model or the external process. One table has ONE non-projection owner — a second owner fails at boot, which makes a fresh-database bootstrap deterministic (exactly one CREATE per table) and turns an accidental tableName collision into a boot error instead of a silent table merge. The physical drift audit checks a projection one-way (its declared columns must exist; the owner’s other columns/indexes are never reported as undeclared), and a physically missing projection table logs an ERROR — never a boot failure, never auto-created. Convention for in-app sharing: repeat the owner’s column declarations verbatim for the columns the projection exposes, and declare everything else dynamic.

Catalog self-bootstrap (the sys_* tables’ own schema)

The five boot-read catalog tables (sys_model, sys_field, sys_option_set, sys_option_item, sys_model_index) have no row-level “last applied state” — the rows recording every other model’s state live inside them. On every boot with a non-empty scanner-scope, the scanner therefore reconciles them physically, from their own annotations, before the strict catalog read:

• table missing → CREATE TABLE — a fresh, empty database bootstraps with no baseline SQL at all;
• column missing → ADD COLUMN — a catalog-column addition in a new framework version converges on existing databases without a hand-written migration;
• declared renamedFrom with the prior column present → CHANGE COLUMN (data carried); both old and new present → boot fails with instructions;
• physically narrower than declared (bounded widths only) → widening MODIFY COLUMN; anything wider / incomparable / undeclared is left untouched by this stage — it runs before the diff exists and possibly under a narrow scope that does not manage the catalog. When the catalog packages are in scope, the main convergence pass later in the same boot eliminates those like any other in-scope drift; otherwise the physical drift audit reports them.

The whole boot DDL window (catalog reconcile → strict read → diff → DDL → row writes) is serialized across instances by a database session lock (MySQL GET_LOCK / PostgreSQL advisory lock, 60s wait budget), so replicas booting the same database never race their DDL.

What still needs a hand-written migration: backfill UPDATEs that give an added column real values on rows the scanner does not manage, destructive changes on out-of-scope tables, and environments running with an empty scanner-scope — there nothing auto-applies, catalog included.

Metadata identity (app_code)

There is no ownership tier column on the sys_* catalog. The annotation lane and the Studio no-code lane reconcile the same rows, matched by business key (modelName / fieldName / optionSetCode / itemCode, plus renamedFrom) — a same-key row is updated in place, never duplicated per channel.

Every runtime declares system.app-code in application.yml (mandatory when metadata-starter is active; fail-fast at boot). All swept sys_* rows carry app_code, stamped server-side on every write path (scanner, Studio envelope, plan/apply) — wire values are never trusted. Signed Studio calls carry the target appCode and the runtime rejects mismatches. Multiple apps can safely share one database: rows are matched per app_code, so shared databases never cross-link catalogs.