Metadata-Version: 2.4
Name: civic-transparency-ptag-spec
Version: 0.2.2
Summary: Civic Transparency PTag specification schemas
Author: Civic Interconnect
License-Expression: MIT
Project-URL: Bug Tracker, https://github.com/civic-interconnect/civic-transparency-ptag-spec/issues
Project-URL: Documentation, https://civic-interconnect.github.io/civic-transparency-ptag-spec/latest/
Project-URL: Homepage, https://github.com/civic-interconnect/civic-transparency-ptag-spec
Project-URL: Repository, https://github.com/civic-interconnect/civic-transparency-ptag-spec
Keywords: civic,transparency,ptag,jsonschema,specification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: bandit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: check-jsonschema; extra == "dev"
Requires-Dist: defusedxml; extra == "dev"
Requires-Dist: deptry; extra == "dev"
Requires-Dist: jsonschema; extra == "dev"
Requires-Dist: openapi-spec-validator; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: PyYAML; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: validate-pyproject; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-gen-files; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
Requires-Dist: mkdocs-literate-nav; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocs-static-i18n; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.18; extra == "docs"
Requires-Dist: mike; extra == "docs"
Dynamic: license-file

# Civic Transparency PTag Specification

[![CI Status](https://github.com/civic-interconnect/civic-transparency-ptag-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/civic-interconnect/civic-transparency-ptag-spec/actions/workflows/ci.yml)
[![Docs: latest](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://civic-interconnect.github.io/civic-transparency-ptag-spec/)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
[![Python: 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/release/python-3120/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

> **Normative specification** for privacy-preserving provenance tags (PTags)
> Includes JSON Schemas and OpenAPI definitions for transparency APIs.

## Schemas

| Schema | Purpose | Status |
|--------|---------|--------|
| [`ptag.schema.json`](./src/ci/transparency/ptag/spec/schemas/ptag.schema.json) | Per-post behavioral metadata | Draft |
| [`ptag_series.schema.json`](./src/ci/transparency/ptag/spec/schemas/ptag_series.schema.json) | Aggregated time series API responses | Draft |
| [`ptag_api.openapi.yaml`](./src/ci/transparency/ptag/spec/schemas/ptag_api.openapi.yaml) | REST API specification | Draft |

## Implementation Flow

1. **Generate provenance tags** when posts are created (per `ptag.schema.json`).
2. **Aggregate tags into time buckets** (with k-anonymity ≥ 100).
3. **Expose aggregated data** via REST API (per `ptag_api.openapi.yaml`).

See [API documentation](./src/ci/transparency/ptag/spec/schemas/ptag_api.openapi.yaml) for complete specification.

## Designed for Privacy

- All responses maintain k-anonymity (k≥100).
- No individual posts or users are exposed.
- Rare categories (<5%) are grouped as "other".
- Geographic data limited to country-level or 1M+ (ISO codes).

## Related Repositories

Three Generated Types:

- [civic-transparency-py-ptag-types](https://github.com/civic-interconnect/civic-transparency-py-ptag-types) - Typed Python models auto-generated from these schemas.
- [civic-transparency-go-ptag-types](https://github.com/civic-interconnect/civic-transparency-go-ptag-types) - Go structs from schemas (Go module).
- [civic-transparency-js-ptag-types](https://github.com/civic-interconnect/civic-transparency-js-ptag-types) - TypeScript typings (npm, @civic-interconnect/ptag-types).

CWE-based proactive catalog including PTag mappings:

- [civic-transparency-cwe-catalog](https://github.com/civic-interconnect/civic-transparency-cwe-catalog) -

Go Ecosystem:

- [civic-transparency-go-sdk](https://github.com/civic-interconnect/civic-transparency-go-sdk) - Go SDK and integrations.


## Versioning

This specification follows semantic versioning.
See [CHANGELOG.md](./CHANGELOG.md) for version history.

## License

MIT © [Civic Interconnect](https://github.com/civic-interconnect)
