Servus 1.0.0 — inline-only schemas, shared fragments, and a smaller surface

[sebscholl]

Why

One thesis: a service's behaviour should be readable from the file that implements it.

Servus had accumulated indirection that worked against that. Schemas could live in three places, two of them outside the service. Two helpers wrapped .call and diverted control flow on failure — one by throwing, one by raising — so the same operation had different calling conventions depending on where you stood. And the emits DSL's own documentation argued against a pattern it fully supported.

Under agentic engineering the cost of that indirection went up. Generated code is most reliable when the contract is stated where the work happens, not resolved reflectively from a constant name or a sibling file.

What changed

Schemas are inline-only. Constant-based (ARGUMENTS_SCHEMA) and mirror-directory JSON schemas are no longer resolved. Only the schema DSL.

Shared fragments replace the duplication that would cause. A registry (Servus::Schema) holds reusable fragments referenced by standard JSON Schema $ref:

Servus::Schema.register('core', { '$defs' => { 'amount' => { 'type' => 'integer' } } })

schema arguments: { properties: { fee: { '$ref' => '#/core/$defs/amount' } } }

Compilation is lazy, memoized, and triggered on first read — so validation, the test example builders, have_schema, and application code all see resolved refs. Lookups never return nil; an unregistered key raises, naming the key, the schema being compiled, the ref chain, and the nearest match. The registry is standalone, so an app can register contracts with no service behind them and emit the lot via compile_all as one JSON asset.

call! and run_service! are removed. Both read like ordinary method calls while hiding a non-local jump.

emits gained no syntax, but lost a bad instruction. Multiple events per trigger, each with its own payload, always worked — the DSL's @note just told people not to. Now documented.

Correctness fixes riding along

Each is the same failure class the release targets — something that looks declared but validates nothing:

• schema arguments: nil raised nothing and silently unvalidated the service. Now raises.
• Subclasses didn't inherit schemas.
• The validator cache was keyed by a namespace-derived path with the last segment dropped, so A::B::Service and A::B::Other shared a schema.
• emits skipped payload validation entirely when no Event class was registered — bypassing require_event_payload_schema on exactly the events with no schema.
• The gem never required deep_dup/pluralize from ActiveSupport; the test suite masked it, a non-Rails consumer would not have.
• The service generator ignored config.services_dir while the event and guard generators honoured theirs.

Notable findings

json-schema v5 does not support draft-07. It tops out at draft-06 and defaults to it — the docs claimed draft-04. A draft-07 $schema raises at any position, which is why the compiler strips $schema/$id from spliced fragments.

SimpleCov (added here, opt-in via COVERAGE=1) found two guards that review missed — deep_freeze never ran on arrays, so freezing stopped at hashes for any fragment with required/enum; and strip_metadata's non-Hash guard never ran, though a $ref can resolve to an array or a bare boolean schema.

Verification

• 889 examples, 0 failures; RuboCop clean across 96 files with no added disables
• Schema subsystem at 100% line and branch coverage
• Docs build clean, including the new Shared Schemas page
• 379 refs to one fragment compile to a single cache entry in <1ms

Upgrading

The CHANGELOG carries the full migration. The one thing that fails silently: a service whose only schema was a constant or JSON file now runs unvalidated with no signal. Enumerate with:

grep -rn 'ARGUMENTS_SCHEMA\|RESULT_SCHEMA\|FAILURE_SCHEMA' app/ lib/
find app/schemas -name '*.json'

Pairing the upgrade with require_service_arguments_schema = true turns that silence into a loud failure.

🤖 Generated with Claude Code