Skip to content

entities.md

Latest commit

 

History

History
386 lines (313 loc) · 16.7 KB

entities.md

File metadata and controls

386 lines (313 loc) · 16.7 KB
Raw

Entities

An entity is a typed, named record shape declared in metadata. It is the unit of codegen, the unit of persistence, and the unit of API exposure. Every port turns the same object.entity declaration into idiomatic native code — a TS interface + Zod schema, a Java POJO, a Kotlin data class, a C# record, a Python @dataclass.

The entity is metadata-first: you don't write the class, the loader reads the declaration, the codegen emits the class, and the runtime layer reads the same declaration to drive CRUD, validation, and relationships. Pattern-derivable code (FK columns, validator chains, type-safe finders) is generated from the metadata; business logic stays hand-written.

Authoring

Canonical JSON (the on-disk interchange)

{
  "metadata.root": {
    "package": "acme::blog",
    "children": [
      {
        "object.entity": {
          "name": "Author",
          "children": [
            { "source.rdb": { "@table": "authors" } },
            { "field.long":   { "name": "id" } },
            { "field.string": { "name": "name", "@required": true, "@maxLength": 200 } },
            { "field.string": { "name": "bio",  "@maxLength": 2000 } },
            { "identity.primary": { "@fields": "id", "@generation": "increment" } }
          ]
        }
      }
    ]
  }
}

Sigil-free YAML (AI-first authoring front-end)

metadata:
  package: acme::blog
  children:
    - object.entity:
        name: Author
        children:
          - source.rdb:
              table: authors
          - field.long:
              name: id
          - field.string:
              name: name
              required: true
              maxLength: 200
          - field.string:
              name: bio
              maxLength: 2000
          - identity.primary:
              fields: id
              generation: increment

YAML is desugared to canonical JSON at load time. See yaml-authoring.md for the desugar rules.

Anatomy of an entity

Child node Purpose Required
source.rdb Declares physical storage (table/view/storedProc). See source-kinds.md. Yes for persisted entities; abstract entities may omit.
field.<subtype> One field per typed column. See field-types.md. At least one.
relationship.composition An FK relationship to another entity. See relationships.md. No.
identity.primary Designates the PK field(s). Yes for persisted entities.
identity.secondary Unique secondary index. No.
identity.reference Inbound FK from this entity to another. No.

identity.primary is a singleton — its name is optional. An entity may carry at most one identity.primary; the loader names a name-less one "primary" automatically (so { "identity.primary": { "@fields": "id" } } is the canonical minimal form — no need to invent a name). Declaring two primaries on one entity is an ERR_TOO_MANY_OCCURRENCES load error. identity.secondary / identity.reference are not singletons and DO require an explicit name.

extends: for shared abstract bases

Common base fields (id, createdAt, updatedAt) live on an abstract entity that concrete entities extend. The loader resolves extends: after all files load, so the base can live in any file in the corpus.

{
  "object.entity": {
    "name": "BaseEntity",
    "abstract": true,
    "children": [
      { "field.long":      { "name": "id" } },
      { "field.timestamp": { "name": "createdAt", "@required": true } }
    ]
  }
}
{
  "object.entity": {
    "name": "Author",
    "extends": "BaseEntity",
    "children": [
      { "field.string": { "name": "name", "@required": true } },
      { "identity.primary": { "@fields": "id" } }
    ]
  }
}

BaseEntity need not live in this project. The same extends: resolves a base published by a metadata dependency exactly as it resolves one declared locally — dependency files load first, in the same loader.load(...). The one rule that changes across that boundary: amending a node you don't own (rather than extending it) must say overlay: true, so its removal upstream fails loudly instead of silently becoming a new, disconnected object — see abstracts-and-inheritance.md.

What each port generates

TypeScript

@metaobjectsdev/codegen-ts emits one file per entity with a Drizzle table, a Zod schema, a TS type, and (with queriesFile() + routesFile()) typed finders and Fastify routes. namesFile() — wired by meta init — emits Author.names.ts beside it, holding the physical table and column names as constants; the table binding references those rather than respelling them.

// generated/acme/blog/Author.names.ts
export const AuthorNames = {
  type: "object",
  subType: "entity",
  name: "Author",
  sources: {
    primary: { type: "source", subType: "rdb", kind: "table", table: "authors" },
  },
  fields: {
    bio:  { name: "bio",  column: "bio" },
    id:   { name: "id",   column: "id" },
    name: { name: "name", column: "name" },
  },
  identities: {
    pk: { type: "identity", subType: "primary", name: "pk" },
  },
  indexes: {},
} as const;
// generated/acme/blog/Author.ts
import { pgTable, bigint, varchar } from "drizzle-orm/pg-core";
import { z } from "zod";
import { AuthorNames } from "./Author.names";

