Civic Transparency – Types

Typed Python models (Pydantic v2) for the Civic Transparency PTag schema.

Overview

This package provides strongly-typed Python models that correspond to the Civic Transparency specification. The types are automatically generated from canonical JSON Schema definitions, ensuring consistency and validation at runtime.

Key Features:

• Type Safety: Full Pydantic v2 validation with IDE support
• Schema Compliance: Generated directly from official JSON schemas
• Privacy-First: Designed for aggregated, non-PII data exchange
• Interoperability: JSON serialization/deserialization with validation

Available Types

See the API documentation for complete field definitions and examples.

Installation

pip install civic-transparency-py-ptag-types

Note: This package automatically includes the compatible civic-transparency-ptag-spec version as a dependency.

Quick Start

Basic Usage

from ci.transparency.ptag.types import PTagSeries, PTag

# Create a time series for civic data
series = PTagSeries(
    topic="#LocalElection",
    generated_at="2025-01-15T12:00:00Z",
    interval="minute",
    points=[]  # Add your aggregated data points here
)

# Validate and serialize
data = series.model_dump()  # JSON-compatible dict
json_str = series.model_dump_json(indent=2)  # Pretty JSON string

Loading and Validation

from ci.transparency.ptag.types import PTagSeries

# Load from existing data with validation
series = PTagSeries.model_validate(data_dict)
series = PTagSeries.model_validate_json(json_string)

# Handle validation errors
from pydantic import ValidationError
try:
    invalid_series = PTagSeries.model_validate(bad_data)
except ValidationError as e:
    print(f"Validation failed: {e}")

Working with PTags (Provenance Tags)

from ci.transparency.ptag.types import PTag

tag = PTag(
    acct_age_bucket="1-6m",
    acct_type="person",
    automation_flag="manual",
    post_kind="original",
    client_family="mobile",
    media_provenance="hash_only",
    dedup_hash="a1b2c3d4"
)

Validation and Schemas

Pydantic Validation

All models use Pydantic v2 for runtime validation:

• Strict typing: Unknown fields are rejected
• Format validation: ISO 8601 dates, patterns, enums
• Range checking: Min/max values, string lengths
• Nested validation: Complex object hierarchies

JSON Schema Validation (Optional)

For additional validation against the canonical schemas:

import json
from importlib.resources import files
from jsonschema import Draft202012Validator

# Get the official schema
schema_text = files("ci.transparency.ptag.spec.schemas").joinpath("series.schema.json").read_text()
schema = json.loads(schema_text)

# Validate your data
validator = Draft202012Validator(schema)
validator.validate(series.model_dump())

Versioning Strategy

The package automatically manages compatibility with the corresponding civic-transparency-ptag-spec version.

Integration Examples

FastAPI Integration

from fastapi import FastAPI
from ci.transparency.ptag.types import PTagSeries

app = FastAPI()

@app.post("/civic-data")
async def receive_series(series: PTagSeries) -> dict:
    # Automatic validation and parsing
    return {"received": series.topic, "points": len(series.points)}

File I/O

from pathlib import Path
from ci.transparency.ptag.types import PTagSeries

# Save to file
series_file = Path("data.json")
series_file.write_text(series.model_dump_json(indent=2))

# Load from file
loaded_series = PTagSeries.model_validate_json(series_file.read_text())

Performance Benchmarks

See the latest benchmark results in performance_results.md.

Development and Contributing

This is a generated types package - the source of truth is the civic-transparency-ptag-spec repository.

For Type Users

• Report type-related issues here
• Request documentation improvements
• Share integration examples

For Schema Changes

• Schema modifications should be made in the spec repository
• Types are automatically regenerated when the spec changes

Local Development

See CONTRIBUTING.md for detailed guidelines.

Versioning

This specification follows semantic versioning. See CHANGELOG.md for version history.

License

MIT © Civic Interconnect