diff --git a/README.md b/README.md
new file mode 100644
index 0000000..af76a00
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# CIC schemas
+
+This project aims to contain sufficient tools for generation, validation and packaging of metadata describing impacts and externalities from the use of Community Inclusion Currencies (CICs).
+
+The expression of impacts and externalities will henceforth be referred to as _certifications_.
+
+_This is a work in process. It is in alpha state, and may radically change at any time._
+
+
+## Using the project
+
+To build json schemas and run tests, please install the python dependencies in `requirements.txt`:
+
+`pip install -r requirements.txt` 
+
+(You may want to use a virtual environment)
+
+
+## Structure
+
+Each unit of metadata consists of two parts:
+
+1. RDF documents the certifications of vouchers, accounts and transactions.
+
+2. A JSON metadata structure bundlinf certficiations as tradeable NFTs.
+
+NFT tooling is at the current time intended for EVM blockchains only.
+
+
+## Certification vocaularies
+
+Four base vocabularies are used to define the certifications.
+
+* [`foaf`](http://xmlns.com/foaf/0.1/) - well-known library used to describe human resources and relationships.
+* `evm` - EVM specific resources like transactions and account addresses.
+* `cic` - concepts specific to CICs, e.g. _Unit of Account_, _voucher validity_ and other parameters decribing kinds of economic activity.
+* `ge` - subject Impact types and areas of interest, according to Grassroots Economics - the organization pioneering this work.
+
+
+### Including other vocabularies
+
+Authors of certifications may express impacts and externalities in vocuabularies managed by themselves or other interested parties.
+
+For example, Grassroots Economics can author a certification with the fictious **We Do Good NGO** as intended recipient. When doing so, elements from the `wedogood` vocabulary is used to reference specific points of interest in terms recognized by the recipient's systems.
+
+`wedogood` can furthermore be a vocabulary that systems of the fictious **We Do More Good NGO** trusts and recognizes, which in turn can improve reliability and confidence for them.
+
+
+### Files
+
+Example certification files used for initial development are (`test_tx.rdf` and `test_voucher.rdf`).
+
+Note these schemas are not yet defined. They only exist as fictious references in the example files. 
+
+
+## EVM NFT
+
+The JSON metadata implements the **ERC721** standard, as well as parts of the **Opensea** metadata standard.
+
+It also contains immutable references to one or more certifications which the NFT represents.
+
+Apart from the `certifications` field, data in the JSON structure is only intended for purposes of displaying the NFT in a user interface.
+
+
+### Files
+
+Current state of the JSON schema can be found in `dist/cic.json`. It is composed by the `build.py` script from `*.in.json`.
+
+`test_valid.json` is a single example data file used to test the JSON schema. `make test` builds the schema and runs the 
+
+
+
+### The attribute property
+
+The `attributes` property may contain one or more values that represents parameters within certifications. However, it does not represent the autoritative data.
+
+Care must be taken to make sure the display parameters does not conflict with the data defined in the certification itself.
diff --git a/test_valid.json b/test_valid.json
index a864fe0..9111065 100644
--- a/test_valid.json
+++ b/test_valid.json
@@ -4,6 +4,7 @@
 	"description": "bar",
 	"attributes": [
 		{
+			"display_type": "gauge",
 			"trait_type": "Rating",
 			"value": 2.2
 		},