export const author = pgTable(AuthorNames.sources.primary.table, {
  id:   bigint(AuthorNames.fields.id.column, { mode: "number" }).primaryKey().generatedByDefaultAsIdentity(),
  name: varchar(AuthorNames.fields.name.column, { length: 200 }).notNull(),
  bio:  varchar(AuthorNames.fields.bio.column,  { length: 2000 }),
});

export const AuthorSchema = z.object({
  id:   z.number(),
  name: z.string().max(200),
  bio:  z.string().max(2000).optional(),
});

export type Author = z.infer<typeof AuthorSchema>;

Java

metaobjects-maven-plugin with MetaDataGeneratorMojo writes a POJO + an OMDB-backed descriptor. The OMDB ObjectManager reads the same metadata at runtime to drive CRUD.

// generated/acme/blog/Author.java
package acme.blog;

public class Author {
    private Long id;
    private String name;     // required, maxLength=200
    private String bio;      // optional, maxLength=2000

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getBio() { return bio; }
    public void setBio(String bio) { this.bio = bio; }
}

Kotlin

metaobjects-codegen-kotlin (KotlinEntityGenerator) emits a plain data class (no @Serializable — entities are Jackson-compatible, not kotlinx-serialized) and (with KotlinExposedTableGenerator) an Exposed Table object.

// generated/acme/blog/Author.kt
package acme.blog

data class Author(
    val id: Long,
    val name: String,
    val bio: String? = null,
)
// generated/acme/blog/AuthorTable.kt
package acme.blog

import org.jetbrains.exposed.sql.Table

object AuthorTable : Table("authors") {
    val id   = long("id").autoIncrement()
    val name = varchar("name", 200)
    val bio  = varchar("bio", 2000).nullable()
    override val primaryKey = PrimaryKey(id)
}

C#

MetaObjects.Codegen (via dotnet meta gen) emits an EF Core entity record, a DbSet on the generated AppDbContext, and a CREATE TABLE in the migration emitted by the Node meta migrate (schema is Node-owned, ADR-0015).

// generated/Acme/Blog/Author.cs
namespace Acme.Blog;

public record Author
{
    public long   Id   { get; set; }
    public string Name { get; set; } = string.Empty;  // required, maxLength=200
    public string? Bio { get; set; }                   // optional, maxLength=2000
}
// generated/AppDbContext.cs (excerpt)
public partial class AppDbContext : DbContext
{
    public DbSet<Author> Authors => Set<Author>();
}

Python

metaobjects.codegen emits a Python @dataclass per entity, plus a shipped FastAPI APIRouter (router_generator, FR-008 §2.3) and a shipped ObjectManager runtime (metaobjects.runtime.object_manager) for CRUD against the same metadata.

# generated/acme/blog/author.py
from dataclasses import dataclass
from typing import Optional

@dataclass
class Author:
    id: int
    name: str               # required, max_length=200
    bio: Optional[str] = None
from metaobjects.runtime.object_manager import ObjectManager

om = ObjectManager(root, driver)   # driver wraps a DB-API 2 connection
row = om.create("Author", {"name": "Ada", "bio": None})
found = om.find_by_id("Author", row["id"])

Verified by

The following conformance fixtures gate this feature's behavior across ports:

Basic entity loading

Inheritance via extends:

Identity

Attributes (@-prefixed)

Documentation common attrs (description, notes, title, …)

Auto-set timestamps

Filter / sort / data-grid layout

Overlay / merge

overlay: true licenses an attribute override

Two files can set the same attribute to different values two ways, and they mean different things:

  • Unmarked — two declarations of the same (type, package::name) that collided without knowing about each other. The value merges last-writer-wins so the loader sees one canonical tree, and the load emits ERR_MERGE_CONFLICT so somebody can fix it.
  • Marked overlay: true — the author saying "I know about the other declaration and I mean to change it." The value wins and the load is silent.

The loader already treats the flag specially — overlay: true is find-or-throw, a plain redeclaration is create-or-find — and this makes it mean one coherent thing rather than two. It is how an adopter retunes an inherited attribute (a library's @status, a dependency's @maxLength) without the toolchain calling a deliberate act a defect.

Mark the whole ancestor chain, not just the leaf. Addressing a nested node means re-declaring its ancestors, and every one of them must carry overlay: true too. Left plain, each ancestor is a same-shape redeclaration and emits WARN_DUPLICATE_DECLARATION — three warnings to change one leaf in a depth-4 tree. Marked, the load is silent.

Cross-port runner coverage: TS / Java / Kotlin / C# / Python all execute these via their respective conformance runners. See docs/CONFORMANCE.md for the per-port pass/skip ledger.

See also