diff --git a/README.md b/README.md
index 2f9bfa91..aa61600e 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,6 @@
 # EVM-based Chains
 
-Listed by chainId according to EIP-155
-
-Data source available on `_data/chains.json`
+The source data is in _data/chains. Each chain has its own file with the filename being the [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md) representation as name and `.json` ans extension.
 
 ## Example
 
@@ -24,10 +22,43 @@ Data source available on `_data/chains.json`
   "infoURL": "https://ethereum.org",
   "shortName": "eth",
   "chainId": 1,
-  "networkId": 1
+  "networkId": 1,
+  "icon": "ethereum",
+  "explorers": [{
+    "name": "etherscan",
+    "url": "https://etherscan.io",
+    "icon": "etherscan",
+    "standard": "EIP3091"
+  }]
 }
 ```
 
+when an icon is used in either the network or a explorer there must be a json in _data/icons with the name used (e.g. in the above example there must be a `ethereum.json` and a `etherscan.json` in there) - the icon jsons look like this:
+
+```json
+
+[
+    {
+      "url": "ipfs://QmdwQDr6vmBtXmK2TmknkEuZNoaDqTasFdZdu3DRw8b2wt", 
+      "width": 1000,
+      "height": 1628,
+      "format": "png"
+    }
+]
+
+```
+
+where:
+ * the URL must be a IPFS url that is publicly resolveable
+ * width and height are optional - but when one is there then the other must be there also
+ * format is either "png", "jpg" or "svg"
+
+## Aggregation  
+
+There are also aggregated json files with all chains automatically assembled:
+ * https://chainid.network/chains.json
+ * https://chainid.network/chains_mini.json (miniaturized - fewer fields for smaller filesize)
+
 ## Usages
 
  * [chainlist.org](https://chainlist.org) or [networklist-org.vercel.app](https://networklist-org.vercel.app) as a staging version with a more up-to-date list