Digital Passport Model Assessment Workbench

This site documents an agent-oriented analytical toolkit for assessing SHACL-based digital passport models, comparing composed solutions and versions, and checking SHACL-only use-case coverage.

Purpose

The workbench is intended to support open and reproducible analysis of digital passport data models.

It focuses on questions such as:

how large and structurally complex is a model composition?
how explicit and constraint-ready is it?
how do two model compositions or versions differ?
can a declared use case be represented from the SHACL model alone?
which findings should be inspected first?

The tool works from inspectable model specifications and declared input files rather than hidden state or representative instance datasets.

Open Science And Replicability

The analysis is designed to be deterministic:

the same inputs should produce the same JSON outputs
input files are explicit and versionable
result documents are machine-readable and inspectable
tests use synthetic local fixtures that do not depend on network access
real live-source examples are separated from validation fixtures

This supports open-science practice: the analytical assumptions, input declarations, result payloads, and example applications can all be reviewed and reproduced.

Agent-Oriented Use

The workbench is designed to be usable directly by humans, but also by AI agents orchestrating analytical workflows.

The agent-oriented design choices are:

explicit file-based inputs
stable package API and CLI operations
JSON result envelopes
built-in discovery through capabilities, schema, vocabulary, and template
no chat-specific behavior inside the analytical core

AI agents can therefore help prepare inputs, run the pipeline, inspect outputs, and explain results while the underlying analysis remains deterministic.

Release-1 Scope

Release 1 provides:

SHACL ingestion from Turtle sources
composition-profile assessment
SHACL-only use-case coverage checks
pairwise comparison of assessment results
rule-based prioritization
discovery of built-in schemas, vocabularies, templates, and capabilities

Documentation Map

Analysis Dimensions: what the tool measures and reports.
Pipeline: operations, inputs, outputs, and result documents.
API Reference: Python package functions for humans, agents, and workflow runners.
Result Interpretation: how to read rich JSON outputs and deterministic summaries.
Example Applications: tutorial-style analytical progression for humans and AI agents.
MCP Server: stdio MCP runtime, registry discovery, packaging, and publication shape.
Source Ingestion: first tutorial step for profile loading and live URL examples.

Repository Validation

The repository-native validation path is:

make validate

This runs compile checks, the test suite, and lightweight CLI smoke checks without requiring an editable package install.

Funded by the European Union under Grant Agreement No. 101092281 — CE-RISE.
Views and opinions expressed are those of the author(s) only and do not necessarily reflect those of the European Union or the granting authority (HADEA). Neither the European Union nor the granting authority can be held responsible for them.

© 2026 CE-RISE consortium.
Licensed under the European Union Public Licence v1.2 (EUPL-1.2).
Attribution: CE-RISE project (Grant Agreement No. 101092281) and the individual authors/partners as indicated.

Developed by NILU (Riccardo Boero — ribo@nilu.no) within the CE-RISE project.

Analysis Dimensions

The workbench analyzes SHACL-based digital passport model specifications without requiring representative instance datasets.

Structural Size And Complexity

Structural metrics describe the scale and shape of a model composition.

Examples include:

number of node shapes
number of property shapes
number of target declarations
number of closed shapes
number of datatype-constrained properties
number of object-reference properties

These metrics help distinguish a compact model slice from a broader composed ecosystem.

Explicitness And Constraint Readiness

Explicitness metrics describe how much of the model is directly constrained in SHACL.

Examples include:

typed-property share
cardinality-bounded-property share
open-property share
constraint density

These metrics are useful when comparing whether one model expresses constraints more directly than another.

Structural Interoperability

Interoperability metrics describe relationships between modules in a composed profile.

Examples include:

cross-module reference count
cross-module reference share
shared-vocabulary overlap count
shared-vocabulary overlap ratio

Release 1 treats each top-level models entry in a composition profile as one module boundary.

Maintainability Signals

Maintainability findings are directly detectable issues or candidates from the SHACL graph.

Examples include:

contradictions
dangling references
redundancy candidates

These findings are intentionally conservative. They are meant to be inspectable signals, not hidden semantic judgments.

Use-Case Coverage

Coverage analysis checks whether a declared use case can be represented from the composed SHACL model.

Use cases are declared as:

required information items
required joins or concept links

Coverage classes are:

representable
partially_representable
not_representable
indeterminate

