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

.gitignore

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

Makefile

@@ -1,8 +1,21 @@
-all: build
+all: json rdf python
 
-build:
-	python bundle.py > cic.json
+.PHONY: json rdf python
 
 
-test: build
-	check-jsonschema --schemafile dist/cic.json test_valid.json
+json:
+	make -C schema/json
+
+rdf:
+	make -C schema/rdf
+
+python:
+	make -C 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 from `requirements.txt`:
 
-To build json schemas and run tests, please install the python dependencies in `requirements.txt`:
-
-`pip install -r 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.
+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.

dist/cic.json

@@ -1 +0,0 @@
-{"$schema": "https://json-schema.org/draft/2020-12/schema", "title": "CIC core metadata container", "$id": "/cic/core", "type": "object", "properties": {"version": {"type": "integer"}, "attachments": {"type": "array", "items": {"$ref": "/mime"}}, "certifications": {"type": "array", "items": {"type": "string", "format": "uri"}, "minItems": 1}, "image_data": {"type": "string", "description": "Raw SVG image data, if you want to generate images on the fly (not recommended). Only use this if you're not including the image parameter.", "contentEncoding": "base64", "contentMediaType": "image/svg+xml"}, "image": {"type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive.", "format": "uri"}, "external_url": {"type": "string", "description": "This is the URL that will appear below the asset's image on OpenSea and will allow users to leave OpenSea and view the item on your site.", "format": "uri"}, "attributes": {"type": "array", "description": "These are the attributes for the item, which will show up on the OpenSea page for the item. (see below)", "items": {"type": "object", "properties": {"trait_type": {"type": "string"}, "value": {"oneOf": [{"type": "string"}, {"type": "number"}]}, "display_type": {"type": "string"}}, "required": ["trait_type", "value"]}}, "animation_url": {"type": "string", "description": "Animation_url also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are now supported. However, access to browser extensions is not supported.", "format": "uri"}, "name": {"type": "string", "description": "Identifies the asset to which this NFT represents"}, "description": {"type": "string", "description": "Describes the asset to which this NFT represents"}}, "required": ["version", "attachments", "attributes"], "mime": {"$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "/mime", "title": "A single generic attachment for documenting any asset", "type": "object", "properties": {"contentType": {"type": "string", "$comment": "valid mime type"}, "contentTransferEncoding": {"type": "string", "enum": ["BASE64", "QUOTED-PRINTABLE", "8BIT", "7BIT"]}, "subject": {"type": "string", "$comment": "utf-8"}, "body": {"type": "string", "$comment": "uri including dataurl"}, "ref": {"type": "string", "format": "uri"}}, "required": ["contentType", "subject"], "oneOf": [{"required": ["body"]}, {"required": ["ref"]}]}, "oneOf": [{"required": ["image"]}, {"required": ["image_data"]}]}

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

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

python/cic_schema/__init__.py

@@ -0,0 +1 @@
+from .cert import Attestation

python/cic_schema/cert.py

@@ -0,0 +1,44 @@
+# standard imports
+import sys
+import enum
+
+# external imports
+from rdflib import Graph, RDF
+from rdflib.term import URIRef
+from rdflib.collection import Collection
+
+
+class CIC(enum.Enum):
+    voucherContract = URIRef('https://defalsify.org/rdf-eth/0.1/voucherContract')
+    voucherTransfer = URIRef('https://defalsify.org/rdf-eth/0.1/voucherTransfer')
+
+
+class Attestation:
+
+    def __init__(self):
+        self.g = Graph()
+        self.txs = {}
+        self.typ = None
+
+
+    @classmethod
+    def from_path(cls, path):
+        c = cls()
+        c.g.parse(path, format='turtle')
+        c.__apply_graph()
+        return c
+
+
+    def __apply_graph(self):
+        current_subject = None
+        for (s, p, o) in self.g:
+            if s != current_subject: 
+                current_subject = s
+            if p == RDF.first:
+                pass
+            print('{} {} {}'.format(s, p, o))
+                
+
+    def export(self, w=sys.stdout):
+        v = self.g.serialize(format='xml')
+        w.write(v)

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/requirements.txt

@@ -0,0 +1,4 @@
+check-jsonschema==0.21.0
+rdflib==6.2.0
+jsonschema==4.17.3
+

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/test_requirements.txt

@@ -0,0 +1 @@
+hypothesis==6.68.2

python/tests/test_json.py

@@ -0,0 +1,28 @@
+# standard imports
+import unittest
+import json
+import os
+
+# external imports
+#from jsonschema import validate as json_validate
+# local imports
+from cic_schema.nft import NFT
+
+test_dir = os.path.realpath(os.path.dirname(__file__))
+testdata_dir = os.path.join(test_dir, 'testdata')
+#data_dir = os.path.join(test_dir, '..', 'cic_schema', 'data')
+
+
+class TestJsonData(unittest.TestCase):
+
+    def setUp(self):
+        self.path = os.path.join(testdata_dir, 'test_valid.json')
+        self.nft = NFT.from_path(self.path)
+
+
+    def test_valid(self):
+        pass
+
+
+if __name__ == '__main__':
+    unittest.main()

python/tests/test_nft.py

@@ -0,0 +1,34 @@
+# standard imports
+import unittest
+import json
+import os
+
+# external imports
+from jsonschema import validate as json_validate
+from rdflib import Graph
+#from hypothesis import given, strategies
+
+# local imports
+from cic_schema import Attestation
+
+test_dir = os.path.realpath(os.path.dirname(__file__))
+testdata_dir = os.path.join(test_dir, 'testdata')
+data_dir = os.path.join(test_dir, '..', 'cic_schema', 'data')
+
+
+class TestNft(unittest.TestCase):
+
+    def setUp(self):
+        #fp = os.path.join(testdata_dir, 'test_voucher.rdf')
+        #self.graph_voucher = Attestation.from_path(fp)
+        fp = os.path.join(testdata_dir, 'test_tx2.rdf')
+        self.graph_tx = Attestation.from_path(fp)
+
+
+    def test_simplest(self):
+        pass
+
+
+
+if __name__ == '__main__':
+    unittest.main()

python/tests/testdata/test_tx.rdf

@@ -1,12 +1,15 @@
-@prefix evm: <https://defalsify.org/rdf-eth/0.1/#> .
+@prefix evm: <https://defalsify.org/rdf-eth/0.1/> .
 @prefix cic: <https://cicnet.org/rdf/0.1/> .
 @prefix ge: <https://grassrootseconomics.net/rdf/0.1/ge#> .
 @prefix redcross: <https://redcross.com/cic-def/0.1/> .
-@prefix un: <https://un.com/esg/0.1/> .
+@prefix un: <https://un.com/cic/0.1/> .
 @prefix xsd:	<http://www.w3.org/2001/XMLSchema#> .
 
-evm:voucherTransfer
-	evm:id	"0x6f4ed36c11345a9a48353cd2f93f1f92958c96df15f3112a192bc994250e8d03"^^xsd:hexBinary ;
+(
+	"6f4ed36c11345a9a48353cd2f93f1f92958c96df15f3112a192bc994250e8d03"^^evm:id
+	"7f4ed36c11345a9a48353cd2f93f1f92958c96df15f3112a192bc994250e8d03"^^evm:id
+	"8f4ed36c11345a9a48353cd2f93f1f92958c96df15f3112a192bc994250e8d03"^^evm:id
+)
 	ge:approvedActor	<URN:uuid:18daebc7-23b9-41e4-af00-2559f7840f78> ;
 	redcross:interest	ge:foodforest ;
 	un:esg	"deforestation" ;

python/tests/testdata/test_voucher.rdf

@@ -5,7 +5,7 @@
 @prefix xsd:	<http://www.w3.org/2001/XMLSchema#> .
 
 evm:voucherContract
-	evm:id	"0x1f92958c96df15f3112a192bc994250e8defef93f"^^xsd:hexBinary ; 
+	evm:id	"01f92958c96df15f3112a192bc994250e8defef93f"^^xsd:hexBinary ;
 	cic:unitOfAccount	cic:ref:wampum ;
 	cic:validFrom	"2023-03-05T19:04:40+00:00"^^xsd:dateTime ; 
 	cic:validUntil	"2024-03-05T19:04:40+00:00"^^xsd:dateTime ;
@@ -17,8 +17,8 @@ evm:voucherContract
 	ge:community	"Foo tribe" .
 
 evm:voucherContract
-	evm:id	"0x58c96df15f3112a192bc994250e8defef93f12345"^^xsd:hexBinary ;
+	evm:id	"058c96df15f3112a192bc994250e8defef93f12345"^^xsd:hexBinary ;
 	cic:unitOfAccount	"seashells" ;
 	cic:validFrom	"2023-03-04T09:34:33+00:00"^^xsd:dateTime ;
-	foaf:name	"Busy Bee" 
+	foaf:name	"Busy Bee" ;
 	ge:approvedActor	<URN:uuid:18daebc7-23b9-41e4-af00-2559f7840f78> .

requirements.txt

@@ -1 +0,0 @@
-check-jsonschema==0.21.0

schema/json/Makefile

@@ -0,0 +1,12 @@
+all: build
+
+build:
+	python bundle.py
+
+
+test: build
+	check-jsonschema --schemafile dist/cic.json test_valid.json
+
+
+install: build
+	cp -v dist/cic.json ../../python/cic_schema/data/

schema/rdf/Makefile

@@ -0,0 +1,5 @@
+all: install
+
+install:
+	cp -v evm.rdfs ../../python/cic_schema/data/	
+

schema/rdf/evm.rdfs

@@ -0,0 +1,14 @@
+@base <https://defalsify.org/rdf-eth/0.1/evm.rdfs> .
+@prefix xsd:	<http://www.w3.org/2001/XMLSchema#> .
+@prefix	rdfs:	<https://www.w3.org/TR/rdf-schema/#> .
+
+<#location>	a	rdfs:Class .
+<#tx>	a	rdfs:Class .
+<#account>	rdfs:subClassOf	<#location> .
+<#contract>	rdfs:subClassOf	<#location> .
+<#voucherContract>	rdfs:subClassOf	<#contract> .
+<#nftContract>	rdfs:subClassOf	<#contract> .
+<#gasTransfer>	rdfs:subClassOf	<#tx> .
+<#voucherTransfer>	rdfs:subClassOf	<#tx> .
+<#nftTransfer>	rdfs:subClassOf	<#tx> .
+<#id>	rdfs:Datatype	xsd:hexBinary .