Home / CommonsTruth / CommonsTruth Specification
CommonsTruth
Where Evidence Becomes Action.
Specification
CommonsTruth is an open-source, privacy-first public accountability platform that enables consumers to anonymously document deceptive advertising, bait-and-switch practices, hidden fees, pricing discrepancies, misleading promotions, and other deceptive business practices through structured, evidence-based reports.
The system is designed to transform individual consumer experiences into organized public evidence that can reveal patterns, inform communities, support research, and encourage accountability while protecting the identity and privacy of people who submit reports.
Core Principles
- Anonymous by default
- Evidence before conclusions
- Privacy first
- Minimal data collection
- Public transparency
- Structured reporting
- Neutral and factual language
- Community corroboration
- Responsible moderation
- Open access to public information
- Human oversight
- Modular design
- Extensible architecture
- AGPL-3.0+ licensing
Core Modules
Anonymous Reporting
The Anonymous Reporting module provides a submission process that does not require users to create accounts or disclose their identity.
Features include:
- Anonymous report submission
- No required personal identification
- Optional contact information handled separately from public reports
- Anonymous session management
- Submission confirmation without requiring an account
- Abuse prevention without exposing user identity
- Privacy-preserving rate limiting
- Anonymous report status tracking where supported
Incident Documentation
The Incident Documentation module provides structured fields for recording consumer experiences.
Each report should support:
- Business name
- Business location
- Incident date
- Incident time
- Product or service involved
- Description of the incident
- Advertised price
- Displayed price
- Charged price
- Promotional terms
- Actual terms encountered
- Consumer response
- Business response, when available
- Resolution status
- Relevant category
- Supporting evidence
Reports should distinguish between documented facts, user observations, and conclusions.
Evidence Management
The Evidence Management module stores and organizes supporting documentation submitted with reports.
Supported evidence may include:
- Photographs
- Receipts
- Advertisements
- Screenshots
- Invoices
- Promotional materials
- Pricing displays
- Contracts
- Documents
- Digital communications
- Other relevant records
Evidence management should support:
- Secure uploads
- Evidence classification
- File integrity verification
- Evidence timestamps
- Duplicate detection
- Metadata inspection
- Metadata removal where appropriate
- Evidence association with incidents
- Evidence visibility controls
- Evidence retention policies
Fraud and Deception Classification
The Classification module organizes reports according to the type of alleged deceptive practice documented.
Categories may include:
- Bait and switch
- False advertising
- Misleading discount claims
- Misleading promotional pricing
- Hidden fees
- Undisclosed charges
- Coupon refusal
- Shelf price versus register discrepancy
- Advertised price versus charged price discrepancy
- Subscription traps
- Misleading limited-time offers
- Misleading product descriptions
- Other deceptive business practices
The classification system should remain extensible so new categories can be added without redesigning the core reporting system.
Evidence Verification
The Evidence Verification module evaluates the quality and consistency of submitted evidence without automatically determining legal liability.
Features include:
- Evidence completeness checks
- Timestamp validation
- Duplicate detection
- Document consistency checks
- Image integrity checks
- Report-to-evidence matching
- Conflicting information detection
- Evidence confidence indicators
- Verification status tracking
- Human review workflows
Verification results should describe evidence quality rather than declare a business legally guilty of fraud.
Corroboration
The Corroboration module identifies independent reports that may describe similar incidents.
Features include:
- Similar incident detection
- Duplicate report detection
- Business matching
- Location matching
- Product or service matching
- Time-period clustering
- Category clustering
- Recurring pattern identification
- Multi-report corroboration
- Corroboration confidence indicators
The system should distinguish independent corroboration from duplicate submissions.
Business Identification
The Business Identification module organizes reports around identifiable businesses and locations.
Features include:
- Business name normalization
- Location records
- Business location matching
- Multiple-location support
- Historical business names
- Business category classification
- Public business identifiers where appropriate
- Incident association by location
- Location-specific incident histories
The system should avoid incorrectly combining unrelated businesses with similar names.
Public Search
The Public Search module provides searchable access to published reports and evidence summaries.
Users should be able to search by:
- Business
- Location
- City
- State
- Category
- Product
- Date
- Incident type
- Price discrepancy
- Verification status
- Corroboration status
Search results should clearly distinguish reports, evidence, verified information, disputed information, and unresolved claims.
Public Accountability Dashboard
The Public Accountability Dashboard provides aggregated information about documented incidents.
Features include:
- Incident totals
- Category trends
- Geographic trends
- Business incident histories
- Incident timelines
- Recurring pattern indicators
- Price discrepancy summaries
- Corroboration statistics
- Verification statistics
- Public data summaries
Aggregated statistics should not be presented in a way that implies legal findings when the underlying reports have not established them.
Transparency and Data Access
The Transparency module provides public access to non-sensitive information generated by the platform.
Features include:
- Public datasets
- CSV exports
- JSON exports
- Public statistics
- Searchable records
- Data documentation
- Methodology documentation
- Verification methodology
- Moderation transparency
- Platform transparency reports
Personally identifying information and protected evidence should not be included in public datasets.
Research and Investigation
The Research module supports journalists, researchers, consumer advocates, watchdog organizations, and members of the public investigating patterns of deceptive business practices.
Features include:
- Trend analysis
- Incident clustering
- Geographic analysis
- Business pattern analysis
- Historical comparisons
- Search filters
- Public data exports
- Evidence references
- Citation-ready report identifiers
- Research datasets
- Investigation workspaces
Privacy Protection
The Privacy Protection module is responsible for protecting anonymous contributors and minimizing unnecessary collection of personal information.
Features include:
- Anonymous submission architecture
- Metadata removal
- EXIF handling
- Optional face redaction
- Optional license plate redaction
- Minimal logging
- Data minimization
- Privacy-preserving identifiers
- Secure evidence handling
- Retention controls
- Protection against accidental identity disclosure
Privacy controls should be applied before evidence becomes publicly accessible.
Abuse Prevention
The Abuse Prevention module protects the platform against spam, harassment, fabricated submissions, coordinated manipulation, and malicious use.
Features include:
- Rate limiting
- Submission throttling
- Duplicate detection
- Automated abuse indicators
- Suspicious activity detection
- Content review queues
- Evidence integrity checks
- Community reporting
- Moderator escalation
- Accountless abuse prevention mechanisms
Abuse prevention should preserve anonymity while limiting manipulation of public records.
Moderation
The Moderation module provides human oversight for published reports and platform content.
Moderation functions include:
- Evidence review
- Report review
- Policy enforcement
- Defamation risk review
- Privacy review
- Harassment review
- Fraudulent submission review
- Removal workflows
- Correction workflows
- Appeals
- Moderator audit records
Moderation should prioritize factual descriptions of documented events rather than unsupported accusations.
Corrections and Appeals
The Corrections and Appeals module provides mechanisms for correcting inaccurate information and challenging published reports.
Features include:
- Report correction requests
- Evidence corrections
- Business response requests
- Public dispute records
- Appeal submissions
- Moderator review
- Correction histories
- Resolution records
- Audit trails
Corrections should preserve appropriate historical records rather than silently rewriting material that has already been publicly published.
Business Response
The Business Response module provides businesses with an optional mechanism to respond to published reports.
Features may include:
- Verified business identity
- Public responses
- Dispute submissions
- Correction requests
- Resolution statements
- Evidence submissions
- Customer resolution records
- Response history
Business responses should remain clearly separated from consumer submissions and should not automatically override published evidence.
Notification and Alerts
The Notification module provides optional public alerts based on published patterns.
Features may include:
- Business alerts
- Category alerts
- Geographic alerts
- Pricing discrepancy alerts
- Recurring incident alerts
- Consumer notification feeds
- Research notification feeds
Users should be able to access alerts without being required to create an identity-linked account whenever practical.
Accessibility
The Accessibility module ensures that the platform can be used by people with different abilities and assistive technologies.
Requirements include:
- Keyboard navigation
- Screen reader compatibility
- Accessible forms
- Accessible evidence submission
- High readability
- Clear error messages
- Alternative text support
- Accessible data tables
- Accessible charts
- Mobile accessibility
- Reduced-complexity workflows
Multilingual Support
The Multilingual module provides infrastructure for supporting multiple languages.
Features include:
- Localized interfaces
- Localized reporting forms
- Translation-ready categories
- Multilingual search
- Language-specific moderation support
- Localized accessibility content
Audit and Provenance
The Audit and Provenance module maintains records describing how reports and evidence move through the platform.
Features include:
- Submission timestamps
- Evidence timestamps
- Verification history
- Moderation history
- Correction history
- Publication history
- Dispute history
- Data provenance
- Change tracking
Audit records should protect private identities while preserving the integrity and history of public records.
Governance
The Governance module defines how CommonsTruth is operated and how changes to the platform are managed.
Governance should address:
- Community standards
- Moderation standards
- Privacy standards
- Evidence standards
- Publication standards
- Appeals
- Security practices
- Data retention
- Transparency reporting
- Open-source contribution
- Specification changes
Optional Plugin Modules
OCR Evidence Plugin
Provides optical character recognition for receipts, advertisements, invoices, signs, and other submitted documents.
Capabilities may include:
- Receipt text extraction
- Price extraction
- Date extraction
- Business name extraction
- Advertisement comparison
- Structured evidence creation
Price Comparison Plugin
Compares advertised, displayed, historical, and charged prices.
Capabilities may include:
- Price discrepancy calculations
- Promotional price comparison
- Historical price comparison
- Percentage difference calculations
- Evidence-linked pricing records
AI Pattern Detection Plugin
Identifies potential recurring patterns across large collections of reports.
Capabilities may include:
- Incident clustering
- Similarity analysis
- Recurring behavior detection
- Geographic pattern detection
- Temporal pattern detection
- Anomaly identification
AI-generated findings must remain advisory and subject to human review.
Browser Extension Plugin
Allows users to capture potentially deceptive advertisements and pricing information while browsing.
Capabilities may include:
- Advertisement capture
- Page archiving
- Screenshot capture
- URL preservation
- Timestamp creation
- Evidence submission
Mobile Capture Plugin
Provides mobile-optimized evidence collection.
Capabilities may include:
- Camera evidence capture
- Receipt photography
- Advertisement photography
- Location selection
- Timestamp capture
- Offline evidence preparation
- Anonymous submission
Geographic Intelligence Plugin
Provides geographic analysis of reported incidents.
Capabilities may include:
- Regional maps
- Incident density
- Geographic clustering
- Local trend analysis
- Business location comparisons
Watchdog Organization Plugin
Provides dedicated tools for consumer advocacy organizations and watchdog groups.
Capabilities may include:
- Shared research workspaces
- Investigation management
- Custom datasets
- Organization dashboards
- Collaborative evidence review
- Public investigation reports
Journalism Plugin
Provides tools designed for investigative journalism.
Capabilities may include:
- Investigation workspaces
- Evidence collections
- Source-independent report analysis
- Exportable datasets
- Timeline generation
- Pattern analysis
- Citation support
Public API Plugin
Provides controlled programmatic access to public CommonsTruth data.
Capabilities may include:
- Search endpoints
- Public incident records
- Aggregate statistics
- Geographic data
- Category data
- Export functions
- Rate limiting
- API access controls
Community Verification Plugin
Allows qualified community participants to assist with evidence verification.
Capabilities may include:
- Verification queues
- Evidence review
- Structured verification responses
- Reviewer confidence indicators
- Reviewer reputation
- Conflict-of-interest controls
Consumer Alert Plugin
Provides notifications when significant patterns emerge in a user’s selected geographic or category areas.
Capabilities may include:
- Local alerts
- Business alerts
- Category alerts
- Recurring incident alerts
- Pricing alerts
- Public safety notifications
Data Export Plugin
Provides advanced export capabilities for researchers and public-interest organizations.
Supported formats may include:
- CSV
- JSON
- Structured research datasets
- Statistical summaries
- Evidence indexes
Exports must exclude protected personal information and private submission data.
Resolution Tracking Plugin
Tracks outcomes after a report has been published.
Capabilities may include:
- Business response
- Refund records
- Corrections
- Policy changes
- Promotional corrections
- Resolved incident status
- Supporting resolution evidence
Reputation and Trust Plugin
Provides trust indicators based on evidence quality and corroboration rather than popularity alone.
Potential indicators include:
- Evidence completeness
- Verification history
- Corroboration level
- Report consistency
- Contributor reliability signals
- Review quality
Trust indicators must not be used to identify anonymous contributors.
Legal and Policy Reference Plugin
Provides links and contextual information about applicable consumer protection laws, regulations, and government agencies.
The plugin should provide informational references and should not represent itself as providing legal advice.
Data Model Requirements
CommonsTruth should maintain structured relationships between:
- Reports
- Incidents
- Businesses
- Locations
- Products
- Services
- Advertisements
- Prices
- Evidence
- Categories
- Verification records
- Corroboration records
- Business responses
- Corrections
- Appeals
- Moderation records
- Audit records
The data model should support historical changes without destroying the provenance of previously published information.
Evidence Standards
Reports should prioritize evidence that is:
- Specific
- Time-bound
- Location-bound
- Relevant to the incident
- Original where possible
- Internally consistent
- Verifiable where possible
The platform should clearly distinguish:
- Submitted evidence
- Verified evidence
- Corroborated reports
- Disputed information
- Unverified claims
- Moderator findings
- Business responses
Publication Standards
Before publication, reports should undergo automated and, where necessary, human review for:
- Personal information
- Unsupported accusations
- Harassment
- Threats
- Malicious content
- Evidence manipulation
- Duplicate submissions
- Defamatory language
- Irrelevant material
- Privacy risks
Published reports should use neutral descriptions of documented events.
Specification Branding License (SBL)
Standard
- Fully AGPL-3.0+ compliant system
- Copyleft enforced for network deployments
- Required attribution:
- Roxanne Ardary
- https://www.roxanneardary.com/
Optional
- Specification Branding License (SBL)
- Attribution-free commercial deployment
- Pricing based on scale, usage, and deployment scope
- https://roxanneardary.com/commonstruth/
Contributing
Community contributions are welcome. Please help improve privacy, transparency, usability, moderation systems, and public-interest tooling.
License & Notice Requirements
CommonsTruth is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).
By contributing to this project, you agree that your contributions will also be released under this license.
Please note the following:
- All contributions must comply with the AGPL-3.0+ terms.
- Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to Roxanne Ardary and roxanneardary.com.
- CommonsTruth specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
- The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update
notice.md. - When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
- Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.
For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.
Notice – CommonsTruth
Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.
Contributors
This file tracks contributors and their specific contributions to the project.
- Roxanne Ardary, roxanneardary.com – May 1, 2026
Created the repository for CommonsTruth. Designed the open-source anonymous evidence reporting platform for deceptive advertising, bait-and-switch practices, and consumer fraud transparency. - [Add other contributors here] – [Date]
[Describe contribution in one sentence]
License – CommonsTruth
This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).
Key Points
- You are free to use, modify, and distribute the code.
- All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
- The software is provided “as is,” without warranty of any kind.
For the full license text, see GNU AGPL-3.0 License.