Tools

The OJS ecosystem includes tools for operations, development, validation, testing, and code generation.

CLI

Repository: ojs-cli/ Language: Go

The OJS CLI (ojs) is a command-line tool for managing jobs, queues, workers, cron schedules, and workflows against any OJS-compliant backend.

Installation

go install github.com/openjobspec/ojs-cli@latest

Commands

Command	Description
ojs enqueue	Enqueue a job
ojs status <id>	Get job status
ojs cancel <id>	Cancel a job
ojs queues	List queues and stats
ojs queues pause <name>	Pause a queue
ojs queues resume <name>	Resume a queue
ojs workers	List active workers
ojs workers quiet <id>	Quiet a worker
ojs cron list	List cron schedules
ojs cron register	Register a cron job
ojs workflows	List workflows
ojs dead-letter	List dead letter jobs
ojs dead-letter retry <id>	Retry a dead letter job
ojs monitor	Live monitoring dashboard

Usage

# Enqueue a job
ojs enqueue --type email.send --args '["user@example.com","Welcome!"]'

# Check status
ojs status 01961234-5678-7abc-def0-123456789abc

# Monitor live
ojs monitor --url http://localhost:8080

# Output as JSON
ojs queues --format json

Configuration

Environment variable	Default	Description
OJS_URL	http://localhost:8080	OJS server URL
OJS_FORMAT	table	Output format (table or json)

---

Admin UI

Repository: ojs-admin-ui/ Language: TypeScript (React 19 + Vite)

A universal web dashboard for managing any OJS backend. The Admin UI auto-discovers backend capabilities via the OJS manifest and adapts its interface accordingly.

Features

• Dashboard — Real-time job statistics, throughput charts, queue depth gauges
• Queues — View, pause, resume, purge queues with live stats
• Jobs — Search, filter, inspect, cancel, retry individual jobs
• Workers — Monitor active workers, send quiet/terminate signals
• Dead Letter — Browse, retry, delete dead letter jobs
• Dark Mode — System-aware theme with manual toggle
• Auto-refresh — Configurable polling interval for live updates

Deployment

The Admin UI can be served as static files by any OJS backend at /ojs/admin, or run standalone:

cd ojs-admin-ui
npm install
npm run dev         # Development server
npm run build       # Production build to dist/

Backends can embed the UI:

import "github.com/openjobspec/ojs-admin-ui"

mountOJSAdmin(element, { baseUrl: "", basename: "/ojs/admin" })

---

Playground

Repository: ojs-playground/ URL: play.openjobspec.org

An interactive development environment for exploring OJS without any local setup.

Browser mode

The playground runs entirely in the browser and includes:

• Schema editor — Monaco-based editor with OJS JSON Schema validation
• State machine visualization — Interactive job lifecycle diagram (React Flow)
• Retry timeline — Visual retry backoff calculator (Recharts)
• Code generation — Generate SDK code from job definitions (Go, TypeScript, Python, Java, Rust, Ruby)
• Templates — Pre-built examples for common patterns

Local mode

For testing against real backends:

cd ojs-playground
docker compose up

Local mode starts a Go backend and executes jobs with real state transitions, streamed to the browser via SSE.

---

Conformance test suite

Repository: ojs-conformance/ Language: Go (test runner), JSON (test definitions)

The conformance test suite validates that an OJS backend correctly implements the specification. Tests are organized into five levels, each a superset of the previous.

Conformance levels

Level	Name	What it tests
0	Core	Enqueue, fetch, ack, nack, health, queue listing, schemas
1	Lifecycle	Job info, cancel, dead letter, heartbeat, state transitions
2	Scheduling	Delayed jobs (scheduled_at), cron job registration, timezone handling
3	Workflows	Chain, group, and batch workflow primitives
4	Full	Batch enqueue, unique jobs, priority ordering, queue pause/resume, queue stats

Running conformance tests

The test runner makes HTTP requests against a running OJS server. Set OJS_URL to point to your server.

Against the Redis backend:

cd ojs-backend-redis
make docker-up                  # Start the server
make conformance                # Run all levels
make conformance-level-0        # Run just Level 0
make conformance-level-1        # Run just Level 1

Against any OJS server:

cd ojs-conformance
OJS_URL=http://localhost:8080 go test ./runner/http/ -v

Test structure

Test definitions are JSON files in ojs-conformance/. Each test specifies:

• An HTTP request (method, path, body)
• Expected response (status code, body fields, timing constraints)
• Pre-conditions and post-conditions

Tests are language-agnostic. The Go test runner executes them, but the test definitions could be used by a runner in any language.

Using conformance to build a backend

If you are building a new OJS backend, start with Level 0 and work up. The conformance tests are the definitive guide to expected behavior. See Implement a Backend for a walkthrough.

---

JSON Schema package

Repository: ojs-json-schema/ Language: Node.js

JSON Schema (draft 2020-12) definitions for all OJS data structures.

Schemas included

Schema	File	Description
Job Envelope	job.schema.json	Complete job envelope validation
Retry Policy	retry-policy.schema.json	Retry configuration
Unique Policy	unique-policy.schema.json	Deduplication configuration
Error	error.schema.json	API error response format
Event	event.schema.json	Lifecycle event format
Batch Request	batch-request.schema.json	Batch enqueue request

Usage

pnpm add @openjobspec/json-schema

import jobSchema from '@openjobspec/json-schema/job.schema.json';
import Ajv from 'ajv';

const ajv = new Ajv();
const validate = ajv.compile(jobSchema);
const valid = validate(myJobEnvelope);

See JSON Schemas Reference for the full schema definitions.

---

Protobuf definitions

Repository: ojs-proto/ Language: Protobuf (with Go and TypeScript codegen)

gRPC service definitions for the OJS gRPC protocol binding. Uses Buf for linting and code generation.

Contents

• ojs/v1/job.proto - Job envelope message types
• ojs/v1/service.proto - gRPC service definitions
• ojs/v1/error.proto - Error response types
• ojs/v1/workflow.proto - Workflow message types

Commands

buf lint          # Lint proto files
buf generate      # Generate Go + TypeScript code

Generated code

Buf generates:

• Go: Full gRPC client and server stubs with protobuf marshaling
• TypeScript: Type definitions and client stubs for use with gRPC-web or Connect

---

Development workflow

Setting up a local development environment

1. Start a backend:

   cd ojs-backend-redis
   make docker-up

2. Verify health:

   curl http://localhost:8080/ojs/v1/health

3. Check conformance:

   make conformance

4. Run SDK tests:

   # JavaScript
   cd ojs-js-sdk && pnpm test
   
   # Go
   cd ojs-go-sdk && go test ./...
   
   # Python
   cd ojs-python-sdk && pytest

Testing against different backends

The beauty of OJS is that you can swap backends without changing your application code. To test against PostgreSQL instead of Redis:

cd ojs-backend-postgres
make docker-up
# Same SDK code, same tests, different backend

Useful curl commands

# Health check
curl http://localhost:8080/ojs/v1/health

# Conformance manifest
curl http://localhost:8080/ojs/manifest

# Enqueue a job
curl -X POST http://localhost:8080/ojs/v1/jobs \
  -H "Content-Type: application/openjobspec+json" \
  -d '{"type":"test.hello","args":["world"]}'

# List queues
curl http://localhost:8080/ojs/v1/queues

# Get a job
curl http://localhost:8080/ojs/v1/jobs/<job-id>

# List dead letter jobs
curl http://localhost:8080/ojs/v1/dead-letter