Operator Registry

MathJSON.jl uses a JSON-based registry system based on the Cortex Compute Engine standard. The registry defines operators, their categories, and Julia function mappings.

Cortex Compute Engine Compatibility

The operator definitions are sourced from the Cortex Compute Engine's OPERATORS.json, providing full compatibility with the MathJSON standard library.

File Structure

The registry consists of three JSON files in the data/ directory:

data/
├── categories.json        # Category definitions
├── operators.json         # Operator definitions (Cortex format)
├── julia_functions.json   # Julia function mappings
└── schemas/               # JSON Schema files for validation
    ├── categories.schema.json
    ├── operators.schema.json
    └── julia_functions.schema.json

Registry File Formats

categories.json

Defines operator categories matching the Cortex Compute Engine standard.

{
  "categories": [
    {
      "id": "Arithmetic",
      "name": "Arithmetic",
      "description": "Basic arithmetic operations and functions"
    }
  ]
}

operators.json

Defines operators using the Cortex Compute Engine format with full metadata.

{
  "operators": [
    {
      "name": "Add",
      "category": "Arithmetic",
      "arity": "variadic",
      "signature": "(value+) -> value",
      "associative": true,
      "commutative": true,
      "idempotent": true,
      "lazy": true,
      "broadcastable": true,
      "description": "Sum of two or more values.",
      "wikidata": "Q32043"
    }
  ]
}

julia_functions.json

Maps operators to Julia functions for expression evaluation.

{
  "mappings": [
    {
      "operator": "Add",
      "julia_function": "+",
      "module": "Base"
    },
    {
      "operator": "And",
      "julia_function": null,
      "expression": "logical_and"
    }
  ]
}

Special Functions: Some operators like And and Or require anonymous functions. These use the expression field to reference entries in the SPECIAL_FUNCTIONS dictionary:

const SPECIAL_FUNCTIONS = Dict{String,Function}(
    "logical_and" => (a, b) -> a && b,
    "logical_or" => (a, b) -> a || b,
    "logical_nand" => (a, b) -> !(a && b),
    "logical_nor" => (a, b) -> !(a || b),
    "logical_implies" => (a, b) -> !a || b,
    "logical_equivalent" => (a, b) -> a == b,
    "square" => x -> x^2,
    "nth_root" => (x, n) -> x^(1/n),
    # ... and more
)

Categories

MathJSON.jl supports all 15 Cortex Compute Engine categories:

Selected Operators by Category

Arithmetic (Sample)

Trigonometry (Sample)

Relational Operators

Logic

Collections (Sample)

Calculus

Linear Algebra (Sample)

Statistics (Sample)

Combinatorics (Sample)

Adding New Operators

Step 1: Add Category (if needed)

Add a new entry to data/categories.json:

{
  "id": "MyCategory",
  "name": "My Category",
  "description": "Description of the category"
}

Note: You must also add the category to the OperatorCategory.T enum in src/operators.jl and the CATEGORY_ENUM_MAP dictionary.

Step 2: Add Operator

Add a new entry to data/operators.json:

{
  "name": "MyOperator",
  "category": "MyCategory",
  "arity": "2",
  "signature": "(number, number) -> number",
  "associative": false,
  "commutative": true,
  "idempotent": false,
  "lazy": false,
  "broadcastable": true,
  "description": "What this operator does"
}

Step 3: Add Julia Function Mapping

Add a new entry to data/julia_functions.json:

{
  "operator": "MyOperator",
  "julia_function": "my_julia_function",
  "module": "Base"
}

For operators without a direct Julia equivalent:

{
  "operator": "MyOperator",
  "julia_function": null
}

For operators requiring custom anonymous functions:

1. Add to SPECIAL_FUNCTIONS in src/registry_loader.jl:

   "my_special" => (a, b) -> custom_logic(a, b)

2. Reference in JSON:

   {
     "operator": "MyOperator",
     "julia_function": null,
     "expression": "my_special"
   }

Step 4: Run Tests

Validate your changes pass schema validation and all tests:

julia --project=. -e 'using Pkg; Pkg.test()'

API Reference

See the API Reference page for documentation of operator-related functions (get_category, get_julia_function, is_known_operator) and types (OperatorCategory).

Registry Types

CategoryInfo

OperatorInfo

RegistryLoadError <: Exception