Move documentation to texinfo, add makefiles, rename Cert to Attestation (python)

.gitignore

@@ -1 +1,5 @@
 cic.json
+build/
+*.egg-info
+*.pyc
+__pycache__

Makefile

@@ -15,3 +15,7 @@ python:
 install: python
 	make -C schema/json install
 	make -C schema/rdf install
+
+readme:
+	make -C doc/texinfo readme
+	pandoc -f docbook -t gfm doc/texinfo/build/docbook.xml > README.md

README.md

@@ -1,77 +1,87 @@
-# CIC schemas
+# 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).
+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_.
+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._
+**This is a work in process. It is in alpha state, and may radically
+change at any time.**
 
+## Getting started
 
-## Using the project
-
-To build json schemas and run tests, please install the python dependencies in `requirements.txt`:
+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)
 
-
-## Structure
+## Project Structure
 
 Each unit of metadata consists of two parts:
 
-1. RDF documents the certifications of vouchers, accounts and transactions.
+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
 
-## Certification vocaularies
+## Attestation 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.
+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 certifications may express impacts and externalities in vocuabularies managed by themselves or other interested parties.
+Authors of attestations 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.
+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.
+`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
 
-### Files
+The JSON metadata implements the ERC721 standard, as well as parts of
+the Opensea metadata standard.
 
-Example certification files used for initial development are (`test_tx.rdf` and `test_voucher.rdf`).
+It also contains immutable references to one or more certifications
+which the NFT represents.
 
-Note these schemas are not yet defined. They only exist as fictious references in the example files. 
+Apart from the `certifications` field, data in the JSON structure is
+only intended for purposes of displaying the NFT in a user interface.
 
+## Files
 
-## EVM NFT
+Current state of the JSON schema can be found in `dist/cic.json`. It is
+composed by the `build.py` script from `*.in.json`.
 
-The JSON metadata implements the **ERC721** standard, as well as parts of the **Opensea** metadata standard.
+`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.
 
-It also contains immutable references to one or more certifications which the NFT represents.
+## The attribute property
 
-Apart from the `certifications` field, data in the JSON structure is only intended for purposes of displaying the NFT in a user interface.
+The `attributes` property may contain one or more values that represents
+parameters within certifications. However, it does not represent the
+autoritative data.
 
-
-### 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.
+Care must be taken to make sure the display parameters does not conflict
+with the data defined in the certification itself.

doc/texinfo/Makefile

@@ -0,0 +1,4 @@
+doc:
+	makeinfo --html -o build index.texi
+readme:
+	makeinfo --docbook -o build/docbook.xml index.texi

doc/texinfo/attestations.texi

