https://github.com/open-operational-state/status-tooling
Reference tools, validators, and utilities for working with Open Operational State data and integrations.
https://github.com/open-operational-state/status-tooling
api-tools automation cli developer-tools integration observability operational-state sdk tooling validation
Last synced: 16 days ago
JSON representation
Reference tools, validators, and utilities for working with Open Operational State data and integrations.
- Host: GitHub
- URL: https://github.com/open-operational-state/status-tooling
- Owner: open-operational-state
- License: apache-2.0
- Created: 2026-04-02T17:47:41.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-04-03T02:03:21.000Z (16 days ago)
- Last Synced: 2026-04-03T13:22:39.187Z (16 days ago)
- Topics: api-tools, automation, cli, developer-tools, integration, observability, operational-state, sdk, tooling, validation
- Language: TypeScript
- Homepage:
- Size: 68.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Status Tooling
Vendor-neutral reference tooling for the [Open Operational State](https://github.com/open-operational-state) standard.
[](https://www.npmjs.com/org/open-operational-state)
[](LICENSE)
## Install
```bash
npm install @open-operational-state/core @open-operational-state/emitter
```
```js
import { normalizeSnapshot } from '@open-operational-state/core';
import { emitHealthResponse, suggestHttpStatus } from '@open-operational-state/emitter';
app.get( '/health', ( req, res ) => {
const snapshot = normalizeSnapshot( {
condition: 'operational',
profiles: [ 'health' ],
subject: { id: 'my-api' },
timing: { observed: new Date().toISOString() },
} );
res.status( suggestHttpStatus( snapshot ) ).json( emitHealthResponse( snapshot ) );
} );
```
Or parse any existing health endpoint into the common model:
```bash
npx @open-operational-state/validator probe https://your-api.com/health
```
## Overview
This monorepo is the source for the `@open-operational-state` npm packages — a complete toolkit for parsing, emitting, validating, and discovering operational-state resources. All packages are published to npm, written in TypeScript, and use ESM.
## Packages
| Package | Purpose | Version |
|---|---|---|
| [`@open-operational-state/types`](packages/types/) | Canonical TypeScript types for the core model | 0.1.1 |
| [`@open-operational-state/core`](packages/core/) | Core model logic, normalization, validation | 0.1.1 |
| [`@open-operational-state/parser`](packages/parser/) | Response parsers and format adapters | 0.1.1 |
| [`@open-operational-state/emitter`](packages/emitter/) | Wire format emitters | 0.1.1 |
| [`@open-operational-state/validator`](packages/validator/) | Conformance validation and `oos` CLI | 0.1.1 |
| [`@open-operational-state/discovery`](packages/discovery/) | Discovery client (Link headers, well-known) | 0.1.1 |
## Development
```bash
# Install dependencies
bun install
# Build all packages
bun run build
# Run all tests
bun run test
# Probe a live endpoint
node packages/validator/dist/cli.js probe https://api.example.com/health
# Run conformance fixtures
node packages/validator/dist/cli.js fixtures ../status-conformance/fixtures/core --format=table
```
## CLI
The `oos` CLI is included in the validator package:
```bash
oos validate # Validate a JSON file against conformance levels
oos probe # Fetch a URL, auto-detect format, parse to core model
oos fixtures # Run all conformance fixtures in a directory
oos inspect # Parse a JSON file, pretty-print core model
```
See the [validator README](packages/validator/README.md) for full CLI documentation.
## Examples
See [examples/](examples/) for real-world usage patterns — Express, Hono, `safeParse()`, discovery, and component aggregation in ~10 lines each.
## Supported Formats
| Format | Content-Type | Adapter |
|---|---|---|
| OOS Native (health) | `application/health+json` | `parseHealthResponse` |
| OOS Native (status) | `application/status+json` | `parseHealthResponse` |
| Health Check Draft | `application/json` | `parseHealthCheckDraft` |
| Spring Boot Actuator | `application/json` | `parseSpringBoot` |
| Plain HTTP | any | `parsePlainHttp` |
Format detection is automatic — the `parse()` function inspects content-type and body structure to select the correct adapter.
## Architecture
This tooling implements the six-layer architecture defined in the [status-spec](https://github.com/open-operational-state/status-spec/blob/main/ARCHITECTURE.md):
- **`types`** — TypeScript interfaces for the core model (Layer 1)
- **`core`** — normalization and manipulation of core model instances
- **`parser`** — deserialization from wire formats to core model (Layers 3–4)
- **`emitter`** — serialization from core model to wire formats (Layer 3)
- **`validator`** — conformance validation against profiles and serializations (cross-cutting)
- **`discovery`** — discovery client for locating operational-state resources (Layer 5)
## Dependency Graph
```
types ← core ← parser
← emitter
← validator ← parser
discovery ← types (only)
```
- `core` depends **only** on `types`
- `parser` and `emitter` depend on `core` + `types`
- `validator` depends on `types` + `core` + `parser`
- `discovery` depends **only** on `types`
## Testing
Tests are fixture-driven where applicable. Conformance fixtures are read directly from the sibling `status-conformance` repository:
```bash
# Run all tests
bun run test
# Run tests for a specific package
bun run --filter '@open-operational-state/parser' test
```
### Round-Trip Invariants
The emitter package includes golden round-trip tests that enforce:
```
parse → normalize → emit → parse → normalize
```
No semantic drift, no loss of required data, no illegal state introduced.
## Related Repositories
| Repository | Purpose |
|---|---|
| [status-spec](https://github.com/open-operational-state/status-spec) | Technical specification (what tooling implements) |
| [status-conformance](https://github.com/open-operational-state/status-conformance) | Conformance fixtures and test taxonomy |
| [governance](https://github.com/open-operational-state/governance) | Charter, terminology, roadmap |
## Project Rules
See [PROJECT_RULES.md](PROJECT_RULES.md) for repo-specific constraints. Key points:
- **ESM only** — no CommonJS
- **Bun** package manager and test runner
- **Node.js + TypeScript** — compiled output targets ES2022
- All behavior must be represented in fixtures or spec
## License
Licensed under [Apache 2.0](LICENSE).