diff --git a/README.md b/README.md
index e7de5e4a6..aaa7a97ea 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,24 @@
 [![Build Status](https://travis-ci.org/Materials-Consortia/optimade-python-tools.svg?branch=master)](https://travis-ci.org/Materials-Consortia/optimade-python-tools)
 
-A library of tools for implementing and consuming
-[OPTiMaDe](http://www.optimade.org) APIs in Python.
+The aim of OPTiMaDe is to develop a common API, compliant with the
+[JSON API 1.0](http://jsonapi.org/format/1.0/) spec, to enable interoperability
+among databases that contain calculated properties of existing and hypothetical
+materials.
 
-The aim of OPTiMaDe is to develop a common API, compliant
-with the [JSON API 1.0](http://jsonapi.org/format/1.0/)
-spec, to enable interoperability
-among databases
-that contain calculated properties of
-existing and hypothetical materials.
+This repository contains a library of tools for implementing and consuming
+[OPTiMaDe](http://www.optimade.org) APIs in Python.
 
 ### Status
-This library is under development. Progress is expected during the [CECAM Workshop on Open Databases Integration for Materials Design](https://www.cecam.org/workshop-4-1525.html) during the week of June 11, 2018 to June 15, 2018.
+Both the OPTiMaDe specification and this repository are **under development**.
+
+### Links
+
+ * [OPTiMaDe Specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/develop/optimade.md), the human-readable specification that this library is based on
+ * [OpenAPI](https://github.com/OAI/OpenAPI-Specification), the machine-readable format used to specify the OPTiMaDe API in [`openapi.json`](openapi.json)
+ * [Interactive documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json#/operation/get_structures_structures_get) generated from [`openapi.json`](openapi.json) (see also [interactive JSON editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/master/openapi.json#/operation/get_structures_structures_get))
+ * [pydantic](https://pydantic-docs.helpmanual.io/), the library used for generating the OpenAPI schema from [python models](optimade/server/models)
+ * [FastAPI](https://fastapi.tiangolo.com/), the framework used for generating the reference implementation from the [`openapi.json`](openapi.json) specification.
+ * [lark](https://github.com/lark-parser/lark), the library used to parse the filter language in OPTiMaDe queries
 
 ### Developing
 
@@ -32,7 +39,7 @@ pip install -e .
 # - starts server in background
 # - ensures and uses ~/dbdata directory to store data
 conda install -c anaconda mongodb
-mkdir -p ~/dbdata && mongod --dbpath ~/dbdata --syslog --fork 
+mkdir -p ~/dbdata && mongod --dbpath ~/dbdata --syslog --fork
 
 # Start a development server (auto-reload on file changes at http://localhost:5000
 # You can also execute ./run.sh