Spec & format · target: openapi schema to seed data format

OpenAPI to SQL for Seed file format fixture: Full Mapping

User wants to know what a seed file should contain for their spec to be useful.

Direct answer

Converting the Seed file format fixture schema to SQL is a one-to-one mapping for 6 constraints in the DDL, and the foreign key order is the only part that needs reasoning.

The mapping assumes the PostgreSQL dialect, which is the only dialect the CLI emits; a native enum type is not used because it cannot be altered in a transaction.

The mapping table below lists the constructs of Seed file format fixture and their SQL form; the enum row shows the one construct that is written as a CHECK constraint rather than as a native enum type.

Data as of 2026-11-18 · source: 0 Stack Overflow questions, 7 Hacker News stories, @apidevtools/openapi-schemas at 29,968,250 monthly downloads · negative-case messages reproduced by executing the fixture against a local SQL engine (Node.js v24.22.0, engine 3.53.4) at 2026-11-18T11:53:54.233Z

The mapping — Seed file

The table below maps each construct in the Seed file format fixture to what it becomes in SQL. 6 constraints in the DDL all have a SQL equivalent: a primary key per table, a foreign key per reference, a NOT NULL per required column and a CHECK for every enum, range and length declaration. The rows are ordered so the parent table comes first.

The cases that need a decision

One construct needs a decision rather than a translation. On Seed file format fixture, the declaration on entities.count is "count" > 0. The generator does not create a native enum type, because a native enum has to be created separately and cannot be changed inside a transaction; it writes the declaration as a CHECK constraint on the column instead. The value that breaks the declaration ships as a negative case, and the reference engine rejected it with "CHECK constraint failed: entities_count_check".

A worked example

The Seed file format fixture is small enough to convert by hand, which is the point. The generator produces 1 tables — entities — and each child table is written after the table it references. Doing it by hand for one fixture takes a few minutes; doing it for every schema change after that is the cost this removes.

Type mapping (PostgreSQL only)

SchemaSeed emits one SQL dialect, and it is PostgreSQL. The fixture on this page is written in it: uuid stays uuid, a timestamp becomes timestamptz, and json becomes jsonb, and every constraint is emitted with PostgreSQL semantics. No other database engine is targeted, so the type mapping below is the whole mapping.

Checking the result

A converted schema is worth checking against the database rather than by eye. The reference engine accepted the DDL for all 64 fixtures in this matrix and rejected the deliberately invalid rows with the expected error class each time, which is the check that catches a mistranslated constraint before it reaches a developer database.

Boundary probes for every constrained column in Seed file format fixtureOne violating value per constraint, with the boundary it crosses.
TableColumnDeclared ruleProbe valueWhy it is invalid
entitiescount> 00not strictly positive
entitiesmodeone of insert, upsert, truncatenot_a_real_membernot a declared member
entitiesmodeone of insert, upsert, truncateINSERTwrong case
Insert order for Seed file format fixture, derived from its foreign keysThe generator sorts the tables by this order before writing a single row.
TableReferenced byWritten
entities—first, no dependencies
Schema construct to SQL construct for Seed file format fixtureDerived from the fixture itself, not from a generic table.
Schema constructSQL formExample in this fixture
object schemaCREATE TABLE entities3 NOT NULL columns
required + foreign keyNOT NULL + FOREIGN KEY REFERENCESnone in this fixture
enumCHECK (col IN (...))insert, upsert, truncate
minimum / rangeCHECK (col >= n)>0
uniquea plain column; the DDL carries no UNIQUE constraintname is declared unique in the schema
spec_seedformat.openapi.yaml

npx --yes @wenlu8848/schemaseed validate --input ./spec_seedformat.openapi.yaml

Download spec_seedformat.openapi.yaml

openapi: "3.0.3"
info:
  title: "Seed file format fixture"
  version: "1.0.0"
  description: "The format contract table on this page lists what a seed file has to record for each part of a spec. The mode enum is the one field that changes what the generated SQL does rather than what it contains. The count constraint is positive, so a file section that declares zero rows is invalid. The name uniqueness is what lets the generator tell two spec components apart."
paths: {}
x-domain-id: "spec_seedformat"
x-dialect: "postgres"
components:
  schemas:
    entities:
      type: "object"
      x-primary-key: "id"
      required: ["id", "name", "count", "mode"]
      properties:
        id:
          type: "string"
          format: "uuid"
        name:
          type: "string"
          x-unique: true
        count:
          type: "integer"
          minimum: 1
        mode:
          type: "string"
          enum: ["insert", "upsert", "truncate"]

Frequently asked questions

Is the mapping lossless?
For Seed file format fixture, 6 constraints in the DDL all have a SQL equivalent, and the mapping table above lists each one with the construct it came from. The enum, range and length declarations become CHECK constraints on the column.
Why not use a native enum type?
Because CREATE TYPE runs outside the transaction and cannot be altered while it is open. The CLI does not create an enum type either: it reads the members out of the schema and writes them as a CHECK constraint on the column, so the database refuses a value that is not a member — entities.count on this fixture.
Does SchemaSeed emit SQL for a database other than PostgreSQL?
No. The SQL export is PostgreSQL only: uuid, timestamptz and jsonb are the PostgreSQL types and every constraint is emitted with PostgreSQL semantics. The Seed file format fixture was accepted by the reference engine.
How are foreign keys ordered?
Topologically, from the reference graph in the schema. For Seed file format fixture the order is entities, and the insert-order table lists each parent.

Run it against your own schema

SchemaSeed is MIT licensed and free: unlimited local generation, no account, no telemetry and no usage limit. It reads your schema file on your own machine, so nothing is uploaded anywhere. If it saves you time, you can support the project.

Get SchemaSeed — free Support the project

Questions: support@schemaseed.drz8848.win