The result is SHACL-only. It does not require instance data.

Model Comparison

Comparison runs on two assessment result documents with the same comparison_scope_label.

It reports:

metric values for both sides
deltas
normalized ranked observations
optional alignment-aware comparison when an analyst-authored alignment file is supplied

This supports both version comparison and cross-ecosystem comparison.

Prioritization

Prioritization consumes previous result documents and ranks follow-up targets.

Signals can come from:

coverage gaps
maintainability findings
directional comparison deltas
alignment gaps

The prioritization layer is rule-based and explainable by design.

Result Interpretation

The summarize operation provides a lightweight interpretation layer over existing result documents.

It does not add new analysis. It extracts a concise headline, key points, and follow-up questions from already computed results.

Pipeline

The release-1 analytical pipeline is intentionally explicit and file-based.

Operations

assess Input: one composition profile Output: one assessment_result
coverage Input: one composition profile and one use-case file Output: one coverage_result
compare Input: two assessment_result documents and optional alignment file Output: one comparison_result
prioritize Input: one assessment_result, optional comparison_result, and optional list of coverage_result documents Output: one prioritization_result Consumes coverage gaps, maintainability findings, structural comparison observations, and alignment-gap observations when present.
summarize Input: one or more result documents Output: one summary_result Produces a compact deterministic interpretation over existing results without rerunning analysis. The JSON result is canonical; the CLI may also render it as Markdown.

Result Documents

All analytical result documents use the same top-level envelope:

result_type
inputs
content
diagnostics

For comparison_result, the main analytical sections are:

structural_comparison Metric deltas and ranked structural observations.
alignment Present only when an alignment file is supplied. Includes aggregate counts, evaluated_pairs, and ranked_alignment_observations for unmatched declared equivalences.

For prioritization_result, the ranked target list may therefore include:

coverage gaps
maintainability findings
structural comparison observations
alignment gaps derived from declared but incompletely matched equivalences

For summary_result, the main sections are:

headline
result_types
key_points
follow_up_questions

Current release-1 analytical semantics are intentionally conservative, but they now include:

direct contradiction detection for cardinality conflicts and datatype-versus-object-reference conflicts
item coverage matching from SHACL property-path, owner-shape, and target-class evidence
join coverage matching from shared owner shapes, explicit cross-shape object-reference paths, or record-level retrieval context where appropriate

Discovery

The tool exposes built-in artifacts through:

schema
vocabulary
template
capabilities

These discovery commands are intended for both humans and AI-agent skills.

API Reference

The Python package API is the primary integration surface for agents and workflow runners.

All public functions return JSON-compatible dictionaries. The same result payloads are emitted by the CLI as JSON.

Import from dpawb.api:

from dpawb.api import assess, coverage, compare, prioritize, summarize
from dpawb.api import capabilities, schema, template, vocabulary

Analytical Operations

`assess(profile_path: str) -> dict[str, object]`

Assess one composition profile and return an assessment_result.

Input:

profile_path: local path to a composition profile YAML file.

The profile may reference local SHACL Turtle files or live URL sources.

`coverage(profile_path: str, use_case_path: str) -> dict[str, object]`

Assess one use case against one composition profile and return a coverage_result.

Inputs:

profile_path: local path to a composition profile YAML file.
use_case_path: local path to one use-case YAML file.

`compare(left_assessment_path: str, right_assessment_path: str, alignment_path: str | None = None) -> dict[str, object]`

Compare exactly two existing assessment result documents and return a comparison_result.

Inputs:

left_assessment_path: local path to the left assessment_result JSON document.
right_assessment_path: local path to the right assessment_result JSON document.
alignment_path: optional local path to an analyst-authored alignment YAML file.

The two assessment results must have the same declared comparison_scope_label.

`prioritize(assessment_path: str, comparison_path: str | None = None, coverage_paths: list[str] | None = None) -> dict[str, object]`

Rank improvement targets from existing result documents and return a prioritization_result.

Inputs:

assessment_path: local path to one assessment_result JSON document.
comparison_path: optional local path to one comparison_result JSON document.
coverage_paths: optional list of coverage_result JSON document paths.

`summarize(result_paths: list[str]) -> dict[str, object]`

Create a compact deterministic interpretation document from one or more existing result documents.

Input:

result_paths: list of JSON result document paths.

