civic-transparency-ptag-spec 0.2.2

Civic Transparency PTag specification schemas

Civic Transparency PTag Specification

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

Schemas

Schema	Purpose	Status
ptag.schema.json	Per-post behavioral metadata	Draft
ptag_series.schema.json	Aggregated time series API responses	Draft
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 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 - Typed Python models auto-generated from these schemas.
• civic-transparency-go-ptag-types - Go structs from schemas (Go module).
• civic-transparency-js-ptag-types - TypeScript typings (npm, @civic-interconnect/ptag-types).

CWE-based proactive catalog including PTag mappings:

• civic-transparency-cwe-catalog -

Go Ecosystem:

• civic-transparency-go-sdk - Go SDK and integrations.

Versioning

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

License

MIT © Civic Interconnect