Civic Transparency – Types

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

Maintained by Civic Interconnect.

• Documentation: https://civic-interconnect.github.io/civic-transparency-types/
• Schema Specification: https://civic-interconnect.github.io/civic-transparency-spec/
• Contributing: CONTRIBUTING.md

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

Installation

pip install civic-transparency-types

For development or schema validation:

pip install "civic-transparency-types[dev]"

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

Quick Start

Basic Usage

from ci.transparency.types import Series, ProvenanceTag

# Create a time series for civic data
series = Series(
    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.types import Series

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

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

Working with Provenance Tags

from ci.transparency.types import ProvenanceTag

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

Available Types

See the API documentation for complete field definitions and examples.

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.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

This package follows the underlying specification versions:

• Major versions: Breaking schema changes
• Minor versions: Backward-compatible additions
• Patch versions: Documentation, tooling, bug fixes

Best Practice: Pin to compatible major versions:

pip install "civic-transparency-types>=0.2.1,<1.0"

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

Integration Examples

FastAPI Integration

from fastapi import FastAPI
from ci.transparency.types import Series

app = FastAPI()

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

File I/O

from pathlib import Path
from ci.transparency.types import Series

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

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

Development and Contributing

This is a generated types package - the source of truth is the civic-transparency-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

git clone https://github.com/civic-interconnect/civic-transparency-types
cd civic-transparency-types
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

See CONTRIBUTING.md for detailed guidelines.

Support and Community

• Documentation: https://civic-interconnect.github.io/civic-transparency-types/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: info@civicinterconnect.org

About Civic Transparency

Civic Transparency is an open standard for privacy-preserving, non-partisan analysis of how information spreads in civic contexts. The specification enables researchers, platforms, and civic organizations to share insights while protecting individual privacy.

Core Principles:

• Privacy by Design: No personally identifiable information
• Aggregation First: Time-bucketed, statistical summaries
• Open Standard: Collaborative, transparent development
• Practical Implementation: Real-world deployment focus