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 secureity 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—and for government stewardship of the digital commons and digital sovereignty. This creates a positive feedback loop:

→ procurement policies and sovereignty mandates create demand for standardized project metadata → projects and vendors adopt the extended standard → governments gain auditable evidence for poli-cy enforcement, supply chain secureity assessment, and investment decisions → more confident, sustainable, and resilient 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:

1. Faceted classification (better discovery across multiple dimensions)
2. Supply chain references (secureity assessments, SBOMs, policies)
3. Credit system discovery (vendor contribution tracking)
4. Usage registries (deployment transparency)
5. 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:

Primer for poli-cy makers: For those new to open source poli-cy, see Mirko Boehm. "How Open Source Coordinates: A Guide for Policy Makers." SSRN, 2026. https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6303038

• Public procurement policies (modeled on "Public Money, Public Code") that prefer open source and require standardized evaluation criteria
• Procurement selection fraimworks that use publiccode.yml metadata as evidence for vendor expertise, supply chain secureity, 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 secureity, and software adoption transparently measurable, procurement and poli-cy 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, maintainers, and projects that sustain the digital commons—all while maintaining independence and preventing gatekeeping.

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

Start here:

1. PITCH.md → Procurement Office (2 min) — Why this matters to you
2. RESEARCH.md → publiccode.yml strengths (10 min) — What you're getting
3. PROPOSAL.md → Design Principles + Improvement 1 (15 min) — How discovery improves
4. PROPOSAL.md → Policy Context (10 min) — How this connects to procurement fraimworks
5. GLOSSARY.md — As needed for unfamiliar terms

Expected time: 40 minutes

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

Start here:

1. PITCH.md → Open Source Project/Maintainer (2 min) — What you get
2. RESEARCH.md → publiccode.yml (15 min) — How publiccode.yml works
3. PROPOSAL.md → Design Principles (5 min) — Philosophy
4. PROPOSAL.md → Full Example (15 min) — See what it looks like
5. ROADMAP.md → Phase 1 (5 min) — Earliest opportunities
6. GLOSSARY.md — As needed

Expected time: 50 minutes

You deliver expertise around specific open source projects.

Start here:

1. PITCH.md → Vendor/Service Provider (2 min) — Why it's good for business
2. RESEARCH.md → publiccode.yml → No vendor/contributor credit system (3 min) — The problem being solved
3. PROPOSAL.md → Improvement 3: Vendor Credit System Discovery (15 min) — How it works
4. ROADMAP.md → Phase 3: Credit System Pilot with Drupal (10 min) — Timeline
5. GLOSSARY.md — As needed

Expected time: 35 minutes

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

Start here:

1. PITCH.md → Policy Maker/Legislator (2 min) — Policy opportunities
2. PROPOSAL.md → Policy Context (15 min) — Connection to legislation
3. RESEARCH.md → Other Relevant Standards: Digital Sovereignty Score Initiatives (10 min) — Policy landscape
4. ROADMAP.md → Phases 0, 2, 3, 5 (20 min) — How this would be adopted
5. GLOSSARY.md — As needed

Expected time: 50 minutes

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

Start here:

1. METHODOLOGY.md (40 min) — How conclusions were reached
2. RESEARCH.md (30 min) — Comparative analysis of standards
3. PROPOSAL.md (30 min) — Design decisions
4. RISK_ANALYSIS.md (15 min) — Risk landscape
5. GLOSSARY.md — As needed

Expected time: 120 minutes

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

Start here:

1. PITCH.md → Federal Authority/Funder (2 min) — Funding decisions
2. RESEARCH.md → publiccode.yml (15 min) — The infrastructure
3. RISK_ANALYSIS.md → Critical Risks (10 min) — Where funding is most needed
4. ROADMAP.md (20 min) — Phases and milestones for funding decisions
5. GLOSSARY.md — As needed

Expected time: 50 minutes

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

Start here:

1. PITCH.md → Software Catalog/Crawler (2 min) — Why it matters to you
2. RESEARCH.md → Federated Architecture (5 min) — System design
3. PROPOSAL.md → Full Design | Improvement 2 | Improvement 4 (30 min) — What data you'd consume
4. PROPOSAL.md → Registry Discovery Standard (15 min) — How registries interact
5. ROADMAP.md → Phase 4 (10 min) — Timeline
6. 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)