@@ -0,0 +1,20 @@
+@node attestations
+@chapter Attestations
+
+@section Attestation vocaularies
+
+Four base vocabularies are used to define the attestations.
+
+* @code{@url{foaf, http://xmlns.com/foaf/0.1/}} - well-known library used to describe human resources and relationships.
+* @code{evm} - EVM specific resources like transactions and account addresses.
+* @code{cic} - concepts specific to CICs, e.g. @emph{Unit of Account}, @emph{voucher validity} and other parameters decribing kinds of economic activity.
+* @code{ge} - subject impact types, areas of interest and inter-currency relations according to Grassroots Economics - the organization pioneering this work.
+
+
+@subsection 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 @strong{We Do Good NGO} as intended recipient. When doing so, elements from the @code{wedogood} vocabulary is used to reference specific points of interest in terms recognized by the systems of the recipient.
+
+@code{wedogood} can furthermore be a vocabulary that systems of the fictious @strong{We Do More Good NGO} trusts and recognizes, which in turn can improve reliability and confidence for them.

doc/texinfo/index.texi

@@ -0,0 +1,28 @@
+\input texinfo
+@settitle CIC Schema
+
+@copying
+Documentation released 2023 under Creative Commons Attribution-Sharealike 4.0 (CC BY-SA 4.0)
+@end copying
+
+@titlepage
+@title CIC Schema
+@author Louis Holbrook
+
+@end titlepage
+
+@c
+@contents
+
+@ifnottex
+@node Top
+@top Introduction
+@end ifnottex
+@menu
+* overview ::
+* instructions :
+@end menu
+
+@include overview.texi
+@include attestations.texi
+@include nft.texi

doc/texinfo/location.texi

@@ -0,0 +1,9 @@
+In the context of CIC, The URI of NFT contract metadata will always be expressed in terms of a content-addressed string.
+
+The string may point to a specific location in the web, or may point to the content address itself, for which the location must be determined by the caller.
+
+The difference between the three methods can be illustrated by two examples:
+
+@itemize
+@item
+tokenURI(foo) -> 

doc/texinfo/nft.texi

@@ -0,0 +1,22 @@
+@node nft
+@chapter EVM NFT
+
+The JSON metadata implements the @dfn{ERC721} standard, as well as parts of the @dfn{Opensea} metadata standard.
+
+It also contains immutable references to one or more certifications which the NFT represents.
+
+Apart from the @code{certifications} field, data in the JSON structure is only intended for purposes of displaying the NFT in a user interface.
+
+
+@section Files
+
+Current state of the JSON schema can be found in @file{dist/cic.json}. It is composed by the @file{build.py} script from @file{*.in.json}.
+
+@file{test_valid.json} is a single example data file used to test the JSON schema. @code{make test} builds the schema and runs the corresponding tests.
+
+
+@section The attribute property
+
+The @code{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.

doc/texinfo/overview.texi

@@ -0,0 +1,29 @@
+@node overview
+@chapter 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 @emph{attestations}.
+
+@strong{This is a work in process. It is in alpha state, and may radically change at any time.}
+
+
+@section Getting started
+
+To build json schemas and run tests, please install the python dependencies from @file{requirements.txt}:
+
+@code{pip install -r requirements.txt}
+
+(You may want to use a virtual environment)
+
+
+@section Project Structure
+
+Each unit of metadata consists of two parts:
+
+@enumerate
+@item RDF documents the certifications of vouchers, accounts and transactions.
+@item A JSON metadata structure bundlinf certficiations as tradeable NFTs.
+@end enumerate
+
+NFT tooling is at the current time intended for EVM blockchains only.

python/Makefile

@@ -1,3 +1,6 @@
 .PHONY: all
 
 all:
+	python setup.py sdist
+test:
+	bash run_tests.sh

python/cic_schema/__init__.py

@@ -1 +1 @@
-from .cert import Cert
+from .cert import Attestation

python/cic_schema/cert.py

@@ -13,7 +13,7 @@ class CIC(enum.Enum):
     voucherTransfer = URIRef('https://defalsify.org/rdf-eth/0.1/voucherTransfer')
 
 
-class Cert:
+class Attestation:
 
     def __init__(self):
         self.g = Graph()

python/cic_schema/error.py

@@ -0,0 +1,2 @@
+class InvalidCertificationError(Exception):
+    pass

python/cic_schema/nft.py

@@ -0,0 +1,64 @@
+# standard imports
+import os
+import json
+from urllib.request import urlopen
+#import binascii.error
+
+# external imports
+from jsonschema import validate as json_validate
+
+# local imports
+from .error import InvalidCertificationError
+
+
+script_dir = os.path.realpath(os.path.dirname(__file__))
+data_dir = os.path.join(script_dir, 'data')
+__f = open(os.path.join(data_dir, 'cic.json'), 'r')
+schema = __f.read()
+__f.close()
+
+
+class NFT:
+
+    def __init__(self):
+        self.name = None
+        self.description = None
+        self.image = None
+        self.attachments = []
+        self.attributes = {}
+        self.certifications = []
+
+
+    @classmethod
+    def from_path(cls, path):
+        f = open(path, 'r')
+        o = json.load(f)
+        f.close()
+        json_validate(schema, o)
+        c = cls()
+        c.name = o['name']
+        c.description = o['description']
+        c.image = o['image']
+        c.attributes = o['attributes']
+        c.attachments = o['attachments']
+        c.certifications = o['certifications']
+
+
+    def __decode_certification(self):
+        for v in self.certiciations:
+            try:
+                r = self.__try_data_uri(v)
+            except:
+                pass
+
+
+    def __try_data_uri(self, data):
+        r = None
+        try:
+            r = urllib.request.urlopen(data) 
+        #except binascii.error:
+        #    raise InvalidCertificationError()
+        except Exception:
+            raise InvalidCertificationError()
+            #return None
+        return r

python/run_tests.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+set -a
+set -e
+set -x
+default_pythonpath=$PYTHONPATH:.
+export PYTHONPATH=${default_pythonpath:-.}
+>&2 echo using pythonpath $PYTHONPATH
+for f in `ls tests/*.py`; do
+	python $f
+done
+set +x
+set +e
+set +a

python/tests/test_nft.py

@@ -9,7 +9,7 @@ from rdflib import Graph
 #from hypothesis import given, strategies
 
 # local imports
-from cic_schema import Cert
+from cic_schema import Attestation
 
 test_dir = os.path.realpath(os.path.dirname(__file__))
 testdata_dir = os.path.join(test_dir, 'testdata')
@@ -20,9 +20,9 @@ class TestNft(unittest.TestCase):
 
     def setUp(self):
         #fp = os.path.join(testdata_dir, 'test_voucher.rdf')
-        #self.graph_voucher = Cert.from_path(fp)
+        #self.graph_voucher = Attestation.from_path(fp)
         fp = os.path.join(testdata_dir, 'test_tx2.rdf')
-        self.graph_tx = Cert.from_path(fp)
+        self.graph_tx = Attestation.from_path(fp)
 
 
     def test_simplest(self):