This operation is rule-based. It does not call an AI model.

Discovery Operations

`schema(name: str) -> dict[str, object]`

Return a bundled JSON Schema as a schema_result.

Common names include:

profile
use_case
alignment
assessment_result
coverage_result
comparison_result
prioritization_result
summary_result

`vocabulary(name: str) -> dict[str, object]`

Return a bundled controlled vocabulary as a vocabulary_result.

Current names:

item_categories
join_kinds

`template(name: str) -> dict[str, object]`

Return a bundled YAML template as a template_result.

Current names:

profile
use_case
alignment

`capabilities() -> dict[str, object]`

Return a capabilities_result describing the package/CLI command surface.

This is the recommended discovery entry point for AI agents and MCP wrappers.

Agent Usage Pattern

Agents should treat every API call as a deterministic pipeline step:

Prepare explicit YAML or JSON input files.
Call one API function.
Store the returned dictionary as a JSON result document when it is needed by a downstream step.
Pass stored result paths to downstream operations such as compare, prioritize, or summarize.

The API does not perform hidden semantic mapping. Alignment-aware behavior only uses analyst-authored alignment files.

Result Interpretation

The workbench produces rich JSON outputs.

This is intentional. The raw outputs are meant to be:

inspectable by humans
parseable by AI agents
suitable for reproducible pipelines
traceable back to model inputs

Result Envelope

All current result documents use the same top-level envelope:

result_type
inputs
content
diagnostics

inputs identifies what was analyzed.

content contains the operation-specific analytical result.

diagnostics records non-fatal notes, limitations, or processing details.

Reading Assessment Results

An assessment_result should be read as a model instrument panel.

The main sections are:

metrics
maintainability findings
module summaries
trace index

The metrics show model size, explicitness, constraint readiness, and interoperability signals.

Maintainability findings should be inspected as candidate issues, not automatically as defects.

Reading Coverage Results

A coverage_result answers whether a declared use case is representable from the composed SHACL model.

Important fields are:

overall_coverage_class
required_item_findings
required_join_findings
supporting_trace

supporting_trace is important because it shows why the workbench classified an item or join in a certain way.

Reading Comparison Results

A comparison_result compares exactly two assessment results.

Important sections are:

metric_deltas
ranked_observations
optional alignment

ranked_observations are sorted to emphasize normalized analytical signals before raw size differences.

When an alignment file is provided, inspect:

alignment_coverage_ratio
evaluated_pairs
ranked_alignment_observations

Alignment results are declaration-based. The workbench does not infer semantic equivalence automatically.

Reading Prioritization Results

A prioritization_result is a ranked follow-up list.

Each target includes:

target_id
priority_rank
message
rule_trace

rule_trace explains why the target was ranked.

Prioritization is not a final quality judgment. It is an interpretable queue for follow-up analysis.

Lightweight Interpretation Layer

The tool includes a preliminary simplified interpretation operation:

summarize

It produces a compact summary_result from one or more existing result documents.

This component does not replace the raw outputs. It sits on top of them.

It is deterministic and rule-based.

The summary does not use AI interpretation. It selects signals using fixed rules:

coverage findings are ordered by fixed coverage severity
comparison signals use the already ranked comparison observations
alignment gaps use the already ranked alignment observations
prioritization signals use the already ranked target list
only a small fixed number of strongest signals is promoted

The CLI can also render the same deterministic summary as Markdown:

dpawb summarize --result comparison.json --format markdown

Example output shape:

{
  "result_type": "summary_result",
  "inputs": {
    "result_count": 2
  },
  "content": {
    "headline": "Both compared profiles satisfy the selected use case; main differences are constraint explicitness and modelling compactness.",
    "key_points": [
      "Coverage is representable on both sides.",
      "BatteryPass is more compact on the reduced slice.",
      "CE-RISE represents the same concepts through a composed model set."
    ],
    "follow_up_questions": [
      "Should compactness or modular extensibility matter more for this use case?"
    ]
  },
  "diagnostics": []
}

This would help humans and AI agents interpret rich outputs consistently while preserving deterministic analysis underneath.

Example Progression

The repository examples show an increasing degree of analytical comparison.

They are not organized by data model. Data models are inputs inside each example.

The examples are written as a tutorial path for both humans and AI agents:

