Handbook

A practical guide to adopting PublicSchema through vocabulary alignment, system mapping, new system design, data exchanges, credentials, validation, and governance.

End-to-end Worked example See one package from scope to release. Lightest path Adopt vocabularies Align local codes first. Most common path Map existing systems Connect platforms without redesigning them. Greenfield path Design a new system Build compatibility from the start. Buying path Procurement acceptance Turn interoperability into evidence. Toolkit Templates Copy practical tables and checklists.

Start here

Introduction

What PublicSchema is, who it is for, and how the handbook is organized around practical adoption work.

Choose Your Path

A decision guide for teams adopting vocabularies, mapping existing systems, designing new systems, issuing credentials, or governing extensions.

Use Cases

Common public service delivery scenarios and the PublicSchema artifacts each one needs.

Worked Example: Mapping a Program Export

A small end-to-end example that follows cash transfer reporting from source systems to mappings, validation, publication, and governance.

Adoption paths

Adopt Vocabularies

The lightest adoption path: align local codes to canonical PublicSchema vocabularies without changing the internal data model.

Map Existing Systems

A complete mapping lifecycle for aligning existing platforms, schemas, APIs, and exports to PublicSchema.

Design a New System

How to use PublicSchema when designing a new registry, MIS, case management system, API, or procurement specification.

Procurement and Vendor Acceptance

Tender language, vendor evidence, acceptance levels, and validation checks for buying PublicSchema-compatible systems.

Implementation

Publish Exchanges and APIs

How to expose PublicSchema-compatible data through APIs, events, files, analytics pipelines, and canonical exports.

Issue Credentials

How to use PublicSchema with JSON-LD contexts, JSON Schemas, SD-JWT Verifiable Credentials, and selective disclosure.

Package and Validate Your Work

What a complete adoption package should contain, how to validate it, and how to make it maintainable.

Templates and Checklists

Copyable tables and review checklists for mappings, crosswalks, packages, validation reports, privacy notes, and releases.

Privacy and Data Protection

Practical data minimization, identifier, sample data, credential, and package review guidance for sensitive service delivery data.

Governance and reference

Extend PublicSchema

When to add local concepts, properties, or vocabulary values, and how to keep extensions interoperable.

Governance, Versioning, and Methodology

How PublicSchema evolves, how maturity and evidence work, and how implementation teams should govern local adoption.

Glossary

Shared terms used throughout the handbook, from concepts and properties to mappings, profiles, shapes, and credentials.

Technical Documentation

Domain migration

Canonical domains, moved terms and migration of existing references.

FHIR registry integration

Connecting health facilities and registry records to FHIR resources.

Facility roles

Distinguishing facilities, their operators and their service delivery roles.

Relationship date conversion

Converting inclusive source validity dates on relationships and periods of responsibility.

Public services

Public services, applications, decisions, appeals and organizational succession.

Ownership and education delivery

Ownership interests, legal arrangements, education programs, offerings and awarded qualifications.