feat: Claim and Attestation schemas for claims engine interop#53
feat: Claim and Attestation schemas for claims engine interop#53glandua wants to merge 1 commit intoregen-network:mainfrom
Conversation
Introduces the semantic foundation for the KOI claims engine and CLAMS CosmWasm contract to share a governed vocabulary via regen-data-standards. New schemas: - Claim.yaml: verifiable claims with typed impact, temporal bounds, entity references, quantity, methodology, and chain bridge fields - Attestation.yaml: reviewer attestations with verdict, rationale, evidence, and on-chain anchoring fields Extended schemas: - taxonomy.yaml: ClaimType, VerificationStatus, VerdictType enums - Entity.yaml: walletAddress attribute, COMMUNITY entity type - schema.yaml: Claim and Attestation imports Designed for: - KOI off-chain claims engine (@context + JSON-LD) - CLAMS on-chain contract (content hash + data IRI bridge) - EAS Ethereum attestations (wallet address identity bridge) - PACTO biocultural claims (BIOCULTURAL claim type, COMMUNITY entity) Closes regen-network#52 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request establishes the foundational semantic schemas for claims and attestations, crucial for enabling interoperability between off-chain (KOI) and on-chain (CLAMS) claims engines. By defining structured data models for claims and their reviews, it provides a robust framework for tracking regenerative outcomes, facilitating verification pathways, and bridging semantic data to on-chain anchors. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces Claim and Attestation LinkML schemas, which is a significant step for interoperability. The schemas are well-structured and documented. I've provided a few suggestions to enhance data integrity and consistency. Specifically, I recommend making temporal bounds (claimStartDate, claimEndDate, attestationDate) required fields, as they are fundamental to claims and attestations. I also suggest a refactoring for quantity and quantityUnit to ensure they are always specified together, and adding explicit slot_uris for consistency. Overall, these are solid additions to the schema.
| claimStartDate: | ||
| slot_uri: schema:startDate | ||
| description: The start date of the period covered by this claim. | ||
| range: date |
There was a problem hiding this comment.
A claim should have a defined temporal bound. The PR description highlights 'Temporal bounds as explicit date attributes', underscoring their importance. To ensure all claims specify the period they cover, consider making claimStartDate a required field.
range: date
required: true| claimEndDate: | ||
| slot_uri: schema:endDate | ||
| description: The end date of the period covered by this claim. | ||
| range: date |
There was a problem hiding this comment.
A claim should have a defined temporal bound. The PR description highlights 'Temporal bounds as explicit date attributes', underscoring their importance. To ensure all claims specify the period they cover, consider making claimEndDate a required field.
range: date
required: true| attestationDate: | ||
| slot_uri: rfs:attestationDate | ||
| description: Date when the attestation was made. | ||
| range: date |
There was a problem hiding this comment.
The attestationDate is a crucial piece of information for an attestation, but it's currently optional. To ensure data integrity and completeness, consider making it a required field.
range: date
required: true| required: true | ||
| inlined: true | ||
| hasCoBenefits: | ||
| description: Secondary impacts or co-benefits associated with the claim. |
There was a problem hiding this comment.
For consistency with other attributes in this schema that explicitly define a slot_uri, consider adding one here. Based on the attribute name, slot_uri: rfs:hasCoBenefits would be appropriate.
slot_uri: rfs:hasCoBenefits
description: Secondary impacts or co-benefits associated with the claim.| quantity: | ||
| slot_uri: rfs:quantity | ||
| description: >- | ||
| Numeric quantity associated with the claim (e.g., tonnes CO2e, | ||
| hectares restored). | ||
| range: float | ||
| quantityUnit: | ||
| slot_uri: qudt:unit | ||
| description: >- | ||
| Unit of measurement for the quantity (e.g., unit:TON, unit:HA). | ||
| range: string |
There was a problem hiding this comment.
The quantity and quantityUnit attributes are defined separately, which could allow for a quantity to be specified without a quantityUnit, leading to ambiguity. To improve data integrity, consider grouping these into a single structure.
For example, you could define a new Quantity class:
# In a shared file like core.yaml or a new Quantity.yaml
classes:
Quantity:
attributes:
value:
range: float
required: true
description: "The numeric value of the quantity."
unit:
range: string
required: true
description: "The unit of measurement."
slot_uri: qudt:unitAnd then use it in Claim.yaml by replacing the current quantity and quantityUnit attributes with:
# In Claim.yaml
quantity:
range: Quantity
inlined: true
description: >-
Numeric quantity associated with the claim (e.g., tonnes CO2e,
hectares restored).| Unit of measurement for the quantity (e.g., unit:TON, unit:HA). | ||
| range: string | ||
| usesMethodology: | ||
| description: The methodology used to measure or verify the claimed outcome. |
There was a problem hiding this comment.
For consistency with other attributes in this schema that explicitly define a slot_uri, consider adding one here. Based on the attribute name, slot_uri: rfs:usesMethodology would be appropriate.
slot_uri: rfs:usesMethodology
description: The methodology used to measure or verify the claimed outcome.![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59d9e683ee
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| IRI or RID of a previous claim that this claim supersedes, | ||
| forming a version chain. | ||
| range: uri |
There was a problem hiding this comment.
supersedes
supersedes is described as accepting “IRI or RID”, but the declared range is uri, which excludes non-URI RID formats. In claim versioning flows that store prior claims by RID (instead of full IRIs), this field will fail schema validation despite being documented as valid input, blocking interoperability for update chains. Use a range that can represent both forms (for example string or uriorcurie) or tighten the description to URI-only.
Useful? React with 👍 / 👎.
|
Hey Greg — just implemented the two KOI Processor issues that don't depend on this PR:
One alignment point on #11 (schema integration — |
2 participants
Summary
Adds Claim and Attestation LinkML schemas as the semantic backbone for KOI (off-chain) and CLAMS (on-chain) claims engine interoperability, per ADR-004.
Claim.yaml— verifiable claims with typed impact, temporal bounds, entity references (claimant/subject/operator), quantity + unit, methodology, credit class link, and chain bridge fields (contentHash, dataIri)Attestation.yaml— reviewer attestations with verdict, rationale, evidence URIs, and on-chain anchoring (contentHash, graphIri for MsgAttest)taxonomy.yaml: ClaimType (ECOLOGICAL, SOCIAL, FINANCIAL, GOVERNANCE, BIOCULTURAL), VerificationStatus (SELF_REPORTED → LEDGER_ANCHORED), VerdictType (PENDING, APPROVED, REJECTED, NEEDS_INFO)Entity.yamlextensions:walletAddressattribute (identity bridge for CLAMS/EAS),COMMUNITYentity type (PACTO collective entities)schema.yaml: Claim and Attestation added to importsDesign decisions
range: Entity, inlined: trueeligibleActivities → ActivityTypepatternfloat+ unitstringcontentHash+dataIrion both Claim and AttestationhasCreditClassas string (not inlined CreditClassInfo)tx_hash,ledger_timestampVerification
linkml-lintpasses (warnings only — all pre-existing camelCase convention warnings)gen-json-schemagenerates valid JSON Schema with all new typesgen-jsonld-contextgenerates JSON-LD context with Claim/Attestation resolvableMerge conflict note
PR #51 (
feat/governance-schema-extensions) touches Entity.yaml (addsAGENTto EntityTypes), taxonomy.yaml (adds governance enums), and schema.yaml (adds governance imports). Our changes are additive to different sections — trivially resolvable after #51 merges.Downstream consumers
@context+ taxonomy validationCloses #52
Test plan
linkml-lintpasses on full schema (no new errors)gen-json-schemagenerates valid output including Claim and Attestationgen-jsonld-contextgenerates context with new typesmakeinschema/completes without errors (after feat: Governance schema extensions for agentic framework #51 merges)🤖 Generated with Claude Code