Metadata Annotations

Softa maintains its sys_* catalog tables through two coexisting paths:

1. Annotations (this page) — code-first. Declare metadata on Java entity classes; a boot-time scanner reads the annotations, reconciles them with the sys_* tables, and applies matching DDL in dev mode. Best for the baseline shipped with your codebase — platform / framework models versioned alongside the source, gated by code review and CI/CD.
2. Studio (visual designer) — config-first. A visual workbench writes the same sys_* rows through a WorkItem → Version → Deployment workflow. Best for tenant customizations and business-team-owned configuration that need to change without a redeploy. See the Studio User Guide.

The two paths never clobber each other: every sys_* row carries an Ownership tag, and the annotation scanner only reads / writes PLATFORM_MAINTAINED rows.

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.

Five annotations, all in io.softa.framework.orm.annotation:

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

Inference rules (no annotation needed)

@Model ↔ SysModel

Business semantics of each attribute: see Model Metadata.

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

Business semantics of each attribute and the full field-type catalog: see Field Metadata.

@OptionSet ↔ SysOptionSet

Runtime behavior, caching, and API shape: see Option Sets.

@OptionItem ↔ SysOptionItem

Display attributes (itemTone, itemIcon) and API response shape: see Option Sets.

@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)

Row ownership (Ownership enum)

Every row in sys_model / sys_field / sys_option_set / sys_option_item / sys_model_index carries an ownership column (io.softa.framework.orm.enums.Ownership):

The scanner reads / writes are filtered with WHERE ownership = 'PLATFORM_MAINTAINED', so platform defaults and tenant customizations are never clobbered by an annotation reconcile.

See Ownership.java javadoc for the full merge-rule contract.