Skip to main content

L0: Contract-first

L0 is the first adoption level. You import GooiAppSpec types and validate spec documents at build time. No runtime dependency is required.

Why this exists​

When teams or services share a spec structure, they need a typed contract to enforce consistency. Without shared types, different services interpret the same spec document differently. There is no way to catch mismatches at build time.

L0 gives you stable TypeScript types for the full spec schema and Zod-powered validation with descriptive error messages. You can use it from a service boundary, a CI validation script, or a tooling layer without taking any runtime dependency.

Installation​

bun add @gooi/app
# or
npm install @gooi/app

Usage​

import type { GooiAppSpec } from "@gooi/app/spec";
import { parseGooiAppSpec } from "@gooi/app/spec";

// Use GooiAppSpec as a shared type between services or teams
const spec: GooiAppSpec = loadYaml("./app.yml");

// Validate a spec document and get descriptive errors on failure
const result = parseGooiAppSpec(spec);
if (!result.success) {
  console.error(result.error.issues);
  process.exit(1);
}

What you get​

  • GooiAppSpec: the full TypeScript type for a spec document
  • parseGooiAppSpec(input): validates a parsed YAML object against GooiAppSpec@1.0.0 and returns a Zod SafeParseResult
  • Zero runtime overhead: no kernel, no compiler, no provider loading

When to use L0​

Use L0 when:

  • You want to validate spec documents in a CI pipeline without compiling them
  • You are building tooling (linters, code generators, documentation tools) that operates on spec documents
  • You are integrating with a Gooi runtime from a service boundary and need typed spec contracts without running the runtime yourself

What's next​