How to Read This Project

This guide helps you navigate the documentation based on your role and what you need to learn.

Quick Start: 60-Second Summary

The Core Idea

Open source procurement is held back not by the absence of good software, but by the absence of shared, machine-readable evidence — the foundation of data-driven procurement decisions rather than purely relationship-driven ones. The north star of this project is decentralized metadata exchange: every stakeholder — projects, vendors, deploying organizations, registries — publishes structured data from their own domain. That data can be crawled independently by any catalog or procurement tool, and further annotated with external verification, trust labels, or policy signals. No central authority controls what gets published or how it is interpreted.

Every step toward this vision has value on its own terms. If some components of this proposal are adopted, others handled by adjacent standards, and still others deferred or never needed — the ecosystem still moves in the right direction. Read the proposal's breadth as a concrete map toward that destination, not a prerequisite checklist.

What This Is

• A proposal to improve publiccode.yml and related ecosystem standards.
• A practical path to make open source easier to discover, assess, and procure in the public sector.
• A bridge between technical metadata standards and procurement/policy enforcement.

Why It Matters

• Public institutions often support digital sovereignty in principle, but procurement still defaults to proprietary vendors.
• Procurement officers face institutional risk when deviating from familiar frameworks.
• Security is often perceived as a proprietary advantage, even though roughly 96% of software products already include open source components (OSBA).
• Missing piece: reliable, comparable, auditable infrastructure for evaluating open source options at scale.
• A data-driven approach lowers perceived personal and institutional risk by replacing relationship-based choices with documented evidence, making it easier and safer to deviate from proprietary-first defaults.

What This Project Adds

• Better project metadata and discovery standards.
• Registry APIs and discovery mechanisms for decentralized evidence collection.
• Policy-aligned structures so procurement decisions can be transparent and defensible.
• A data-driven basis for procurement decisions that supports justified deviation from incumbent proprietary norms.

Positive Feedback Loop (Design Intent)

1. Procurement policies and sovereignty mandates create demand for standardized metadata.
2. Projects and vendors adopt the extended standards.
3. Governments gain auditable evidence for procurement, security, and funding decisions.
4. Open source adoption becomes more confident, sustainable, and resilient.

Who This Is For

• Procurement professionals
• Open source maintainers
• Policy makers and legislators
• Vendors and service providers
• Researchers and standards specialists
• Funders and grant managers
• Software catalog operators

Core Proposal Components

Improvements to publiccode.yml:

• Faceted Classification — multi-dimensional discovery
• Supply Chain References — SBOMs, policies, security evidence
• Accessibility Declaration — product accessibility baseline for procurement
• Certifications and Seals — attested proof, project-side
• Interoperability and Standards Declarations — per-standard support status
• Compliance Document References — privacy policy, terms, DPA
• Vendor Contribution Credit System Discovery — vendor and contributor visibility
• Deprecate usedBy — usage moves to external registries (trust-model-tagged decentralized adoption signals)
• Deprecate Temporal Fields — cleaner and more trustworthy data
• Package Distribution References — npm, PyPI, Maven, etc.
• Sanctioned Mirror Declarations — forge migration and mirrors

