@dforge-core/metadata

Canonical dForge authoring registries, module-file types, and JSON schemas — the single source of truth shared by the web app, the SDK, the diagram library, the CLI, the MCP server, and the VS Code extension.

• Runtime-dependency-free. Safe to import anywhere — editors, bundled web apps, Node CLIs, MCP servers.
• One source of truth. The registries mirror the platform metadata seed (server/database/system-modules/metadata/seed-data/) and the structural types mirror the JSON schemas under docs/schemas/. Parity tests fail the build if either drifts.

Install

pnpm add @dforge-core/metadata

What's inside

| Surface | Exports | | --- | --- | | Field types | fieldTypes, fieldTypeCds, isFieldTypeCd, getFieldType, fieldTypesByColumnType | | Base datatypes | baseDatatypes, baseToDbDatatype | | Column types | columnTypes, getColumnType | | Traits | traits, getTrait, expandTrait, expandTraits | | Derivation | deriveDbDatatype, deriveBaseDatatype, defaultParams, NUMERIC_TOTAL | | Aggregation | AggType, AGG_TYPE_LIST | | Display flags | flagDefs (V Visible · I Identity · E Editable · M Mandatory · H Hidden) | | View / report kinds | dataViewKinds, vizTypes, chartTypes | | Scalar enums | FieldTypeCd, BaseDatatypeCd, ColumnTypeCd, FlagCd, AlignType | | Module-file types | ManifestDef, EntityDef, DataViewsFile, ReportsFile, MenusFile, FoldersFile, RolesFile, SettingsFile, JobsFile, TriggersFile, WebhooksFile, PrintTemplatesFile, SeedDataFile, ActionsFile, … | | Filter expression | Filter, FilterCondition, FilterGroup, SortClause | | JSON schemas | ./schemas/<name>.schema.json (see Schemas) |

Registries & derivation

An author picks a friendly fieldTypeCd; the helpers derive the physical metadata so no one types a raw SQL type by hand.

import {
  getFieldType,
  isFieldTypeCd,
  deriveDbDatatype,
  deriveBaseDatatype,
  defaultParams,
} from "@dforge-core/metadata";

isFieldTypeCd("currency");          // true
isFieldTypeCd("reference");         // false — not a real code (it's `lookup`)

getFieldType("currency");
// { cd: "currency", columnType: "D", baseDatatypeCd: "number", precision: 2, ... }

deriveDbDatatype("currency");       // "numeric(18,2)"
deriveDbDatatype("text");           // "varchar"
deriveDbDatatype("textarea");       // "text"
deriveDbDatatype("lookup");         // null — relationship-backed, no own column
deriveBaseDatatype("color");        // "string"
defaultParams("number");            // { min: 0, max: 10000 }

Traits

import { expandTrait, expandTraits } from "@dforge-core/metadata";

// Expand a trait into the FieldDef map it contributes to an entity.
expandTrait("audit", "invoice");
expandTraits(["identity", "audit"], "invoice");

Module-file types

The structural types describe the authoring shape of every file in a .dforge module package — the same shapes the JSON schemas validate.

import type { ManifestDef, EntityDef, DataViewsFile } from "@dforge-core/metadata";

const entity: EntityDef = {
  description: "Customer",
  dbObject: "customer",
  fields: {
    /* … */
  },
};

Note: these are the authoring shapes. The resolved runtime model returned by the API (metadata.getModel) is a different contract — see @dforge/sdk's Model* types, which reuse the scalar enums from this package.

JSON schemas

The 14 canonical schemas are shipped alongside the types and stay byte-identical to docs/schemas/ (a parity test enforces it; prepack re-syncs before publish). Import them directly or point a validator / editor at the files.

import entitySchema from "@dforge-core/metadata/schemas/entity.schema.json" with { type: "json" };

// VS Code settings.json — validate module files against the shipped schemas
"json.schemas": [
  {
    "fileMatch": ["entities/*.json"],
    "url": "./node_modules/@dforge-core/metadata/schemas/entity.schema.json"
  }
]

Available: manifest, entity, data_views, folders, menus, roles, settings, reports, jobs, triggers, webhooks, print_templates, traits, seed_data.

Source of truth & parity

This package never edits the canonical sources — it mirrors them and guards the mirror:

• Registries mirror the platform metadata seed; test/registries.test.ts fails if a code drifts from field_types.json (and a compile-time coverage guard fails if the FieldTypeCd union and the fieldTypes array diverge).
• Schemas are copied from docs/schemas/ by pnpm sync-schemas; test/schemas.test.ts fails if the shipped copy drifts. prepack re-syncs.

When consumed standalone (no monorepo around the package) the parity checks are skipped — the shipped data is authoritative on its own.

Scripts

pnpm build          # tsc → dist/
pnpm test           # vitest (registry + schema parity)
pnpm sync-schemas   # refresh schemas/ from docs/schemas/

License

MIT