diff --git a/data/de/db-hafas-mgate.json b/data/de/db-hafas-mgate.json
new file mode 100644
index 0000000..0937e47
--- /dev/null
+++ b/data/de/db-hafas-mgate.json
@@ -0,0 +1,61 @@
+{
+  "name": "Deutsche Bahn (DB)",
+  "type": {
+    "hafasMgate": true
+  },
+  "supportedLanguages": [
+    "en",
+    "de",
+    "fr",
+    "es"
+  ],
+  "options": {
+    "auth": {
+      "aid": "n91dB8Z77MLdoR0K"
+    },
+    "checksumSalt": "6264493855566A34304B356676787766",
+    "client": {
+      "id": "DB",
+      "name": "DB Navigator",
+      "type": "AND",
+      "v": 19040000
+    },
+    "endpoint": "https://reiseauskunft.bahn.de/bin/mgate.exe",
+    "ext": "DB.R19.12.a",
+    "lineModeMap": {
+      "1": "Long-distance train (ICE)",
+      "128": "Metro",
+      "16": "Rapid Transit (S)",
+      "2": "Long-Distance Train (IC/EC)",
+      "256": "Tram",
+      "32": "Bus",
+      "4": "Local Train (D)",
+      "512": "Taxi",
+      "64": "Ferry",
+      "8": "Local Train (RE/RB)"
+    },
+    "locationIdentifierType": "db",
+    "standardLocationIdentifierCountries": [
+      51,
+      53,
+      54,
+      55,
+      56,
+      70,
+      71,
+      74,
+      76,
+      80,
+      81,
+      82,
+      83,
+      84,
+      85,
+      86,
+      87,
+      88
+    ],
+    "standardLocationIdentifierType": "ibnr",
+    "version": "1.18"
+  }
+}
diff --git a/data/de/db-hafas-query.json b/data/de/db-hafas-query.json
new file mode 100644
index 0000000..8521c49
--- /dev/null
+++ b/data/de/db-hafas-query.json
@@ -0,0 +1,49 @@
+{
+  "name": "Deutsche Bahn (DB)",
+  "type": {
+    "hafasQuery": true
+  },
+  "supportedLanguages": [
+    "en",
+    "de",
+    "fr",
+    "es"
+  ],
+  "options": {
+    "endpoint": "https://reiseauskunft.bahn.de/bin/",
+    "lineModeMap": {
+      "1": "Long-distance train (ICE)",
+      "128": "Metro",
+      "16": "Rapid Transit (S)",
+      "2": "Long-Distance Train (IC/EC)",
+      "256": "Tram",
+      "32": "Bus",
+      "4": "Local Train (D)",
+      "512": "Taxi",
+      "64": "Ferry",
+      "8": "Local Train (RE/RB)"
+    },
+    "locationIdentifierType": "db",
+    "standardLocationIdentifierCountries": [
+      51,
+      53,
+      54,
+      55,
+      56,
+      70,
+      71,
+      74,
+      76,
+      80,
+      81,
+      82,
+      83,
+      84,
+      85,
+      86,
+      87,
+      88
+    ],
+    "standardLocationIdentifierType": "ibnr"
+  }
+}
diff --git a/data/de/vrr-efa.json b/data/de/vrr-efa.json
new file mode 100644
index 0000000..fdac4ba
--- /dev/null
+++ b/data/de/vrr-efa.json
@@ -0,0 +1,13 @@
+{
+	"name": "Verkehrsverbund Rhein-Ruhr (VRR)",
+	"type": {
+		"efa": true
+	},
+	"supportedLanguages": [
+		"en",
+		"de"
+	],
+	"options": {
+		"endpoint": "https://efa.vrr.de/standard/"
+	}
+}
diff --git a/readme.md b/readme.md
index bcda01b..64bd886 100644
--- a/readme.md
+++ b/readme.md
@@ -5,8 +5,89 @@
 
 ## Format
 
-to be discussed
+### Overall Structure
 
+There is a single JSON file per API endpoint. It must contain the following
+properties:
+
+* `name`: endpoint name
+* `type`: endpoint protocol description (see below)
+* `supportedLanguages`: list of supported languages (see below)
+* `coverage`: the geographic area this endpoint provides results for (see below)
+* `options`: protocol-specific options (not specified here)
+
+### Endpoint Protocol
+
+```js
+{
+    "type": {
+        "hafasMgate": true
+    }
+}
+```
+
+Known protocols:
+* `efa`
+* `hafasMgate`
+* `hafasQuery`
+* `navitia`
+* `otpGraphQl`
+* `otpRest`
+
+### Supported Languages
+
+```js
+{
+    "supportedLanguages": [
+        "en",
+        "de",
+        "fr",
+        "es"
+    ]
+}
+```
+
+A list of ISO-639-1 language codes describing the languages supported by the
+endpoint.
+
+### Coverage Information
+
+Describes the geographic area this endpoint provides results for.
+
+```js
+{
+    "coverage": {
+        "realtimeCoverage": { /* ... */ },
+        "regularCoverage": { /* ... */ },
+        "anyCoverage": { /* ... */ }
+    }
+}
+```
+
+There's three coverage categories:
+* `realtimeCoverage`: In this area the endpoint provides accurate and highly detailed information.
+  This is typically where the operator can rely on live data about their own vehicles.
+
+* `regularCoverage`: In this area reasonably complete data is available, but e.g. realtime data from other operators is missing or inaccurate quite often.
+
+* `anyCoverage`: In this area only incomplete and/or shallow data is available. This is commonly the case in areas outside of the operating area,
+e.g. long-distance trains & buses but not local modes of transport, or planned data but not realtime data.
+You could say that this is the extent to which, in a region, the API provides any data.
+
+At least one coverage category must be provided.
+
+```js
+{
+    "area": { /* GeoJSON polygon */ },
+    "region": [ /* ISO-3166-1/2 codes */ ]
+}
+```
+
+The following properties are defined for each coverage category:
+* `area`: a GeoJSON polygon defining the geographic area. This can be reasonably coarse, meter-precision for example is neither necessary nor practically meaningful.
+* `region`: an array of ISO-3166-1 alpha 2 country codes, or ISO-3166-2 region codes covered.
+
+Both fields should be provided.
 
 ## Contributing