MD-Models: Human-Readable, Model-Driven Specifications for FAIR Research Data

What's inside model.md — the single source of truth: the data model written in plain Markdown. gen.toml — generation config mapping the model to all generated artifacts. code/ — programming libraries auto-generated from the model: Python (dataclass, Pydantic, Pydantic-XML), TypeScript (plain and Zod), Rust, Go, and Julia. schemes/ — technical schemas: JSON Schema, XML Schema (XSD), Protobuf, GraphQL, and LinkML. diagrams/ — a Mermaid class diagram of the model. config.toml, docker-compose.yml, Dockerfile.*, start.sh — the local backend stack: PostgreSQL + pgvector, a REST API, and an MCP server.

UploadDataset.ipynb — a Jupyter notebook that creates and lists datasets through the REST API. chats/ — example Claude Desktop conversations using the MCP server to create and query experiments. README.md — full setup and usage instructions. How to use it Inspect the model.

Open model.md to see the authoritative specification, and browse code/ and schemes/ for the artifacts generated from it. Regenerate artifacts. With the mdmodels toolkit, run the generator against gen.toml to reproduce every library, schema, and diagram from model.md.

Run the local stack. With Docker installed, run ./start.sh to launch the database, REST API (localhost:8800), and MCP server (127.0.0.1:7001/mcp). Add and query data.

Use UploadDataset.ipynb to create and list Experiment datasets via the REST API, or connect Claude Desktop to the MCP server for LLM-assisted data entry and querying (see README.md for the configuration). For complete prerequisites, service verification steps, and example commands, see README.md in the dataset.