About PublicSchema
What it provides, where it sits, and where it's going.
What PublicSchema provides
PublicSchema is an open reference model for public service data. The homepage covers the basics; this page goes deeper.
It provides:
- Concepts: semantic entities (Person, Enrollment, Payment, and others) with definitions written for policy practitioners, not developers.
- Properties: named, typed fields that apply to one or more concepts. Defined once and reused, keeping definitions consistent across domains.
- Vocabularies: controlled value sets. Where international standards exist (ISO, FHIR, UN), we reference them. Where they do not, we define a canonical set with mappings to how specific systems encode the same values.
- Credential schemas: JSON-LD contexts and structures for issuing concept data as Verifiable Credentials, using SD-JWT VC for selective disclosure of sensitive personal data.
Every element gets a stable URI. Everything is optional. Countries and programs adopt what they need and extend what they don't.
Design principles
Definitions carry semantic weight, not just structure. Properties are reusable across concepts. Time-boundedness is first-class. International standards are referenced, never reinvented. Nothing is mandatory.
See Design Principles for the full rationale behind each of these choices.
Where PublicSchema sits
PublicSchema complements existing efforts rather than competing with them. It sits at the delivery data layer: between identity standards, API interoperability, and trust infrastructure.
| Layer | What exists | What PublicSchema adds |
|---|---|---|
| Trust and transport | W3C VC, OpenID4VC, EBSI | Domain vocabulary inside credentials |
| Identity attributes | EU Core Person Vocabulary | Delivery lifecycle data beyond name/birth/citizenship |
| Service catalogues | CPSV-AP, HSDS/Open Referral | Who receives what, not what services exist |
| API interoperability | DCI, GovStack | Shared semantics behind the API contracts |
| Statistical measurement | ILO/World Bank ASPIRE | Data models for exchange, not just indicators |
| Delivery lifecycle | Nothing | This is the gap |
DCI is the closest initiative: it defines how data flows between social protection systems; PublicSchema defines what the data means. GovStack defines building blocks for digital government; PublicSchema is the shared data model those blocks implicitly need. FHIR is the health sector equivalent; we take inspiration from its approach but target public services broadly.
See Related Standards for a detailed comparison.
Scope
PublicSchema provides concepts and vocabularies shared across public service delivery: identity, civil status, household composition, location, payment, hazard events, and others. Two domain-specific layers are currently active: social protection (enrolment, entitlements, grievances, referrals) and civil registration (births, deaths, marriages, adoptions). Humanitarian assessment is extended through the AidOps schema, which vendors PublicSchema's foundations. Health and education domains are planned.
See the full list of concepts for current coverage.
The structure is the same across domains; only the concepts and vocabularies change.
How countries and programs adopt it
PublicSchema is a starting point, not a mandate. Countries and programs adopt the parts that apply to their context and extend the rest in their own namespace. The shared schema stays stable; local specificity is preserved.
- Adopt universal concepts as-is. Person, Household, Location, and other universal concepts rarely need local changes. Using them directly gives interoperability at no cost.
- Use vocabularies where they fit. ISO countries, currencies, and languages map cleanly to most systems. Where a domain vocabulary (enrollment status, benefit modality) does not cover a local code, add it in your namespace.
- Extend what's missing. Country-specific concepts (a national identifier, a specific case management record, a local benefit category) live in your namespace alongside PublicSchema terms.
- Propose upstream. When an extension turns out to be useful across countries, propose it for inclusion. The vocabulary grows through real-world adoption, not committee design.
See Extending PublicSchema for concrete patterns and examples.
How it's built
PublicSchema synthesizes a large body of prior work: literature on public service delivery, open-source systems (openIMIS, OpenSPP, OpenCRVS, MOSIP, SEMIC, GovStack), and international standards (ISO, FHIR, UN M49, DCI). AI tooling accelerates that analysis at scale; humans review every definition, mapping, and design decision, and each non-trivial architectural choice is captured as a public decision record. Concepts carry a maturity flag (draft, candidate, normative) so adopters see where we are confident and where community input is still open.
See Methodology for the full process.
Governance and roadmap
PublicSchema is open source and free to use. The project is stewarded by Jeremi Joslin, with decisions taken in public so contributors and adopters can see how the schema evolves.
Where we are now
Concepts, properties, and credential schemas are published with stable URIs. Vocabularies reference international standards (ISO, UN, FHIR) where they exist. Cross-system mappings cover identity (MOSIP), social protection (OpenSPP, openIMIS), civil registration (OpenCRVS), and health (DHIS2), alongside interoperability standards (DCI, FHIR, GovStack). The schema has not yet been validated against a production country deployment.
How decisions are made
- Every concept, property, and vocabulary value carries a maturity flag (draft, candidate, normative), so adopters see where we are confident and where input is still open.
- Non-trivial architectural decisions are captured as public Architecture Decision Records in the project repository.
- Contributions are welcome from domain experts, system implementers, and standards bodies.
How governance will evolve
The current setup enables fast iteration before adoption. As countries and programs take up the schema, governance will expand: first to an advisory group of contributors and domain experts, then to a formal multi-stakeholder structure when adoption commitments justify it.