umpire-spec

The cross-language conformance specification for Umpire — the portable form-logic engine.

This repository provides two artifacts:

• umpire.schema.json — A JSON Schema (draft 2020-12) that validates .umpire.json files. You can use this in editors to enable autocomplete and inline validation without a Node.js toolchain.
• conformance/ — Plain JSON fixtures. Any Umpire runtime (TypeScript, Python, Dart, Kotlin, etc.) can consume these to verify behavioral correctness against the reference implementation.

Quick Start

npm install
npm run validate

This runs AJV against umpire.schema.json. It verifies that every conformance fixture’s inner schema block is structurally valid and ensures that intentionally malformed documents are rejected.

Conformance Fixtures

Read conformance/README.md to understand the fixture shape and how to write a port runner.

To implement a runner:

1. Load conformance/index.json.
2. For each fixture in index.fixtures, parse the file, extract fixture.schema, and execute it using your Umpire implementation against each test case.
3. Assert that your output matches case.expectedAvailability.

All fixture paths in index.json are relative to the conformance/ directory.

Adding to Editors

To enable autocomplete for .umpire.json files:

• VS Code: Add this to your .vscode/settings.json:

  {
    "json.schemas": [
      {
        "fileMatch": ["*.umpire.json"],
        "url": "./umpire.schema.json"
      }
    ]
  }
  

• SchemaStore: Submission to the SchemaStore catalog is on the roadmap.

Versioning

This repository uses semver tags (e.g., v1.0.0). Bump the tag whenever the schema or the fixture contract changes in a way that requires port updates.

License

See LICENSE.

This site is open source. Improve this page.