Humans can read each folder README and run the commands step by step.
AI agents can follow the same folders as deterministic task recipes, using the declared YAML inputs and JSON outputs.
The numbered folders intentionally move from simpler operations to richer comparison workflows.
Source ingestion Load and assess composition profiles from live URL sources.
Structural comparison Compare two assessment results for profiles with the same declared scope.
Reduced use-case comparison Run the first hand-checkable aligned use-case comparison.
Extended use-case comparison Run a broader aligned use-case comparison to exercise more coverage signals.

Why Four Folders?

The folders reflect the analysis workflow, not source ecosystems.

Read them in numerical order.

Shared Preparation Pattern

The comparison examples are self-contained and follow the same preparation pattern:

Define the comparison scope.
Define the left composition profile.
Define the right composition profile.
Define the use-case YAML.
Define the analyst-authored alignment YAML.
Run coverage for the left profile.
Run coverage for the right profile.
Run assessment for the left profile.
Run assessment for the right profile.
Run comparison.
Run prioritization.
Run deterministic summarization.

Folder Layout

Each canonical example folder uses this structure:

profiles/
use_cases/
alignments/
models/
notes/
results/

The results/ folder contains deterministic summary outputs generated from the raw result documents.

The raw result documents can be regenerated from the step-by-step commands in each example README.

For agents, the important rule is that every step consumes explicit files and produces deterministic JSON or Markdown outputs. No hidden interpretation step is required to reproduce the example.

Source Ingestion

Folder:

examples/01-source-ingestion/

Purpose:

exercise live URL loading
assess composition profiles without local model files
keep source selection separate from comparison logic

Structural Comparison

Folder:

examples/02-structural-comparison/

Purpose:

assess two profiles
compare their structural metrics
optionally add an analyst-authored alignment file

Reduced Use-Case Comparison

Folder:

examples/03-reduced-use-case-comparison/

Purpose:

compare the minimum product-identification slice
validate that both input profiles represent the selected identification concepts
provide the main worked example for documentation and inspection

Start here:

examples/03-reduced-use-case-comparison/README.md

Extended Use-Case Comparison

Folder:

examples/04-extended-use-case-comparison/

Scope:

battery_passport_metadata_and_classification

Purpose:

validate the same workflow on a broader slice
add version/revision semantics
add type/category/classification semantics
check that the matching and summarization behavior is not overfit to the reduced example

Start here:

examples/04-extended-use-case-comparison/README.md

MCP Server

The package ships a thin stdio MCP server over the same deterministic package operations and JSON result contracts.

Alignment Rule

The implementation rule is:

one package API function
one CLI command
one MCP tool

with the same conceptual inputs and the same JSON result payload.

Tool Mapping

Package API	CLI command	MCP tool	Result type
`assess`	`assess`	`assess`	`assessment_result`
`coverage`	`coverage`	`coverage`	`coverage_result`
`compare`	`compare`	`compare`	`comparison_result`
`prioritize`	`prioritize`	`prioritize`	`prioritization_result`
`schema`	`schema`	`schema`	`schema_result`
`vocabulary`	`vocabulary`	`vocabulary`	`vocabulary_result`
`template`	`template`	`template`	`template_result`
`capabilities`	`capabilities`	`capabilities`	`capabilities_result`
`summarize`	`summarize`	`summarize`	`summary_result`

Result Contract

The MCP server reuses the same result-envelope style already used by the package:

result_type
inputs
content
diagnostics

This applies to analytical results and now also to discovery-style results.

Discovery Bridge

capabilities is the main bridge for MCP-aware agent tooling.

It now states, for each operation:

the CLI command name
the package API function name
the MCP tool name
the conceptual inputs
stable input-field descriptions
the emitted result type

That means the MCP wrapper does not invent a second command catalog.

The current package/CLI names remain the source of truth. The input_fields entries in capabilities are descriptive metadata for agent tooling and MCP schema generation; they do not introduce a second invocation API.

Runtime Shape

local Python entry point: dpawb-mcp
transport: stdio
message framing: newline-delimited JSON-RPC 2.0
exposed MCP capability: tools
current tool set: assess, coverage, compare, prioritize, schema, vocabulary, template, capabilities, summarize

Access And Discovery

The MCP identity is:

registry name: io.github.CE-RISE-software/dpawb
OCI image pattern: ghcr.io/ce-rise-software/dpawb-mcp:<release-version>
official registry base: https://registry.modelcontextprotocol.io/
source metadata file: server.json

