fix(loader): the bare-object error names the ladder, not just the escape hatch

ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF fires at the exact moment an author
writes a shape they have not declared — and until now it answered with one
alternative, the open bag: "For an open/untyped JSON map use @dbColumnType:
jsonb on a field.string instead of a bare object." That is the last rung of a
three-rung ladder presented as the only rung, at the one moment the author is
most likely to take whatever the tool suggests. The authoring skill already
teaches the full ladder and says so explicitly ("the loader's pointer at
@dbColumnType: jsonb on that error is for the genuinely open case, not the
missing-VO case"); the loader itself did not.

All four ports now say the same thing, in each port's own quoting style:

  a known key set              → declare an object.value and @objectref it
  dynamic keys, known value    → field.map (@objectref or @valueType)
  a bag no reader pins a key in → @dbColumnType: jsonb on a field.string

The rule and the code are unchanged — a bare field.object is still rejected,
with the same code and the same source envelope. Only the guidance changed.
expected-errors.json gates code + jsonPath, so no fixture churn; verified no
port test asserts the old substring (the two migrate-ts integration fixtures
that cited it in a COMMENT are corrected — both are legitimately on the last
rung, which is now said rather than implied).

docs/features/field-types.md listed 11 field subtypes where the registry
registers 17. The six missing rows (float, decimal, time, uri, inet, map) are
added with per-port native types read from each port's own mapper rather than
inferred, plus a footnote for the three rows that need one: the uri/inet
@lenient degrade, and field.map's real port coverage — Java's SpringTypeMapper
has no MapField arm, C# emits the property but DbContextGenerator writes no EF
storage mapping, and no persistence- or api-contract fixture exercises it on
any port.

Verified: TS metadata 2621/0; Python unit+conformance 947/0; C# MetaObjects
builds clean; Java metadata module compiles; scripts/ci-local.sh --quick
passed (leak-scan, fixture-lint, ts build+typecheck, conformance: typescript,
ts unit suites, doc-template drift, embedded-library drift all green).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M

Author: dmealing

docs/features/field-types.md

@@ -14,13 +14,40 @@ across ports — a `field.currency` is integer minor units everywhere; a
 | `field.int` | `number` | `Integer` | `Int` | `int` | `int` | `integer` |
 | `field.long` | `number` (or bigint) | `Long` | `Long` | `long` | `int` | `bigint` |
 | `field.double` | `number` | `Double` | `Double` | `double` | `float` | `double precision` |
+| `field.float` | `number` | `Float` | `Float` | `float` | `float` | `real` |
+| `field.decimal` | `string` | `BigDecimal` | `BigDecimal` | `decimal` | `Decimal` | `numeric(@precision, @scale)` |
 | `field.boolean` | `boolean` | `Boolean` | `Boolean` | `bool` | `bool` | `boolean` |
 | `field.date` | `Date` | `LocalDate` | `LocalDate` | `DateOnly` | `date` | `date` |
+| `field.time` | `string` | `LocalTime` | `LocalTime` | `TimeOnly` | `datetime.time` | `time` |
 | `field.timestamp` | `Date` | `Instant` | `Instant` | `DateTimeOffset` | `datetime` | `timestamp with time zone` |
 | `field.currency` | `number` (minor units) | `Long` (minor units) | `Long` (minor units) | `long` (minor units) | `int` (minor units) | `bigint` |
 | `field.uuid` | `string` | `UUID` | `UUID` | `Guid` | `UUID` | `uuid` |
+| `field.uri` | `string` | `java.net.URI` | `java.net.URI` | `Uri` | `AnyUrl` | `text` |
+| `field.inet` | `string` | `InetAddress` | `InetAddress` | `IPAddress` | `IPvAnyAddress` | `inet` |
 | `field.enum` | union + `z.enum` | `Enum` | `enum class` | `enum` | `Enum` | `varchar` + `CHECK` |
 | `field.object` | nested type | nested class | nested data class | nested record | nested dataclass | per `@storage` |
+| `field.map` | `Record<string, V>` | — (see below) | `Map<String, V>` | `Dictionary<string, V>` | `dict[str, V]` | `jsonb` |
+
+That is the whole registered vocabulary — 17 concrete subtypes. `field.base` is an
+abstract registry anchor, never authored (`ERR_ABSTRACT_SUBTYPE_AUTHORED`).
+
+Three rows need a footnote:
+
+- **`field.uri` / `field.inet`** bind a native URL/IP type on every port but TypeScript,
+  which has none (the same reason `field.uuid` is a `string` there). `@lenient: true`
+  degrades both to a plain string with no validator, and takes the `inet` column down to
+  `text`.
+- **`field.map`** is the typed dict: string keys, and a value type set by exactly one of
+  `@valueType` (a scalar subtype) or `@objectRef` (a value object) — `V` above. It is one
+  jsonb column holding the JSON object; `isArray` does not apply. **Java does not complete
+  this rung:** `SpringTypeMapper.javaTypeName` has no `MapField` arm, so a mapped field on
+  a Spring entity reaches its `unsupported Spring DTO type mapping` throw. On C# the
+  property and its `[Column]` annotation are emitted but `DbContextGenerator` writes no EF
+  storage mapping for the dictionary, so EF does not persist it. **No persistence- or
+  api-contract-conformance fixture exercises `field.map` on any port — it is loader-gated
+  only.** Until that closes, a stable key set is better declared as an `object.value`
+  behind `field.object`; see [ADR-0037](../../spec/decisions/ADR-0037-metamodel-vocabulary-expansion-decision-framework.md)
+  for which of the two a shape belongs in.
 
 ## Common field attributes
 

fixtures/conformance/ERROR-CODES.json

@@ -48,7 +48,7 @@
     "ERR_BAD_ATTR_FILTER": "An attr.filter references a field that is not addressable in that context or uses a disallowed op: a dataGrid @filter over a non-filterable field or an op disallowed for the field's subtype, or a projection row-scope @filter over a non-declared (dangling) or aggregate-derived field (#207).",
     "ERR_STORAGE_FLATTENED_ARRAY": "@storage \"flattened\" cannot be combined with isArray=true.",
     "ERR_STORAGE_WITHOUT_OBJECT_REF": "@storage was set on a field that has no @objectRef.",
-    "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF": "ADR-0013: a field.object declares no @objectRef. A field.object models a typed nested value and REQUIRES @objectRef. For a genuinely open/untyped JSON map, use the physical escape hatch @dbColumnType: jsonb on a field.string instead of a bare object.",
+    "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF": "ADR-0013: a field.object declares no @objectRef. A field.object models a typed nested value and REQUIRES @objectRef. The message states the whole ladder rather than only the escape hatch: a known key set is an object.value the field @objectRefs; dynamic keys over a known value type are a field.map (@objectRef for a value object, @valueType for a scalar); only a bag no reader pins a key in is @dbColumnType: jsonb on a field.string. Naming the escape hatch alone is what taught adopters to reach for the bag by default.",
     "ERR_UNRESOLVED_OBJECT_REF": "ADR-0042: a field.object / field.map @objectRef does not resolve to any object in the loaded tree (a dangling target). The ref resolves package-locally when bare (referrer's package, else root-level) and exactly when FQN — a bare cross-package ref no longer binds elsewhere. The error names same-short-name objects in other packages so the author can qualify it.",
     "ERR_RESERVED_ATTR": "An @-prefixed reserved structural keyword (e.g. @name, @isArray, @children) was used as an inline attribute.",
     "ERR_SCOPE_PATTERN_INVALID": "Phase-1 metadata-source-resolution: a scope include/exclude package pattern is malformed (empty pattern or empty :: segment).",

server/csharp/MetaObjects/Loader/ValidationPasses.cs

@@ -2919,8 +2919,12 @@ private static void WalkDbColumnType(MetaData node, List<MetaError> errors)
     //   Cross-attribute validation for field.object + @storage (ADR-0013):
     //     - A field.object ALWAYS requires @objectRef → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF.
     //       A field.object models a typed nested value; without @objectRef it is
-    //       "an oxymoron at the logical layer". Open/untyped JSON uses the physical
-    //       @dbColumnType: jsonb escape hatch on field.string, NOT a bare object.
+    //       "an oxymoron at the logical layer". The MESSAGE states the whole ladder,
+    //       not just the last rung: a known key set is an object.value the field
+    //       @objectRefs; dynamic keys over a known value type are a field.map; only
+    //       a bag no reader pins a key in is @dbColumnType: jsonb on a field.string.
+    //       Naming the escape hatch alone — which this error did until now — is what
+    //       taught adopters to reach for the bag by default.
     //       This rule subsumes the legacy @storage-without-@objectRef check
     //       (@storage is only meaningful on a field.object), so missing-@objectRef
     //       now always reports this single, clearer error — one error per node
@@ -2951,8 +2955,12 @@ public static IReadOnlyList<MetaError> ValidateFieldObjectStorage(MetaData root)
                 {
                     errors.Add(new MetaError(
                         $"field.object \"{obj.Name}.{field.Name}\" has no @objectRef; " +
-                        "a field.object requires @objectRef. For an open/untyped JSON map " +
-                        "use @dbColumnType: jsonb on a field.string instead of a bare object.",
+                        "a field.object models a typed nested value and requires one. " +
+                        "Take the first of these that fits: a known key set → declare an " +
+                        "object.value and point @objectRef at it; dynamic keys over a known value " +
+                        "type → field.map with @objectRef (a value object) or @valueType (a " +
+                        "scalar); a genuinely open bag no reader pins a key in → " +
+                        "@dbColumnType: jsonb on a field.string.",
                         ErrorCode.ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF,
                         Envelope: field.Source));
                     continue;

server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java

@@ -1893,8 +1893,12 @@ private static List<String> junctionReferenceFkFields(MetaObject junction) {
     // Rules, matching the cross-port spec (ADR-0013):
     //   1. A field.object ALWAYS requires @objectRef → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF.
     //      A field.object models a typed nested value; without @objectRef it is "an
-    //      oxymoron at the logical layer". Open/untyped JSON uses the physical
-    //      @dbColumnType: jsonb escape hatch on field.string, NOT a bare object.
+    //      oxymoron at the logical layer". The MESSAGE states the whole ladder, not
+    //      just the last rung: a known key set is an object.value the field
+    //      @objectRefs; dynamic keys over a known value type are a field.map; only a
+    //      bag no reader pins a key in is @dbColumnType: jsonb on a field.string.
+    //      Naming the escape hatch alone — which this error did until now — is what
+    //      taught adopters to reach for the bag by default.
     //      This rule subsumes the legacy @storage-without-@objectRef check (@storage
     //      is only meaningful on a field.object), so missing-@objectRef now always
     //      reports this single, clearer error — one error per node (we skip the
@@ -1931,9 +1935,12 @@ private static void validateObjectFieldStorageNode(MetaData node) {
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF
                     + ": field.object '" + field.getName()
-                    + "' has no @objectRef — a field.object requires @objectRef."
-                    + " For an open/untyped JSON map use @dbColumnType: jsonb on a"
-                    + " field.string instead of a bare object.",
+                    + "' has no @objectRef — a field.object models a typed nested value"
+                    + " and requires one. Take the first of these that fits: a known key set"
+                    + " → declare an object.value and point @objectRef at it; dynamic keys"
+                    + " over a known value type → field.map with @objectRef (a value object)"
+                    + " or @valueType (a scalar); a genuinely open bag no reader pins a key"
+                    + " in → @dbColumnType: jsonb on a field.string.",
                 ErrorCode.ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF, field.getSource());
         }
 

server/java/metadata/src/main/java/com/metaobjects/util/ErrorMessageConstants.java

@@ -186,9 +186,11 @@ private ErrorMessageConstants() {
 
     /**
      * Error code emitted when a {@code field.object} declares no {@code @objectRef}
-     * (ADR-0013). A field.object models a typed nested value and REQUIRES @objectRef;
-     * an open/untyped JSON map uses the physical {@code @dbColumnType: jsonb} escape
-     * hatch on a {@code field.string} instead of a bare object.
+     * (ADR-0013). A field.object models a typed nested value and REQUIRES @objectRef.
+     * The message states the whole ladder rather than only the escape hatch: a known
+     * key set is an {@code object.value} the field {@code @objectRef}s; dynamic keys
+     * over a known value type are a {@code field.map}; only a bag no reader pins a key
+     * in is {@code @dbColumnType: jsonb} on a {@code field.string}.
      * Cross-language contract: {@code ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF}.
      */
     public static final String ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF = "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF";

server/python/src/metaobjects/loader/validation_passes.py

@@ -3365,8 +3365,12 @@ def _validate_sortable_has_supported_subtype(
 # Cross-port rules (ADR-0013):
 #   1. A field.object ALWAYS requires @objectRef → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF.
 #      A field.object models a typed nested value; without @objectRef it is an
-#      oxymoron at the logical layer. Open/untyped JSON uses the physical
-#      @dbColumnType: jsonb escape hatch on field.string, NOT a bare object. This
+#      oxymoron at the logical layer. The MESSAGE states the whole ladder, not just
+#      the last rung: a known key set is an object.value the field @objectRefs;
+#      dynamic keys over a known value type are a field.map; only a bag no reader
+#      pins a key in is @dbColumnType: jsonb on a field.string. Naming the escape
+#      hatch alone — which this error did until now — is what taught adopters to
+#      reach for the bag by default. This
 #      rule subsumes the legacy @storage-without-@objectRef check (@storage is only
 #      meaningful on a field.object), so missing-@objectRef now always reports this
 #      single, clearer error — one error per node (the flattened/array check is
@@ -3388,8 +3392,12 @@ def _validate_field_object_storage(root: MetaData, errors: list[MetaError]) -> N
                 code=ErrorCode.ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF,
                 message=(
                     f"field.object '{node.name}' has no @objectRef — a field.object "
-                    f"requires @objectRef. For an open/untyped JSON map use "
-                    f"@dbColumnType: jsonb on a field.string instead of a bare object."
+                    f"models a typed nested value and requires one. Take the first of "
+                    f"these that fits: a known key set → declare an object.value and point "
+                    f"@objectRef at it; dynamic keys over a known value type → field.map "
+                    f"with @objectRef (a value object) or @valueType (a scalar); a "
+                    f"genuinely open bag no reader pins a key in → @dbColumnType: jsonb "
+                    f"on a field.string."
                 ),
                 envelope=node.source,
             ))

server/typescript/packages/metadata/src/loader/validation-passes.ts

@@ -1672,8 +1672,13 @@ export function validateDerivedFieldProvidability(root: MetaData): ParseError[]
 // Rules (ADR-0013):
 //   1. A field.object ALWAYS requires @objectRef. A field.object models a typed
 //      nested value; without @objectRef it is "an oxymoron at the logical layer".
-//      Genuinely open/untyped JSON uses the physical @dbColumnType: jsonb escape
-//      hatch on field.string, NOT a bare object. → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF.
+//      → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF. The MESSAGE states the whole ladder,
+//      not just the last rung: a known key set is an object.value the field
+//      @objectRefs; dynamic keys over a known value type are a field.map; only a
+//      bag no reader pins a key in is @dbColumnType: jsonb on a field.string.
+//      Naming the escape hatch alone — which this error did until now — is what
+//      taught adopters to reach for the bag by default, and it is the mechanism
+//      behind every untyped-jsonb column an adoption audit finds.
 //      (This rule subsumes the legacy @storage-without-@objectRef check —
 //      @storage is only meaningful on a field.object, so the missing-@objectRef
 //      situation now always reports this single, clearer error. One error per
@@ -1699,7 +1704,7 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         // further @storage error on the same node would be redundant.
         errors.push(
           new ParseError(
-            `field.object "${obj.name}.${field.name}" has no @objectRef; a field.object requires @objectRef. For an open/untyped JSON map use @dbColumnType: jsonb on a field.string instead of a bare object.`,
+            `field.object "${obj.name}.${field.name}" has no @objectRef; a field.object models a typed nested value and requires one. Take the first of these that fits: a known key set → declare an object.value and point @objectRef at it; dynamic keys over a known value type → field.map with @objectRef (a value object) or @valueType (a scalar); a genuinely open bag no reader pins a key in → @dbColumnType: jsonb on a field.string.`,
             { code: "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF", source: field.source },
           ),
         );

server/typescript/packages/migrate-ts/test/integration/pg-expression-index-casts.test.ts

@@ -63,7 +63,8 @@ const meta = (indexes: ReadonlyArray<{ name: string; expr: string }>): string =>
             children: [
               { "source.rdb": { "@table": "ledger" } },
               { "field.long": { name: "id" } },
-              // An open/untyped JSON map, spelled the way the loader's own error prescribes.
+              // A genuinely open bag — the LAST rung of the jsonb ladder, and the right one
+              // here: the fixture exercises expression-index casts over jsonb, pinning no key.
               { "field.string": { name: "payload", "@column": "payload", "@dbColumnType": "jsonb" } },
               { "field.decimal": { name: "amt", "@column": "amt", "@precision": 10, "@scale": 2 } },
               { "identity.primary": { name: "pk", "@fields": ["id"], "@generation": "increment" } },

server/typescript/packages/migrate-ts/test/integration/pg-expression-index-spacing.test.ts

@@ -48,8 +48,10 @@ const meta = (expr: string): string =>
             children: [
               { "source.rdb": { "@table": "notification" } },
               { "field.long": { name: "id" } },
-              // An open/untyped JSON map: a `field.string` with a jsonb physical type, which
-              // is what the loader's own error message prescribes for a bare object.
+              // A genuinely open bag — the LAST rung of the jsonb ladder, and the right one
+              // here: this fixture exists to exercise expression-index rendering over a jsonb
+              // column, so nothing in it pins a key. (A shape the code knows would be an
+              // object.value or a field.map; the loader's error names all three rungs.)
               { "field.string": { name: "requestContext", "@column": "request_context", "@dbColumnType": "jsonb" } },
               { "identity.primary": { name: "pk", "@fields": ["id"], "@generation": "increment" } },
               { "index.lookup": { name: "byDevice", "@expr": expr } },