The technical specification for Open Operational State — a vendor-neutral standard for machine-readable operational state of web services.
Today, every framework and platform exposes operational state differently — Spring Boot, Kubernetes, custom health endpoints — with no shared model for what the values mean. This repository defines how web services communicate their operational condition — health, readiness, liveness, status — in a machine-readable, interoperable way. It provides a unifying semantic model for health check endpoints, readiness and liveness probes, and service status APIs, built around a six-layer extensible architecture.
Start here:
- ARCHITECTURE.md — the six-layer architecture that structures the entire standard
- NON_GOALS.md — what this standard explicitly is not
- PRIOR-ART.md — influences and compatibility targets
Then explore the specification documents:
| Document | Layer | Description |
|---|---|---|
| spec/core-model.md | Core Model | Stable, transport-agnostic semantics |
| spec/condition-vocabularies.md | Core Model | Condition values per profile with ecosystem mappings |
| spec/profiles.md | Profiles | Domain-specific specializations (Liveness, Readiness, Health, Status) |
| spec/serializations.md | Serializations | Wire-level representation overview |
| spec/serializations/health-response.md | Serializations | application/health+json format |
| spec/serializations/service-status.md | Serializations | application/status+json format |
| spec/serializations/http-status-only.md | Serializations | Minimal HTTP-only serialization |
| spec/adapters.md | Adapters | Adapter specification framework |
| spec/adapters/plain-http.md | Adapters | Plain HTTP status code adapter |
| spec/adapters/health-check-draft.md | Adapters | draft-inadarei health check adapter |
| spec/discovery.md | Discovery | Locating operational-state resources |
| spec/capabilities.md | Capabilities | Negotiation and feature advertisement |
| spec/security-considerations.md | Cross-cutting | Exposure guidance and security considerations |
| Directory | Purpose |
|---|---|
| terminology/ | Applied spec-level usage and context (authoritative glossary is in governance) |
| design-notes/ | Design rationale and working notes |
| examples/ | Example payloads and scenarios |
Open Operational State builds on prior work in machine-readable service health and status, including:
- Health Check Response Format for HTTP APIs (
draft-inadarei-api-health-check) — a widely adopted format for HTTP API health checks - Service Status Resource Format for Web Services (
draft-dallariva-web-service-status-json) — a proposal for richer, structured service status resources
These approaches represent different models of expressing operational state. Concepts from both are commonly seen in production systems, such as health endpoints exposed by frameworks like Spring Boot Actuator and readiness/liveness probes in Kubernetes. This project provides a unifying architecture that allows these formats to be interpreted through a common model. See PRIOR-ART.md for detailed analysis.
| Repository | Purpose |
|---|---|
| governance | Charter, governance model, authoritative glossary |
| status-conformance | Conformance definitions and test taxonomy |
| status-tooling-js | Vendor-neutral reference tooling (JavaScript) |
See PROJECT_RULES.md for repo-specific constraints. This repository is markdown only — no code.