The server is discoverable in the official MCP Registry by searching for io.github.CE-RISE-software/dpawb.

Registry discovery page:

https://registry.modelcontextprotocol.io/?q=dpawb

Minimal local client configuration:

{
  "mcpServers": {
    "dpawb": {
      "command": "dpawb-mcp"
    }
  }
}

Packaging And Publication

The MCP server has two runtime paths:

local Python installation through the dpawb package
GitHub Container Registry image for MCP-oriented distribution from the GitHub mirror

The repository includes placeholder MCP registry metadata in server.json. The publish workflow writes the release version and OCI image tag before uploading to the official MCP Registry with GitHub OIDC.

Source Ingestion Examples

Release 1 supports composition-profile sources that are either local Turtle files or live URLs.

This page is the first tutorial step in the examples progression. It shows how a human or an AI agent can start from declared profile files and run deterministic assessment or coverage commands.

Examples

The source-ingestion examples use live SHACL URLs as inputs:

examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml
examples/01-source-ingestion/profiles/battery_product_identification_live.yaml
examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml
examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml
examples/01-source-ingestion/profiles/metadata_focused_composition_live.yaml
examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml
examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml
examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml

If you want a single live source, the metadata-oriented example is the main starting point:

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml

If you want a composed profile, use:

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml

You can also run the traceability-only example:

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml

Or through an installed CLI:

dpawb assess --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml

Coverage Examples

The repository also includes use-case examples for coverage runs:

examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml
examples/01-source-ingestion/use_cases/battery_product_identification.yaml
examples/01-source-ingestion/use_cases/battery_passport_metadata_and_classification.yaml
examples/01-source-ingestion/use_cases/record_identity_lookup.yaml
examples/01-source-ingestion/use_cases/provenance_actor_lookup.yaml

Example:

./scripts/run-local.sh coverage \
  --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml \
  --use-case examples/01-source-ingestion/use_cases/record_identity_lookup.yaml

For the broader battery-DPP comparison effort, the main starting use case is:

examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml

This keeps the first shared scope intentionally narrow:

passport identity
battery identity
version or revision
one responsible actor
one battery type or classification signal

The matching starting composition for that use case is:

examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml

This currently composes:

dp_record_metadata
traceability_and_life_cycle_events

This remains a broader exploratory baseline for the battery-DPP scope, but it is not the main validated comparison slice.

For the first reduced real comparison pass, use:

examples/03-reduced-use-case-comparison/

This narrower left-side slice composes:

dp_record_metadata
product_profile
traceability_and_life_cycle_events

and is the first validated comparison baseline against the right-side General Product Information proxy.

A second broader validated comparison slice is also included:

examples/04-extended-use-case-comparison/

This adds:

passport version or revision
battery type or classification

while staying inside the same composed left-side model set.

Comparison examples

For manual pairwise comparison, use the comparison-ready live pair:

examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml
examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml
examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml as a starting-point alignment example

Example:

./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml --output /tmp/left.json
./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml --output /tmp/right.json
./scripts/run-local.sh compare --left /tmp/left.json --right /tmp/right.json

Alignment-aware example:

./scripts/run-local.sh compare \
  --left /tmp/left.json \
  --right /tmp/right.json \
  --alignment examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml

For alignment-aware comparison results, inspect:

alignment_coverage_ratio for the overall declared-match coverage
evaluated_pairs for the full per-pair presence status
ranked_alignment_observations for declared matches that are left_only, right_only, or missing_both

Those ranked alignment observations are the main review queue for analyst follow-up when a declared equivalence is not matched on both sides.

Notes

fixtures/ is reserved for synthetic local validation assets only.
examples/01-source-ingestion/ demonstrates live URL source loading.
examples/03-reduced-use-case-comparison/ and examples/04-extended-use-case-comparison/ demonstrate aligned use-case comparison.
Live URL fetching is allowed in the contract.
Release 1 does not cache fetched sources across runs.
If reproducibility matters, use a pinned URL or a locally captured Turtle file instead.
CI validation intentionally does not depend on live network sources; it uses synthetic local fixtures only.

Keyboard shortcuts

Digital Passport Model Assessment Workbench Documentation