cic-schema/README.md

# Overview

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 *attestations*.

**This is a work in process. It is in alpha state, and may radically
change at any time.**

## Getting started

To build json schemas and run tests, please install the python
dependencies from `requirements.txt`:

`pip install -r requirements.txt`

(You may want to use a virtual environment)

## Project 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.

# Attestations

## Attestation vocaularies

Four base vocabularies are used to define the attestations.

- `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, areas of interest and inter-currency
  relations according to Grassroots Economics - the organization
  pioneering this work.

### Including other vocabularies

Authors of attestations may express impacts and externalities in
vocuabularies managed by themselves or other interested parties.

For example, Grassroots Economics can author a attestation 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 systems of the recipient.

`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.

# 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 corresponding tests.

## 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.