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.
• Nested predicates as arguments – predicates can be passed as arguments to other predicates, enabling higher-order Prolog constructs like findall/3, bagof/3, and setof/3.
• Wasm bindings generated with wasm-bindgen, making the same API available on npm.

Installation

Rust (crates.io)

[dependencies]
json_to_prolog = "0.3.4"

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": {
  "X": { "var": "X" },
  "Z": { "var": "Z" }
 },
 "evaluate": {
  "and": [
   { "predicate": "parent", "x": { "var": "X" }, "y": { "var": "Y" } },
   { "predicate": "parent", "x": { "var": "Y" }, "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 (an object), and an evaluate tree composed of logic nodes (predicate, and, or, not). Each property may include an optional label field (e.g. { "var": "X", "label": "timestamp" }). Arguments are sorted alphabetically: by label if provided, otherwise by property key. The optional updateView defaults to "assert".
• Queries – must include claimType: "query" and a predicate; any other properties become arguments. Arguments are sorted alphabetically using the same logic as rules: when a label is provided for a property, the label is used as the sort key; otherwise the property key itself is used. 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.

Nested Predicates: Predicate arguments can themselves be predicates (logic nodes), enabling complex Prolog constructs like findall/3, bagof/3, and higher-order predicates. For example:

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

let rule = json!({
 "claimType": "rule",
 "name": "foo",
 "headVariables": {
  "name": { "var": "_Name" },
  "people": { "var": "People" }
 },
 "evaluate": {
  "predicate": "findall",
  "a_template": { "var": "_Name" },
  "b_goal": {
   "predicate": "person",
   "name": { "var": "_Name" }
  },
  "c_result": { "var": "People" }
 }
});

let prolog = convert_rule_to_prolog(&rule)?;
assert_eq!(prolog, "assert(foo(_Name, People) :- findall(_Name, person(_Name), People)).");

In this example, the b_goal argument to findall is itself a predicate (person(_Name)), demonstrating the nested predicate capability.

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.