Skip to content

README.md

Latest commit

 

History

History
90 lines (79 loc) · 5.71 KB

README.md

File metadata and controls

90 lines (79 loc) · 5.71 KB
Raw

MetaObjects Documentation

This directory is the user-facing entry point to MetaObjects: the feature reference (what the metamodel can express, and what each language port emits for it) and the per-port quickstarts (how to install, wire, generate, and use the output).

If you are a developer adopting MetaObjects, start with your language's quickstart under ports/. If you are an LLM helping a developer adopt it, the feature files under features/ are the source of truth — each file is self-contained and shows the same Author entity across all five ports so you can copy-paste cross-port without context-switching.

Layout

docs/
├── README.md                    # this file
├── CONFORMANCE.md               # inverse index: fixture → feature doc + per-port pass status
├── features/                    # one file per metamodel feature — see `ls docs/features/`
│                                 # for the definitive, always-current list; as of this
│                                 # writing:
│   ├── entities.md
│   ├── source-kinds.md
│   ├── relationships.md
│   ├── field-types.md
│   ├── templates-and-payloads.md
│   ├── loaders.md
│   ├── migrations-and-drift.md
│   ├── migrations/                  # per-version migration guides (e.g. 0.x → 1.0)
│   ├── api-contract.md          # cross-port REST contract (the universal browser client speaks it)
│   ├── abstracts-and-inheritance.md # abstract: true + extends: — author-side shape reuse
│   ├── extending-with-providers.md  # custom metamodel subtypes/attrs via MetaDataTypeProvider
│   ├── yaml-authoring.md
│   ├── cli.md                       # CLI command matrix across all five ports
│   ├── codegen-concepts.md          # declarative template-codegen scopes (perEntity/perPackage/perModel)
│   ├── codegen-data-shapes.md       # the neutral template data dict shared cross-port
│   ├── downstream-metadata-decisions.md # guidance for adopters extending the metamodel
│   ├── generated-mutations.md       # generated POST/PATCH mutation surface
│   ├── image-upload.md              # view.image form control (TS-web)
│   └── own-your-codegen.md          # scaffold-and-own generator ownership (ADR-0034)
└── ports/                       # one file per language/framework port
    ├── typescript.md
    ├── typescript-client.md     # browser-side TS (React, TanStack, Angular, codegen pairs)
    ├── java.md
    ├── kotlin.md
    ├── csharp.md
    └── python.md

If this list and ls docs/features/ ever disagree, trust the directory listing — this tree is documentation, not the source of truth.

When to read which

You want to … Read
Pick a language and ship a small CRUD app ports/<lang>.md
Understand what object.entity, source.rdb, template.prompt mean features/
Compare what TS vs Java vs Kotlin vs C# vs Python emit for the same metadata any features/*.md — every feature shows all five ports side-by-side
Author metadata in YAML instead of JSON features/yaml-authoring.md
Wire prompt construction (FR-004) features/templates-and-payloads.md
Share a metadata shape across multiple instances (abstracts, extends:) features/abstracts-and-inheritance.md
Add a custom metamodel subtype or attribute to a downstream project features/extending-with-providers.md + recipes/extending-metaobjects-with-providers.md
Wire the universal browser client (React + TanStack, or Angular 18) to any backend ports/typescript-client.md (see §Angular 18 for the Angular tier) + features/api-contract.md
Know which feature is supported in which port today the capability matrix in the root README.md or the per-port "Capability snapshot" table
See which conformance fixtures gate each feature (and which port passes which) CONFORMANCE.md
Read the canonical spec (target-agnostic) ../spec/
Find a release recipe (Cloudflare D1, etc.) recipes/
See the deeper design rationale for a feature superpowers/specs/

Conventions used in these docs

  • Named example. Every feature file uses an Author entity in the acme::blog package, with id (long), name (string, required), and bio (string, optional). Stable across files so you can cross-reference behavior without re-loading unrelated context.
  • Both authoring formats shown. Canonical JSON (the on-disk interchange) and sigil-free YAML (the AI-first authoring front-end, ADR-0006).
  • Generated output shown per port. TS / Java / Kotlin / C# / Python. If a port doesn't yet support a feature, the section says so explicitly with a pointer to the port's roadmap.
  • Code blocks are complete. No "rest omitted" — drop into a fresh project and run.

See also