Metadata Mapping

Metadata Mapping

Purpose

Decide where mapping information lives and what generates it, and keep it honest about the schema it describes. Metadata mapping is what makes an ORM possible: the mapping is data, read by a generic engine, instead of a per-class translation someone wrote. That is a large win and it has three recurring costs — the metadata sits on the domain class, it is checked late, and it drifts.

The choices

Annotations on the class      the mapping lives with the code it maps.
                              Discoverable, but string values can drift; it couples
                              the class to the persistence framework.

External metadata (orm.xml)   the class stays clean; the mapping is a
                              separate artefact that can vary per
                              deployment. Costs discoverability and is
                              not refactor-safe.

Programmatic configuration    mapping built in code at startup (Spring
                              Data JDBC dialects, jOOQ, MyBatis, a
                              hand-written Data Mapper). Most explicit,
                              most verbose.

Generated code                a build step produces the mapping or the
                              accessors from a source of truth — the
                              schema (jOOQ), the entities (JPA static
                              metamodel), or an interface (MapStruct).

Workflow

Inspect the JDK/compiler, JPA namespace/version, ORM/provider, annotation processors, database dialect and schema deployment pipeline first. Examples are partial; this skill does not authorize upgrading the stack to match its documentation sources.

1. Pick the schema deployment authority. Versioned migrations should control shared production schemas. Model-generated DDL can be reviewed into migrations; avoid independent automatic startup mutation competing with the migration history.
2. Decide whether the domain class may carry the metadata. This is the layering question, and the honest answer depends on whether a separate domain model exists at all (data-source-patterns).
3. Validate mapping/schema compatibility in CI and suitable startup environments. Strict startup validation can intentionally reject mixed-version rolling deploys or restricted production credentials; decide where it is safe and keep a pre-deploy compatibility gate.
4. Prefer typed generated references where supported. Regeneration exposes removed/renamed members at compile time when used. Remaining strings/constants need validation; moving a string into a constant does not make its value schema-checked.
5. Check for duplicated mapping. The same fact stated in annotations, in a migration, in a DTO mapper and in a view is four places to update and three places to be wrong.
6. Resist metadata-driven behaviour unless a stated driver requires it; see the decision rules.

Decision rules

Entities are the persistence model, the team is small, the stack is JPA
        → annotations. The default, and the coupling is honest because
          the class IS the persistence model.

A separate framework-free domain model exists
        → the metadata belongs on the persistence model (row/entity),
          not on the domain type. If annotations are appearing on the
          domain class, investigate the leak or an accepted coupling rather than
          inferring that either model is redundant.

The same classes must map differently per deployment or per tenant
        → external metadata or programmatic configuration. This is the
          case orm.xml was designed for and it is rare.

Column and attribute names appear as strings in queries or projections
        → use typed generated references where possible; validate remaining
          string-based queries against the target mapping/schema.

The schema is the source of truth and is owned elsewhere
        → generate from a pinned schema (jOOQ-style), regenerate in CI and
          compile consumers; test compatibility with the deployed schema too.

Mapping between two object shapes (entity ↔ DTO)
        → generated mapper, or explicit hand-written code. Reflection
          -based deep mappers hide field mismatches until runtime.

Someone proposes storing the model definition as data so new fields
need no deploy
        → require the driver in writing. This buys deploy-free change
          and moves validation and compatibility checks into a versioned
          runtime schema/interpreter (enterprise-architecture-smells).

Rules

• Use one schema mutation authority. Spring Boot uses spring.jpa.hibernate.ddl-auto; Hibernate's native setting is hibernate.hbm2ddl.auto. Avoid update/create/create-drop competing with migrations on shared data. Disposable test databases may deliberately generate schemas; model-generated scripts reviewed into migrations are another valid path.
• Use validate where startup failure is an acceptable control and permissions expose enough metadata. For rolling deployment, validate both old and new application versions against the expanded schema before rollout; do not discover incompatibility by replacing all healthy pods.
• Startup validation is not complete validation. It checks tables, columns and types; it does not check nullability the way you would want, nor constraints, nor indexes, nor defaults comprehensively across providers/dialects. A schema diff covers only the objects and properties its extraction includes; exercise permissions, queries and writes separately.
• Annotations on domain classes are a real coupling and a defensible one. What is not defensible is claiming a framework-free domain while the domain classes carry @Entity — decide which architecture you have and record it (layering-and-boundaries).
• Unchecked string literals naming columns or attributes are a runtime-failure risk. JPQL text, Sort.by("cusotmerId"), projections by name, native queries: invalid names can fail at runtime, some only on a rarely used path. Generate the JPA static metamodel and use Order_.CUSTOMER style constants only when supplied by the chosen processor; they are not the portable typed metamodel contract and string-consuming APIs still need execution/validation tests.
• Reflection/enhancement/accessor costs are provider, mapping and runtime specific. Metadata parsing is primarily startup work, while field access, dirty checking and materialization remain hot-path concerns. Do not infer significance; measure startup and query/allocation profiles where it matters (startup-cds-crac-leyden).
• Bytecode enhancement changes real behaviour, not just performance: lazy attribute loading, inline dirty tracking, and support for lazy inverse @OneToOne in applicable Hibernate mappings. Feature flags, mutable types and provider/version matter; do not assume all snapshots disappear or all associations become lazy. Enhancement has its own debugging cost — adopt it for a named reason, not by default.
• Repeated facts can drift, but migration DDL, persistence mapping and API validation can intentionally express different contracts. Identify which facts must agree; generate or test those agreements instead of deleting independent constraints by counting repetitions.
• Metadata-driven models trade compile-time safety for deploy-free change, and the trade includes an interpreter and runtime validation you must maintain. Versioned schemas, bounded field/type limits and contract tests remain possible and necessary. Require a concrete variability driver and confine dynamic behavior where practical (orm-structural-mapping on serialized LOB).

References

• Where mapping metadata lives — annotations, orm.xml, programmatic and generated mappings compared on coupling, refactor safety, discoverability and per-deployment variability; the mixed strategy that works (annotations plus an override file); metamodel generation; and mapping between object shapes. Read when choosing where the mapping should live, or when annotations are accumulating somewhere they should not.
• Generation and drift — schema validation at startup and what it does not catch, a schema diff in CI, generating code from the schema versus generating the schema from code, bytecode enhancement's real effects, and the recurring drift scenarios with their detection. Read when a mapping mismatch reached production, or when setting up the build's guardrails.