(Further improvements await consensus: CRA Steward Declarations, informed by the Commission's July 2026 CRA application guidance; Platform Lock-in Declaration, seeking community input; External Metadata Source References, defining co-existence with peer metadata formats such as CNCF .project and OpenSSF security-insights.yml; and Lifecycle Status Declaration. See PROPOSAL.md for details.)

Companion specifications:

• Contribution Credit Registry API
• Registry Discovery Standard (/.well-known/publiccode-registry.json)
• Trust and Identity — trust models and entity identifiers shared across registries
• Usage Registry API
• Organization-Level Usage Declarations (.well-known/publiccode-usage.json)
• Project-Level Funding Declarations (.well-known/publiccode-funding.json)
• Assessment Registry API (for Sovereignty Checks and regional compliance assessments)

Policy layer and governance alignment:

• Procurement policies that prefer open source and use standardized criteria
• Selection frameworks based on metadata-backed evidence
• Legislative reference models (including Switzerland's EMBAG law)

Policy Primer (Optional)

For policy makers new to open source policy: Mirko Boehm, "How Open Source Coordinates: A Guide for Policy Makers" (SSRN, 2026): https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6303038

Trust Model in One Line

• Independent registries expose standardized data and declare trust models (verified-domain, signed-attestation, self-reported) so evidence consumers can choose risk-appropriate sources. See Design Principles.

Documents at a Glance

Reading Paths by Role

Pick the track that matches your available time:

• Quick path: 10-20 minutes for orientation and decisions
• Deep dive: 35-120 minutes for implementation and policy detail

1. Procurement Professional

You're evaluating whether open source is right for your organization.

Quick path (12-15 min):

• PITCH.md → Procurement Office
• PROCUREMENT_EVIDENCE_REQUIREMENTS.md — the buyer-side requirements, written for practitioner review; your corrections and additions are the input this project most needs
• RESEARCH.md → publiccode.yml strengths
• PROPOSAL.md → Policy Context

Deep dive (40 min):

• Add PROPOSAL.md → Design Principles and Faceted Classification
• Use GLOSSARY.md for unfamiliar terms

2. Open Source Project Maintainer

You're considering whether to adopt publiccode.yml metadata.

Quick path (15-20 min):

• PITCH.md → Open Source Project/Maintainer
• PROPOSAL.md → Full Example
• ROADMAP.md → Phase 1

Deep dive (50 min):

• Add RESEARCH.md → publiccode.yml
• Add PROPOSAL.md → Design Principles
• Use GLOSSARY.md as needed

3. Vendor / Service Provider

You deliver expertise around specific open source projects.

Quick path (12-15 min):

• PITCH.md → Vendor/Service Provider
• PROPOSAL.md → Vendor Contribution Credit System Discovery
• ROADMAP.md → Phase 3

Deep dive (35 min):

• Add RESEARCH.md → publiccode.yml for background
• Use GLOSSARY.md for terminology

4. Policy Maker / Legislator

You're drafting open source procurement requirements or digital sovereignty mandates.

Quick path (20-25 min):

• EU_POLICY_CONTEXT.md
• PITCH.md → Policy Maker/Legislator
• PROPOSAL.md → Policy Context

Deep dive (70 min):

• Add RESEARCH.md → Digital Sovereignty Score Initiatives
• Add ROADMAP.md (focus on Phases 0, 2, 3, and 5)
• Use GLOSSARY.md as needed

5. Researcher / Standards Specialist

You're studying open source governance, metadata standards, or supply chain transparency.

Quick path (20-30 min):

• RESEARCH.md
• PROPOSAL.md
• RISK_ANALYSIS.md

Deep dive (120 min):

• Add METHODOLOGY.md first for provenance and process
• Use GLOSSARY.md for terminology normalization

6. Funder / Grant Manager

You allocate money to open source infrastructure and want to understand this proposal.

Quick path (15-20 min):

• PITCH.md → Federal Authority/Funder
• RISK_ANALYSIS.md → Critical Risks
• ROADMAP.md

Deep dive (50 min):

• Add RESEARCH.md → publiccode.yml
• Use GLOSSARY.md as needed

7. Software Catalog Operator

You run openCode.de, Developers Italia, or another registry/index.

Quick path (15-20 min):

• PITCH.md → Software Catalog/Crawler
• PROPOSAL.md → Registry Discovery Standard
• ROADMAP.md → Phase 4
• TOOLING.md → Tooling gaps

Deep dive (65 min):

• Add RESEARCH.md → Federated Architecture
• Add PROPOSAL.md (focus on Supply Chain References and Deprecate usedBy)
• Add TOOLING.md for what to build or extend
• Use GLOSSARY.md as needed

Tips for Reading

Terminology tip: If you see an acronym or unfamiliar term, check GLOSSARY.md first. It's designed to make everything accessible.

Links: Click links to jump between sections. Most documents cross-reference each other so you can read non-linearly.

Tables: Scan tables first—they often contain the key insights in compact form.

Technical sections: PROPOSAL.md has YAML examples. You don't need to understand YAML syntax; read the descriptions alongside the code blocks.

Scope boundaries: Each document tries to be honest about what it does not cover. If something seems missing, check the Risk Analysis and Methodology sections for why.

How to Contribute Feedback

This project is open for feedback and collaboration. Key places to raise ideas:

• On the proposal: See ROADMAP.md → Phase 0 → Actions for governance processes
• On research methodology: See METHODOLOGY.md → Limitations
• On specific risks: See RISK_ANALYSIS.md — if you see a missing risk, that's valuable input
• On implementation details: See ROADMAP.md — phases are sequenced but not set in stone

Project Status

• ✅ Completed: Initial comparative analysis (RESEARCH.md), proposal (PROPOSAL.md), pitches (PITCH.md), risk analysis (RISK_ANALYSIS.md)
• ✅ Completed: Possible roadmap and initial coalition mapping (ROADMAP.md)
• ✅ Completed: Supporting reference material — glossary (GLOSSARY.md), ecosystem architecture and data flow (DATA_FLOW.md), EU policy context (EU_POLICY_CONTEXT.md), tooling survey (TOOLING.md), research methodology (METHODOLOGY.md), future work (FUTURE_WORK.md), and peer-format crosswalks (crosswalks/)
• 🔄 Current: Community review for completeness and accuracy; early outreach and pilot preparation underway (engagement, procurement-pilot, and conference-submission drafts in pilots/)
• 🔄 Next: Find initial allies and open governance discussions (Phase 0 of ROADMAP.md)

License: CC-BY-SA 4.0 (see LICENSE file)