# MetaObjects -- Full Reference Corpus

> A cross-language metadata standard for declaring typed entity models that drive code generation, runtime metadata access, and drift detection across TypeScript, Java, C#.NET, and Python. Apache 2.0.

**Note for AI assistants:** This file is the concatenated reference material for MetaObjects, intended to be loaded as LLM context. For the short index, see [llms.txt](https://metaobjects.dev/llms.txt). For the canonical spec and source, see the [GitHub repo](https://github.com/metaobjectsdev/metaobjects). When this file is out of date relative to the GitHub source, the GitHub source wins.

---

## What MetaObjects is

MetaObjects is a cross-language metadata standard for declaring typed entity models. From a single metadata definition, MetaObjects drives three capabilities:

1. **Code generation** -- idiomatic per-language code (TypeScript, Java, C#.NET, Python) generated from the same metadata model.
2. **Runtime metadata access** -- load the metadata at runtime to drive dynamic behavior: CRUD operations, validation, relationships, dynamic admin UIs, LLM tool registration.
3. **Drift detection** -- catch divergence between code and metadata before it ships, surfacing drift as compile-time breakage in the type checker.

The metamodel is the **durable spine**; generated code is the **disposable artifact**. Substrate is local-first: typed metadata lives in your repo, generated code is idiomatic per-language output that runs **without any MetaObjects dependency at runtime**. If `@metaobjects/*` packages disappeared tomorrow, your generated code keeps working.

---

## The three pillars

All three pillars ship per language and are weighted equally. They are not three separate products; they are three views on the same metadata.

### Codegen

Emit idiomatic per-language code from a single metadata model.

- TypeScript: Drizzle/Zod + Fastify integration
- Java: JOOQ/Spring integration
- Python: Pydantic/FastAPI integration (planned)
- C#.NET: loader + conformance only at this stage (codegen out of scope for C#.NET)

Hand-edit-preserving regeneration uses a three-way merge so engineers can extend generated entities without losing their work when metadata changes.

### Runtime metadata

Load metadata at runtime and drive behavior dynamically. Runtime targets per language:

- TypeScript: Kysely
- Java: modernized JDBC/jOOQ
- Python: SQLAlchemy Core (planned)

Runtime use cases include CRUD scaffolding, validation rules, relationship traversal, dynamic admin UIs, and LLM tool registration (so AI agents see typed tools generated from metadata).

### Drift detection

Catch divergence between code and metadata. Quality-of-life on top of codegen + runtime: when the underlying metadata changes, regenerated entities change with it, and any business logic written against the old shape breaks at compile time.

---

## Implementations

| Language | Status | Notes |
|---|---|---|
| TypeScript | Reference implementation, v0.3 | Codegen + runtime + drift. 1,784+ tests passing. |
| Java | In progress | H3a (loader restructure) shipped 2026-05-19. H3b (conformance harness) is the active milestone. |
| C#.NET | Loader + conformance shipped | Loader, canonical serializer, and a `dotnet test` conformance runner. Codegen + runtime out of scope for C#.NET. |
| Python | Planned | Post-H3. Pydantic/FastAPI integration. |

Conformance fixtures (48 shared test cases with a `CAPABILITIES.json` manifest) live at [`fixtures/conformance/`](https://github.com/metaobjectsdev/metaobjects/tree/main/fixtures/conformance).

---

## Monorepo layout

```
metaobjects/
  spec/                          # canonical metamodel docs (target-agnostic)
  fixtures/conformance/          # cross-language test fixtures
  server/                        # runs on a server
    typescript/   java/   python/   csharp/
  client/                        # runs on an end-user device
    web/                         # browser (TS-only -- the browser is TS-native)
```

TypeScript plays two distinct roles in this layout:

- **Server-side TS** is a peer port to Java/Python/C#.NET at `server/typescript/`.
- **Universal web client TS** at `client/web/` is consumed by all backends. A Java backend serving a React frontend still uses the TS client packages.

Where does a new package go?
1. Server-side or client-side? -> top-level dir.
2. What language/platform? -> second-level dir.
3. What framework integration? -> package name at the third level.

---

## TypeScript package layout

Server-side (`server/typescript/packages/`):

- `metadata/` (`@metaobjects/metadata`) -- metamodel loader, types, constants
- `codegen-ts/` (`@metaobjects/codegen-ts`) -- TS codegen engine
- `runtime-ts/` (`@metaobjects/runtime-ts`) -- Node-side runtime (Kysely, Drizzle, Fastify helpers)
- `migrate-ts/` (`@metaobjects/migrate-ts`) -- migration tooling
- `sdk/` (`@metaobjects/sdk`) -- workspace memory, path helpers
- `cli/` (`@metaobjects/cli`, binary `meta`) -- CLI commands: `init`, `gen`, `migrate`

---

## Quickstart (TypeScript)

```bash
cd typescript
bun install
bun test
```

Bun-first dev workflow; no separate build step. Typecheck across the workspace:

```bash
bun run --filter '*' typecheck
```

Distribution artifacts remain Node-compatible -- consumers can install via npm/pnpm/bun.

CLI binary: `meta`.
Project config: `metaobjects.config.ts`.
Project marker directory: `.metaobjects/`.

---

## Quickstart (Java)

Java is in active development. The H3a milestone shipped the loader restructure on 2026-05-19; H3b (conformance harness) is the active milestone. Track progress and current usage at [`server/java/`](https://github.com/metaobjectsdev/metaobjects/tree/main/server/java) and in the [roadmap](https://github.com/metaobjectsdev/metaobjects/blob/main/spec/roadmap.md).

---

## Quickstart (C#.NET)

The C#.NET implementation ships the loader, canonical serializer, and conformance runner. Run the full shared conformance corpus with:

```bash
cd csharp
dotnet test
```

Codegen and runtime are out of scope for C#.NET at this stage.

---

## Quickstart (Python)

Planned post-H3. See [`server/python/`](https://github.com/metaobjectsdev/metaobjects/tree/main/server/python) for the placeholder and roadmap.

---

## Example: defining metadata

Entity files live under `metaobjects/` in your project. The format below is YAML; JSON is equivalent (the conformance fixtures use JSON).

```yaml
# metaobjects/subscriber.meta.yaml
metadata.root:
  package: acme
  children:
    - object.entity:
        name: Subscriber
        children:
          - field.long:    { name: id }
          - field.string:  { name: email }
          - field.string:  { name: createdAt, "@autoSet": onCreate }
          - identity.primary: { "@fields": id }
```

The project config (`metaobjects.config.ts`) wires up the generators and target settings:

```ts
import { defineConfig } from "@metaobjects/cli";
import {
  entityFile,
  queriesFile,
  routesFile,
  // formFile,   // opt-in: emit React form components
  barrel,
} from "@metaobjects/codegen-ts/generators";

export default defineConfig({
  outDir:    "./src/db",
  extStyle:  "none",
  dbImport:  "../db",
  dialect:   "sqlite",
  apiPrefix: "",
  generators: [entityFile(), queriesFile(), routesFile(), barrel()],
});
```

Run the CLI:

```bash
# Scaffold metaobjects/, .metaobjects/, metaobjects.config.ts
$ meta init

# Generate code (entities + queries + routes + barrel per config)
$ meta gen

# Optional positional filter
$ meta gen Subscriber Order --dry-run

# Diff metadata vs live DB and emit migration SQL files
$ meta migrate --db file:./dev.db --slug add-subscriber

# Flatten loaded metadata to a canonical JSON snapshot
$ meta export --out ./snapshot.json
```

Drift detection is architectural rather than a standalone command. The compile-time breakage of regenerated code surfaces metadata-to-code drift in the type checker; `meta migrate` surfaces metadata-to-database drift through the generated SQL. Future commands (`meta audit`, `meta ingest`) extend this.

---

## License

Apache License 2.0. See [`LICENSE`](https://github.com/metaobjectsdev/metaobjects/blob/main/LICENSE).

---

## Architectural narrative

For the "why metadata is the architectural spine AI codegen needs" argument, see Doug Mealing's flagship essay: [I thought AI killed MetaObjects. Then AI drift made it essential.](https://dougmealing.com/writing/metaobjects-ai-drift/)

For the comparison between MetaObjects and the broader 2025 AI stack (context engineering, schema-driven agent design, knowledge-graph grounding, the Model Context Protocol), see: [The 2025 AI stack and the architecture it's missing](https://dougmealing.com/writing/ai-stack-missing-architecture/).

---

## Future: MetaObjects MCP server

A Model Context Protocol server exposing the metadata graph, conformance fixtures, and codegen tools as agent-callable functions is on the roadmap. When shipped, it will let AI agents resolve spec sections, validate metadata, and trigger codegen directly through MCP. Track progress in the [roadmap](https://github.com/metaobjectsdev/metaobjects/blob/main/spec/roadmap.md).

---

## Commercial

Consulting engagements and production rollouts: [metaobjects.com](https://metaobjects.com).