Understanding Recap’s design.

  1. Overview
  2. Systems
  3. Paths
  4. Clients
  5. Converters
  6. CLI
  7. Gateway
  8. Python API


You should understand the following concepts before using Recap.


Systems are Recap’s term for remote schema sources. They’re typically databases, schema registries, data catalogs, and so on.

Each system has a name and a URL. Systems are normally defined as environment variables.

export MY_PG=postgresql://user:pass@host:port/dbname

See Recap’s configuration documentation for more information.


Recap takes a path as an argument when listing or reading schemas. Each system has its own path structure. For example, PostgreSQL has paths like:


You can browse paths using the ls command:

recap ls my_pg
recap ls my_pg/testdb
recap ls my_pg/testdb/public

This example uses Recap’s CLI. You can also use Recap’s Python API or gateway.


Each system has a client implementation. Clients connect to remote systems, read schemas, and convert them to Recap schemas. Clients use converters to convert to Recap schemas.


Converters are used to convert to and from Recap schemas. Unlike clients, converters do not connect to remote systems. They just take an in-memory schema and return a Recap schema (or vice-versa).


Recap’s CLI is a command line interface for connecting to systems and reading schemas. It’s a thin wrapper around Recap’s Python API.


Recap’s gateway is a stateless HTTP/JSON server that you can use to query systems and schemas. The server doesn’t require any database or storage. It’s simply connects to systems and returns Recap schemas.

The gateway is useful if you’re not using Python, but want to use Recap programmatically.

Python API

Recap is written in Python and is designed to be used as a Python library. See the Python documentation for more information.