Open consequence graph for source-backed administrative workflows

Status: CI passing · OpenSSF Best Practices: passing · OpenSSF Scorecard · REUSE compliant · Codecov · SonarCloud · Code: EUPL-1.2 · Data: CC-BY-4.0 · DOI: 10.5281/zenodo.20572455 · FAIR: 4/5

Clarvia Graph is reusable public-interest digital infrastructure. While it serves as the technical engine behind the consumer-facing checklist at clarvia.org, it is designed as an open, source-backed administrative workflow repository. It structures official rules, deadlines, and requirements for bereavement paperwork so that any application, civic-tech portal, research project, or public service can consume and adapt them automatically.

Clarvia Graph is being prepared for submission to the Digital Public Goods Alliance Registry as open, source-backed administrative workflow infrastructure for bereavement administration. See DPG.md for the DPG Standard mapping, open-license information, privacy and do-no-harm boundaries, SDG alignment, and reuse documentation.

📸 Alpha checklist preview

The living demo at clarvia.org/en/checklist consumes a static JSON export generated from this graph. See exports/example-bereavement-lu.json for the exact shape.

Technically, Clarvia Graph is a structured, versioned, source-backed knowledge graph for cross-border administrative consequences. It models what happens after a life event (starting with bereavement), what steps may be required, which authorities are involved, what documents are needed, and where the official source says so.

This repository contains:

• Schemas — JSON Schema definitions for all canonical record types
• Vocabularies — Controlled vocabularies for jurisdictions, domains, claim types, etc.
• Graph data — Source-backed consequences, task templates, conditions, and deadlines
• Sources — Official source registry, captured snapshots, and extracted assertions
• Validation — CLI tooling to validate, build, and test the graph
• Exports — Generated JSON for web consumers (example), plus JSON-LD, CPSV-AP, and web runtime bundles

clarvia-graph/
├── schemas/          # JSON Schema definitions (v0.1)
├── vocab/            # Controlled vocabularies
├── graph/            # Consequence graph data (YAML)
│   ├── authorities/
│   ├── conditions/
│   ├── consequences/
│   ├── task_templates/
│   └── …
├── sources/          # Source registry, snapshots, and assertions
├── translations/     # Locale overlay files
├── tests/            # Scenario tests and unit tests
├── exports/          # Generated output (JSON, JSON-LD, web bundles)
├── packages/         # Workspace packages
│   ├── cli/          #   @clarvia/cli — validation, build, and export tooling
│   └── generator/    #   @clarvia/generator — checklist generation engine
├── docs/             # Foundation specification and guides
└── build/            # Build output (git-ignored)

The root package.json is a pnpm workspace that orchestrates the packages above. Run pnpm install from the root to set up all dependencies.

🔒 Foundation specification locked — The foundation spec defines the complete data architecture, standards alignment, editorial governance, and extensibility model.

🚧 Early implementation in progress — Proof-of-concept, alpha, and beta work is proceeding with internal resources to validate the foundation before funded hardening, validation, and scale-up phases.

Clarvia Graph is being developed as the technical foundation for source-backed bereavement checklists and related administrative workflows across Europe.

The project is moving through rapid proof-of-concept, alpha, and beta phases. Early versions are built with internal resources so that the data model, graph structure, validation approach, and export pipeline can be tested before larger funding cycles conclude.

This early implementation work is not intended to replace funded development. It is intended to de-risk the technical foundation and demonstrate that the architecture can move from specification to working infrastructure.

Future funded phases will focus on raising the foundation to production quality: schema refinement, validation tooling, source provenance, test coverage, interoperability, documentation, governance, security hardening, maintainability, and support for multiple jurisdictions.

The intended path is to build quickly, learn from real implementation, and then use funded phases to validate, harden, document, and scale the graph responsibly.

flowchart LR
    Source --> Snapshot --> Assertion --> Consequence --> Task["Task template"] --> Item["Checklist item"]

Every checklist item traces back to an official source. No legal consequence publishes without an approved source assertion.

• Source-backed: Every published claim traces to a captured official source
• Three-valued logic: Conditions evaluate to true, false, or unknown — never hides uncertainty
• Cross-border: Jurisdiction roles (death_place, habitual_residence, work_state, asset_situs) compose layered checklists
• Static exports: Consumer apps load generated JSON at build time — no runtime API dependency
• Privacy-first: Client-side condition evaluation, no user data sent to servers

This repository uses automated quality checks for tests, linting, static analysis, dependency and security scanning, documented installation, reproducible examples, citation metadata, licensing information, and archived releases. These checks run in CI on every pull request and release.

Clarvia maintains internal Clarvia-native schemas and generates compatibility views for:

• CPSV-AP — Core Public Service Vocabulary Application Profile
• CCCEV — Core Criterion and Core Evidence Vocabulary
• ELI — European Legislation Identifier
• PROV-O — W3C Provenance Ontology

Planned for next release: integrate prov Python library for PROV-O exports.

Planned: use SEMICeu/CPSV-AP and SEMICeu/CCCEV official SHACL shapes as validation targets for CPSV-AP and CCCEV exports.

v0.1 technical validation scope: Bereavement workflows, Luxembourg proof dataset, and minimal cross-border fixtures for France/Germany/EU concepts where needed to test jurisdiction composition.

Designed for extension to: Additional jurisdictions (Belgium, Netherlands, ...) and life events (birth, relocation, ...) without schema changes.

Clarvia Graph is an open, source-backed knowledge graph for administrative consequences — designed so that others can study the architecture, adapt the schemas, and fork for their own regulatory domains.

The provenance chain, three-valued condition logic, publication gate, and EU standards alignment are domain-agnostic patterns. The bereavement/Luxembourg dataset is a working reference implementation. If you are building source-backed regulatory workflows for a different life event or jurisdiction, this repository provides a tested starting point.

Clarvia Graph is maintained by Clarvia ASBL, a Luxembourg-registered nonprofit.

Our current funding needs and contribution channels are published in the project's funding.json manifest.

Current priority: an adoption-ready first release covering stable versioning, documentation, reproducible examples, validation, automated testing, governance, and independent technical review.

• Code & tooling: EUPL-1.2
• Graph data: CC-BY-4.0
• Schemas & vocabularies: CC0 or Apache-2.0
• Source snapshots: Not relicensed (follow original source terms)

See CONTRIBUTING.md for how to get involved.

We are grateful for the support of ecosystem partners who have endorsed Clarvia’s public-interest mission, including Trauerwee ASBL, which has expressed its intention to support a future pilot, and TSC Real Estate, which has endorsed our public-interest goals.

• lex — Open legal-data infrastructure — normalized national legislation for AI agents
• workflow-web — Consumer web application at clarvia.org
• workflow-data — Archived. Cross-border source, authority, and corridor data migrated into this graph in June 2026.

HirenGajjar built the original cross-border bereavement dataset in workflow-data — source records, institution registries, and corridor documentation for Belgium, France, Germany, and Portugal. That work materially accelerated the graph's cross-border coverage and now lives here as migrated authority, source, and condition records.