OpenDB Specification

A machine-readable format for documenting relational databases — the database counterpart to OpenAPI.

An API description tells you how to call a service. It says nothing about the database behind it, which is where the questions that survive a rewrite live: what does this column mean, which of these tables is the source of truth, and how do I get a post with its author and its tags.

opendb: 1.0.0
info:
  title: Blog
  type: postgresql

tables:
  posts:
    columns:
      id:    { type: bigint, nullable: false, autoIncrement: true }
      status: { type: varchar(20), enum: [draft, published] }
    primaryKey: [id]

queries:
  published_posts_with_tags:
    summary: Published posts with their author and tag list
    tables: [posts, authors, tags, post_tags]
    sql: |
      SELECT p.id, p.title, a.display_name AS author
      FROM posts p JOIN authors a ON a.id = p.author_id
      WHERE p.status = 'published' LIMIT :limit

The specification

• OpenDB 1.0.0 — the specification
• JSON Schema — for validating a document
• Example — a complete document
• Repository — issues, merge requests, governance

Status

1.0.0 is not frozen. OpenDB has one implementation (Docy), and a format with one implementation is a file format rather than a standard. Breaking changes stay on the table until there is a second — which is the single most useful thing anyone could contribute.