json_to_prolog

json_to_prolog converts structured JSON descriptions of facts, queries, and rules into Prolog source code. It is published as both a Rust crate (for native use) and a Wasm package (for npm), so you can validate domain data on the server or in the browser with the same logic.

[!WARNING] The schema is still evolving. Expect breaking changes before 1.0.0.

Features

JSON Schema validation for each claim type (facts, rules, queries) before conversion.
Deterministic Prolog output (fields sorted alphabetically, optional label-based ordering for rule arguments, consistent quoting, and wildcard handling).
Support for logical combinators (and, or, not) when defining rule bodies.
Wasm bindings generated with wasm-bindgen, making the same API available on npm.

Installation

Rust (crates.io)

[dependencies]
json_to_prolog = "0.3.2"

JavaScript/TypeScript (npm)

npm install json_to_prolog
# or
yarn add json_to_prolog

The npm package ships pre-built Wasm bindings in pkg/. You can import the helper functions from json_to_prolog or use the generated JS glue directly.

Quick Start

Converting a fact (Rust)

use json_to_prolog::convert_fact_to_prolog;
use serde_json::json;

let fact = json!({
 "claimType": "fact",
 "predicate": "person",
 "updateView": "assert",
 "name": "Alice",
 "age": 30,
 "active": true,
 "nickname": null // converted to wildcard `_`
});

let prolog = convert_fact_to_prolog(&fact)?;
assert_eq!(prolog, "assert(person(true, 30, 'Alice', _)).");

JavaScript + SWI-Prolog (Node)

import init, {
  convert_fact_to_prolog_wasm,
  convert_query_to_prolog_wasm,
} from "json_to_prolog";
import SWIPL from "swipl-wasm";

const main = async () => {
  await init();
  const swipl = await SWIPL({ arguments: ["-q"] });

  const fact = {
    claimType: "fact",
    predicate: "person",
    name: "Alice",
    age: 20,
    updateView: "assert",
  };

  const query = {
    claimType: "query",
    predicate: "person",
    name: "Alice",
    age: { var: "Age" },
  };

  const factClause = convert_fact_to_prolog_wasm(fact);
  const queryClause = convert_query_to_prolog_wasm(query);

  await swipl.prolog.call(factClause); // assert fact once
  const results = await swipl.prolog.query(queryClause);
  console.log(results.once()); // -> { Age: "20" }
};

main();

Converting a rule

use json_to_prolog::convert_rule_to_prolog;
use serde_json::json;

let rule = json!({
 "claimType": "rule",
 "name": "grandparent",
 "headVariables": [{ "var": "X" }, { "var": "Z" }],
 "returns": "boolean",
 "evaluate": {
  "and": [
   { "predicate": "parent", "args": [{ "var": "X" }, { "var": "Y" }] },
   { "predicate": "parent", "args": [{ "var": "Y" }, { "var": "Z" }] }
  ]
 }
});

let prolog = convert_rule_to_prolog(&rule)?;
assert_eq!(prolog, "assert(grandparent(X, Z) :- (parent(X, Y), parent(Y, Z))).");

Converting a query

use json_to_prolog::convert_query_to_prolog;
use serde_json::json;

let query = json!({
 "claimType": "query",
 "predicate": "person",
 "name": { "var": "Name" },
 "age": { "var": "Age" }
});

let prolog = convert_query_to_prolog(&query)?;
assert_eq!(prolog, "person(Age, Name)");

JSON Schema Overview

Each converter validates its input using jsonschema before emitting Prolog:

Facts – must provide claimType: "fact" and predicate. The optional updateView field can be one of: "assert", "retract", "assertz", "asserta" (defaults to "assert" if omitted). Additional keys become arguments and are sorted alphabetically for deterministic output.
Rules – require claimType: "rule", a head name, headVariables, and an evaluate tree composed of logic nodes (predicate, and, or, not). Each prologValue in headVariables or predicate args may include an optional label (e.g. { "var": "X", "label": "timestamp" }); when present, arguments are sorted lexicographically by those labels before conversion, otherwise their original order is preserved. Only boolean rules are currently supported. The optional updateView defaults to "assert".
Queries – must include claimType: "query" and a predicate; any other properties become arguments. Objects of the form { "var": "VarName" } produce bare Prolog variables.

Null JSON values translate to the wildcard _. Arrays become Prolog lists, and strings are single-quoted to match atom syntax. Objects shaped like { "var": "Token" } insert the token verbatim (useful for variables or pre-declared atoms). The claimType field is filtered out during conversion and does not appear in the generated Prolog code.

API Surface

Rust functions:

convert_json_to_prolog(value: &Value) -> Result<String, String> – Unified converter that dispatches to the appropriate converter based on claimType
convert_fact_to_prolog(value: &Value) -> Result<String, String>
convert_rule_to_prolog(value: &Value) -> Result<String, String>
convert_query_to_prolog(value: &Value) -> Result<String, String>

Wasm bindings expose the same conversions but accept/return JsValue:

convert_json_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue> – Unified converter
convert_fact_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>
convert_rule_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>
convert_query_to_prolog_wasm(value: &JsValue) -> Result<JsValue, JsValue>

All functions return descriptive error messages when validation fails. The unified convert_json_to_prolog function is recommended when you have mixed claim types or want automatic dispatch based on the claimType field.

Development

Prerequisites:

Rust toolchain (stable)
wasm-pack (for rebuilding the npm package)

Helpful commands:

cargo test           # Run the unit test suite
wasm-pack build --target bundler  # Rebuild Wasm bindings

Before publishing to crates.io or npm, ensure tests pass and review the schema contracts. Because the project is still experimental, contributions that extend validation or add new claim types are welcome—open an issue or PR describing your idea.

License

MIT. See Cargo.toml for the authoritative declaration.

json_to_prolog 0.3.3