search

regen-network / regen-registry-standards

:seedling: RDF and SHACL schemas for Regen Registry
4 stars 1 forks source link

Add JSONLD examples and SHACL schema for C01 credit classes, credit batches and projects #12

Closed wgwz closed 2 years ago

wgwz commented 2 years ago

Description

Closes: https://github.com/regen-network/regen-registry/issues/780

The most critical file to review is this one: shacl/credit-batches/credit-batch.ttl. I decided to create new shape definitions just for the sake of getting something that works. But I believe we might want to dedupe and move some of these new shape definitions to pre-existing shape definitions. I.e. I define a new ProjectShape in credit-batch.ttl even though there is already a ProjectShape defined in project-shape.ttl.

I confirmed that the example JSON-LD conforms with the new credit batch spec:

kyle@lookfar4:~/regen/regen-registry-standards$ pyshacl -s shacl/credit-batches/credit-batch.ttl jsonld/credit-batches/C01-verified-carbon-standard.json
Validation Report
Conforms: True

I think that I might move shacl/credit-batches/credit-batch.ttl into shacl/credit-batches/C01-verified-carbon-standard.ttl. I'm not really sure what the best name for this file is, I could use some feedback there as well.

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.

I have...

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.

I have...

wgwz commented 2 years ago

I just pushed a new commit that added an example JSON-LD based on the Mai Nadombe example. This newly add project graph data also validates with the shacl/credit-batches/credit-batch.ttl schema (since I defined a Project schema there)

Showing the validation result:

kyle@lookfar4:~/regen/regen-registry-standards$ pyshacl -s shacl/credit-batches/credit-batch.ttl jsonld/projects/C01-verified-carbon-standard.json
Validation Report
Conforms: True
blushi commented 2 years ago

I think that I might move shacl/credit-batches/credit-batch.ttl into shacl/credit-batches/C01-verified-carbon-standard.ttl. I'm not really sure what the best name for this file is, I could use some feedback there as well.

I think that would make sense since here we're defining constraints for credit batches that will belong to this particular credit class (C01-verified-carbon-standard)

wgwz commented 2 years ago

Hi @blushi I made those changes, thanks for the suggestions :-) I think I handled those changes correctly. I added some minCount and maxCount values to some of the other fields as well.

One thing I'd like to discuss is why this test data does not result in a SHACL validation error:

      "qudt:numericValue": {
        "@type": "xsd:double",
        "@value": "foo"
      }

The schema for this piece of the graph is this:

  sh:property [
    sh:path qudt:numericValue ;
    # TODO: This is not validating as expected (I think..)
    # See "qudt:numericValue" in
    # jsonld/credit-batches/C01-verified-carbon-standard.json
    sh:datatype xsd:double ;

I'm expecting an error because the test data is a string value, and not a double. Does the xsd:double datatype just not have any constraints? Do we need to add constraints?

wgwz commented 2 years ago

It seems like you're not using the same url for qudt namespace in the SHACL and the JSON-LD data, which gives you some unexpected behavior when running validation. Let's just start using http://qudt.org/schema/qudt everywhere which now seems the most up-to-date one and we don't need to worry about the version.

Ah, ok. I see. I've updated that and made that change in all the places it was used (it was only two instances).

SHACL only verifies that the @type is xsd:double, not the actual value. You could also represent a double using a string, e.g. "380.16". In addition, you could also add sh:minExclusive 0 ; to double check it's a positive number.

I see, ok, this is what I was getting confused by. The interesting thing is that it seems like some types do some light validation to the data when verifying with a SHACL schema. For example, the date type, when I ran the SHACL schema, it raised an issue if it wasn't actually a date.

I also removed all the fake data I had in sample JSON-LD's, it's all empty strings or 0's now.

blushi commented 2 years ago

I see, ok, this is what I was getting confused by. The interesting thing is that it seems like some types do some light validation to the data when verifying with a SHACL schema. For example, the date type, when I ran the SHACL schema, it raised an issue if it wasn't actually a date.

After some afterthought and some testing on that, if you just have a string like "foo" for some xsd:double, the validation should actually fail.

I believe your issue was rather that the validation wasn't run because you were using the type name as sh:node instead of the shape name.

wgwz commented 2 years ago

After some afterthought and some testing on that, if you just have a string like "foo" for some xsd:double, the validation should actually fail.

I believe your issue was rather that the validation wasn't run because you were using the type name as sh:node instead of the shape name.

So I took a look at this, and I tried testing the change to "foo" for xsd:double value. With just that change, I was still not getting any validation error. However with the patch below, I was able to get it to raise a validation error. Should I commit these and push them?

TL;DR I replaced qudt:numericValue with xsd:double in both the SizeShape definition and in the example JSON-LD.

diff --git a/jsonld/credit-batches/C01-verified-carbon-standard.json b/jsonld/credit-batches/C01-verified-carbon-standard.json
index 61f5499..2fde0c6 100644
--- a/jsonld/credit-batches/C01-verified-carbon-standard.json
+++ b/jsonld/credit-batches/C01-verified-carbon-standard.json
@@ -57,7 +57,7 @@
         "@type": "qudt:Unit",
         "@value": "unit:HA"
       },
