Semval

This is a collection of rules, rule-evaluators, and tests for semantic validation of Versa receipts. Written in Rust, it uses napi-rs to compile to native modules for use in NodeJS environments. It can also be used in Rust backends, and is utilized by the Versa custodial service and official Docker images.

Usage

Install from npm:

npm install @versaprotocol/semval

In a NodeJS-runtime route handler:

import { runSemanticValidation } from "@versaprotocol/semval";

export async function POST(request: Request) {
  const data = await request.json();
  const semval = runSemanticValidation(data);
  for (const violation of semval.violations) {
    console.warn(`Semval Warning for rule ${violation.rule}: ${violation.description}`);
  }
  return new Response();
}

Support

The native module is tested on a support matrix for NodeJS versions 20 and 22

Future

One item to watch is napi-rs support for WASM targets, so that this could also be used in the browser

Not Yet Implemented

The below items are potential improvements to the semval module that have not yet been scheduled for development.

• Stricter use of types in rule validation Currently we just index into json objects directly by key, leading to maintainability problems
• Stricter use of types in test Currently Ava breaks down during CI/CD if types are added to the test files
• Name test suites after rules and validate that each rule has a test suite (as part of CI)
• Add conventional commit enforcement to git hooks
• Formalize standard for keyword referencing in a violation's details
• Optional quality scoring for data completeness