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) applies the matching DDL.

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 FKs clash with the never-auto-DROP DDL governance. 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”: the new column is auto-added, dropping the old one is warn-only — and the data stays in the orphaned column (silent data divorce).

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 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.

DDL auto-execute policy

Rationale: additive DDL doesn’t lose data; DROP operations are destructive and may take minutes on large tables. Even in dev, you should consciously choose to drop schema.

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.