-      "qudt:numericValue": {
+      "xsd:double": {
         "@type": "xsd:double",
         "@value": ""
       }
diff --git a/shacl/credit-batches/C01-verified-carbon-standard.ttl b/shacl/credit-batches/C01-verified-carbon-standard.ttl
index d4ec67f..fb6ee5a 100644
--- a/shacl/credit-batches/C01-verified-carbon-standard.ttl
+++ b/shacl/credit-batches/C01-verified-carbon-standard.ttl
@@ -138,7 +138,7 @@ regen:SizeShape a sh:NodeShape ;
     sh:datatype qudt:Unit ;
   ] ;
   sh:property [
-    sh:path qudt:numericValue ;
+    sh:path xsd:double ;
     sh:minExclusive 0 ;
     sh:datatype xsd:double ;
   ] ;

Here's the validation error for when it's a negative value:

Constraint Violation in MinExclusiveConstraintComponent (http://www.w3.org/ns/shacl#MinExclusiveConstraintComponent):
        Severity: sh:Violation
        Source Shape: [ sh:datatype xsd:double ; sh:minExclusive Literal("0", datatype=xsd:integer) ; sh:path xsd:double ]
        Focus Node: [ <qudt:unit> Literal("unit:HA" = None, datatype=<qudt:Unit>) ; rdf:type regen:Size ; xsd:double Literal("-12.0", datatype=xsd:double)
 ]
        Value Node: Literal("-12.0", datatype=xsd:double)
        Result Path: xsd:double
        Message: Value is not > Literal("0", datatype=xsd:integer)

And here's the validation error for "foo":

Constraint Violation in MinExclusiveConstraintComponent (http://www.w3.org/ns/shacl#MinExclusiveConstraintComponent):
        Severity: sh:Violation
        Source Shape: [ sh:datatype xsd:double ; sh:minExclusive Literal("0", datatype=xsd:integer) ; sh:path xsd:double ]
        Focus Node: [ <qudt:unit> Literal("unit:HA" = None, datatype=<qudt:Unit>) ; rdf:type regen:Size ; xsd:double Literal("foo" = None, datatype=xsd:double) ]
        Value Node: Literal("foo" = None, datatype=xsd:double)
        Result Path: xsd:double
        Message: Value is not > Literal("0", datatype=xsd:integer)
blushi commented 2 years ago

TL;DR I replaced qudt:numericValue with xsd:double in both the SizeShape definition and in the example JSON-LD.

The path value shouldn't have any impact on the validation. I have tried using just qudt:numericValue as path and I get the same validation errors.

wgwz commented 2 years ago

I mostly reviewed for the JSON-LD content and made a few minor suggestions to omit value content (ie description, organization, scope, and offset method values) in the JSONLD files and instead leave all fields as null/empty.

After some discussion with @clevinson I think we want to use the regen-registry-standards repo to hold templates and standards for graphs and validations, but not the actual content for credit classes, batches, projects, etc... Instead we will start a new new repository, regen-registry-ops, where we can keep all the implemented credit classes, projects, and credit batches json-ld files, as well as many of the scripts in our multisig ops, credit class issuances, etc...

@S4mmyb @blushi One point I wanted raise here is that it would be helpful to have testing data (JSONLD with non-empty values) for this repo. I think that when you start using SHACL schema for validation, it's important to have a simple way to test that the validations are working correctly. I have some ideas for how we could potentially set up a CI for this repo to run tests. I'm uncertain of what will be in regen-registry-ops and how or if we could use it for these purposes.

wgwz commented 2 years ago

it'd be nice to update the credit batch shacl schema and create new ones based on the project and credit class metadata jsonld templates

@blushi I've setup two SHACL schema for project and credit class (C01):

The project schema was pulled out of the batch schema we set up previously, and I only made a small adjustment.

I think the most import to review at this point are C01-verified-carbon-standard-class.ttl and the corresponing C01-verified-carbon-standard-class.json. I'm not 100% sure how we should structure the JSON-LD, specifically the things that lists, and depending on that, maybe we need some updates to it's SHACL.

wgwz commented 2 years ago

Note-to-self: Fix tab issue in shacl files.