This guide helps you navigate the documentation based on your role and what you need to learn.
What is this project?
This project evaluates metadata standards for open source software and proposes improvements to publiccode.yml as well as concrete standards for decentralized data collection (registry APIs, discovery mechanisms, usage declarations). This data will enable procurement offices, funders, and security teams to discover, evaluate, and confidently adopt open source projects—and to identify and fund critical open source infrastructure and maintenance in a sustainable manner.
Why this matters: The proposal pairs technical standards (metadata, APIs, registries) with a strategic push for public procurement policies that prefer open source. This creates a positive feedback loop:
→ procurement policies create demand for standardized project metadata → projects and vendors adopt the extended standard → procurement offices get better visibility and evaluation tools → more confident open source adoption
Who's it for?
- Procurement professionals considering open source adoption
- Open source project maintainers seeking visibility with public sector buyers
- Policy makers designing procurement requirements or digital sovereignty mandates
- Vendors/service providers wanting to demonstrate expertise
- Researchers studying open source governance and digital sovereignty
- Funders allocating resources to critical open source infrastructure
What's proposed?
A comprehensive ecosystem of standards and registries built around publiccode.yml:
Proposed Improvements to publiccode.yml:
- Faceted classification (better discovery across multiple dimensions)
- Supply chain references (security assessments, SBOMs, policies)
- Credit system discovery (vendor contribution tracking)
- Usage registries (deployment transparency)
- Temporal field deprecation (cleaner, more trustworthy data)
Companion Specifications:
- Credit Registry API — Standardized interface for how registries expose vendor/contributor credit data
- Usage Registry API — Standardized interface for how registries expose software adoption data
- Registry Discovery Standard — How registry operators advertise their existence and capabilities so crawlers can discover them automatically (
/.well-known/publiccode-registry.json) - Organization-Level Usage Declarations — Standard format for organizations to declare what software they deploy (
.well-known/publiccode-usage.json)
Policy Layer:
- Public procurement policies (modeled on "Public Money, Public Code") that prefer open source and require standardized evaluation criteria
- Procurement selection frameworks that use publiccode.yml metadata as evidence for vendor expertise, supply chain security, and community health
- Legislative models and best practices (including Switzerland's EMBAG law as a reference) for mandating open source in government
Decentralized Trust Networks:
- No central authority controls the data. Registries operate independently in different jurisdictions and sectors, but use standard APIs and discovery mechanisms.
- Trust is verifiable, not assumed. Each registry declares its trust model (
verified-domain,signed-attestation,self-reported) so consumers can choose data sources matching their risk tolerance. - Data drives decisions, not politics. By making vendor contributions, supply chain security, and software adoption transparently measurable, procurement and policy become evidence-based rather than relationship-based.
Together, these enable a self-reinforcing, decentralized ecosystem where procurement demand drives adoption of open source standards, verified through trust networks, which in turn strengthens the vendors and projects within those ecosystems—all while maintaining independence and preventing gatekeeping.
| Document | Purpose | Length | Best for | Start here if… |
|---|---|---|---|---|
| GLOSSARY.md | Key terms explained | ~20 min | Everyone | You encounter unfamiliar terms or acronyms |
| RESEARCH.md | Comparative analysis of 5 standards | ~30 min | Researchers, policy makers, infrastructure decision-makers | You want to understand why publiccode.yml and not something else |
| DATA_FLOW.md | Ecosystem architecture and data flow diagram | ~15 min | Architects, system designers, visual learners | You want to see how the ecosystem connects together |
| PITCH.md | Why each actor benefits | 10 min | Practitioners in each role | You want to know "what's in it for me?" |
| PROPOSAL.md | Detailed technical spec including 5 publiccode.yml improvements plus companion standards (registry APIs, discovery, organization declarations) | ~60 min | Maintainers, spec authors, technical implementers | You want the concrete technical specification and full ecosystem design |
| RISK_ANALYSIS.md | Identified risks and mitigations | ~20 min | Risk managers, decision-makers | You need to understand what could go wrong |
| ROADMAP.md | Phased implementation plan | ~20 min | Project managers, funders, coalition builders | You're thinking about how to make this real |
| METHODOLOGY.md | Research process documented | ~40 min | Meta/research/reproducibility-focused readers | You want to understand how conclusions were reached |
| LICENSE | CC-BY-SA 4.0 | 2 min | Everyone | You need reuse permissions |
You're evaluating whether open source is right for your organization.
Start here:
- PITCH.md → Procurement Office (2 min) — Why this matters to you
- RESEARCH.md → publiccode.yml strengths (10 min) — What you're getting
- PROPOSAL.md → Design Principles + Improvement 1 (15 min) — How discovery improves
- PROPOSAL.md → Policy Context (10 min) — How this connects to procurement frameworks
- GLOSSARY.md — As needed for unfamiliar terms
Expected time: 40 minutes
You're considering whether to adopt publiccode.yml metadata.
Start here:
- PITCH.md → OSS Project/Maintainer (2 min) — What you get
- RESEARCH.md → publiccode.yml (15 min) — How publiccode.yml works
- PROPOSAL.md → Design Principles (5 min) — Philosophy
- PROPOSAL.md → Full Example (15 min) — See what it looks like
- ROADMAP.md → Phase 1 (5 min) — Earliest opportunities
- GLOSSARY.md — As needed
Expected time: 50 minutes
You deliver expertise around specific open source projects.
Start here:
- PITCH.md → Vendor/Service Provider (2 min) — Why it's good for business
- RESEARCH.md → publiccode.yml → No vendor/contributor credit system (3 min) — The problem being solved
- PROPOSAL.md → Improvement 3: Vendor Credit System Discovery (15 min) — How it works
- ROADMAP.md → Phase 3: Credit System Pilot with Drupal (10 min) — Timeline
- GLOSSARY.md — As needed
Expected time: 35 minutes
You're drafting open source procurement requirements or digital sovereignty mandates.
Start here:
- PITCH.md → Policy Maker/Legislator (2 min) — Policy opportunities
- PROPOSAL.md → Policy Context (15 min) — Connection to legislation
- RESEARCH.md → Other Relevant Standards: Digital Sovereignty Score Initiatives (10 min) — Policy landscape
- ROADMAP.md → Phases 0, 2, 3, 5 (20 min) — How this would be adopted
- GLOSSARY.md — As needed
Expected time: 50 minutes
You're studying open source governance, metadata standards, or supply chain transparency.
Start here:
- METHODOLOGY.md (40 min) — How conclusions were reached
- RESEARCH.md (30 min) — Comparative analysis of standards
- PROPOSAL.md (30 min) — Design decisions
- RISK_ANALYSIS.md (15 min) — Risk landscape
- GLOSSARY.md — As needed
Expected time: 120 minutes
You allocate money to open source infrastructure and want to understand this proposal.
Start here:
- PITCH.md → Federal Authority/Funder (2 min) — Funding decisions
- RESEARCH.md → publiccode.yml (15 min) — The infrastructure
- RISK_ANALYSIS.md → Critical Risks (10 min) — Where funding is most needed
- ROADMAP.md (20 min) — Phases and milestones for funding decisions
- GLOSSARY.md — As needed
Expected time: 50 minutes
You run openCode.de, Developers Italia, or another registry/index.
Start here:
- PITCH.md → Software Catalog/Crawler (2 min) — Why it matters to you
- RESEARCH.md → Federated Architecture (5 min) — System design
- PROPOSAL.md → Full Design | Improvement 2 | Improvement 4 (30 min) — What data you'd consume
- PROPOSAL.md → Registry Discovery Standard (15 min) — How registries interact
- ROADMAP.md → Phase 4 (10 min) — Timeline
- GLOSSARY.md — As needed
Expected time: 65 minutes
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.
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
- ✅ 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)
- 🔄 Current: Community review for completeness and accuracy
- 🔄 Next: Find initial allies and open governance discussions (Phase 0 of ROADMAP.md)
License: CC-BY-SA 4.0 (see LICENSE file)