# dppvalidator - Extended Context for LLMs

> Python library for validating Digital Product Passports (DPP) according to EU ESPR regulations and UNTP standards.

## Overview

dppvalidator is the open-source compliance engine for EU Digital Product Passports. The EU's Ecodesign for Sustainable Products Regulation (ESPR) mandates Digital Product Passports for textiles starting 2027. This library ensures DPP data is compliant before production.

## Tech Stack

- Python 3.10+
- Pydantic v2 for validation models
- Included: httpx, jsonschema, pyld, cryptography, PyJWT
- Optional: rich (CLI formatting via `[cli]` extra)

## Installation

```bash
# Using uv (recommended)
uv add dppvalidator               # Full functionality
uv add "dppvalidator[cli]"        # With rich CLI formatting

# Or using pip
pip install dppvalidator
pip install "dppvalidator[cli]"
```

## Architecture

### Seven-Layer Validation

0. **Schema Detection**: Auto-detect DPP schema version from $schema/@context
1. **Schema Layer (SCH001-SCH099)**: JSON Schema Draft 2020-12 validation
2. **Model Layer (MOD001-MOD099)**: Pydantic v2 type validation and coercion
3. **Semantic Layer (SEM001-SEM099)**: Business rules, ISO codes, GTIN checksums
4. **JSON-LD Layer (JLD001-JLD099)**: PyLD expansion, context resolution
5. **Vocabulary Layer (VOC001-VOC099)**: External code lists, ontology validation
6. **Plugin Layer**: Custom validator plugins via entry points
7. **Signature Layer (SIG001-SIG099)**: VC signature verification, DID resolution

### Performance

- Model (minimal): 0.011ms (87k ops/sec)
- Model (full): 0.016ms (62k ops/sec)
- Semantic: 0.005ms (194k ops/sec)
- Full (Model+Sem): 0.017ms (58k ops/sec)

## Core API

### ValidationEngine

```python
from dppvalidator.validators import ValidationEngine

# All layers (default)
engine = ValidationEngine()

# Specific layers
engine = ValidationEngine(layers=["schema"])
engine = ValidationEngine(layers=["model", "semantic"])

# Strict mode (warnings become errors)
engine = ValidationEngine(strict_mode=True)

# Validate
result = engine.validate(dpp_dict)
# Returns: ValidationResult with .valid, .errors, .warnings, .validation_time_ms
```

### Models

```python
from dppvalidator.models import (
    DigitalProductPassport,
    CredentialIssuer,
    Product,
    IdentifierScheme,
    Link,
)

passport = DigitalProductPassport(
    id="https://example.com/dpp/product-001",
    issuer=CredentialIssuer(id="https://example.com/issuer", name="Company"),
)
```

### Exporters

```python
from dppvalidator.exporters import JSONLDExporter

exporter = JSONLDExporter()
jsonld = exporter.export(passport)  # W3C Verifiable Credential format
```

### Plugin System

```python
from dppvalidator.plugins import PluginRegistry
from dppvalidator.validators import ValidationEngine

# Define a validator implementing the SemanticRule protocol
class CustomValidator:
    rule_id = "CUSTOM001"
    description = "Custom validation rule"
    severity = "error"

    def check(self, passport):
        """Return list of (json_path, error_message) tuples."""
        violations = []
        # Custom validation logic
        return violations

# Manual registration
registry = PluginRegistry(auto_discover=False)
registry.register_validator("custom", CustomValidator)

# Or use entry points for automatic discovery
engine = ValidationEngine(load_plugins=True)
```

## CLI Usage

```bash
dppvalidator validate passport.json
dppvalidator validate passport.json --strict
dppvalidator export passport.json --format jsonld --output out.jsonld
dppvalidator schema --version 0.6.1
```

## Directory Structure

```
src/dppvalidator/
├── models/          # Pydantic models for DPP entities
├── validators/      # Validation engine and layers
├── verifier/        # Signature and credential verification
├── exporters/       # JSON-LD and other export formats
├── schemas/         # JSON Schema loading and caching
├── vocabularies/    # Controlled vocabulary loading
├── cli/             # Command-line interface
├── plugins/         # Plugin system
└── __init__.py
```

## Related Standards

- UNTP Digital Product Passport: https://untp.unece.org/docs/specification/DigitalProductPassport/
- EU ESPR Regulation: https://environment.ec.europa.eu/topics/circular-economy/ecodesign-sustainable-products-regulation_en
- W3C Verifiable Credentials: https://www.w3.org/TR/vc-data-model/

## Links

- Documentation: https://artiso-ai.github.io/dppvalidator/
- PyPI: https://pypi.org/project/dppvalidator/
- GitHub: https://github.com/artiso-ai/dppvalidator
- Issues: https://github.com/artiso-ai/dppvalidator/issues