iraa/scjson repository overview

⁠scjson

⁠Overview

scjson is a structured, schema-based representation of SCXML⁠, the W3C standard for state machine modeling. This format preserves the semantics and hierarchy of SCXML while making it more accessible to modern tools, languages, and interfaces.

Why JSON?

• Easier to parse in JavaScript, Python, Rust, etc.
• Fits naturally with REST APIs, editors, and static validation
• Can be round-tripped to and from standard SCXML
• Works with compact formats like MessagePack or Protobuf when needed

⁠Goals

• 💡 Interoperability: Serve as a bridge between SCXML and modern application ecosystems
• 📦 Portability: Enable translation to binary formats (MessagePack, Protobuf, etc.)
• 📚 Pedagogy: Make it easier to teach and learn state machines with cleaner syntax and visual tools
• 🔁 Round-trip Fidelity: Support conversion back to valid SCXML without semantic loss

⁠Schema

The canonical scjson.schema.json file is located in /schema⁠.
It is generated from Pydantic models and used to validate all *.scjson documents.

⁠Directory Structure

Each language implementation lives in its own directory, as a standalone module or library root:

/schema/ → JSON Schema definition of scjson /examples/ → SCXML and scjson sample pairs /tutorial/ → Git submodule: Zhornyak SCXML tutorial /python/ → Python reference implementation (CLI + library) /js/ → JavaScript CLI and library /ruby/ → Ruby CLI and gem /go/ → Go command line utility /rust/ → Rust command line utility /swift/ → Swift command line tool /java/ → Java command line tool /lua/ → Lua scripts /csharp/ → C# command line tool

Each directory is designed to be independently usable as a library or CLI tool.

⁠Converters

This repo includes a curated set of canonical SCXML examples and their equivalent scjson forms in /examples⁠. These are used for:

• Functional validation (SCXML ↔ scjson ↔ SCXML)
• Teaching state machine concepts via visual tools
• Demonstrating usage in editors, UI libraries, and low-code platforms

These examples are derived from and/or adapted from:

⁠📚 Included Tutorial (as Git Submodule)

We include Alex Zhornyak’s SCXML Editor Tutorial as a Git submodule under /tutorial⁠.
This provides a rich set of canonical SCXML test cases and diagrams.

⁠🛠️ Submodule Setup

If you cloned this repo and /tutorial is empty, run:

git submodule init
git submodule update
Or clone with submodules in one step:

git clone --recurse-submodules https://github.com/your-org/scjson.git

This ensures you get the complete tutorial content alongside the examples and converters.

⁠Converters

All converters share the same schema and test suite to ensure compatibility.

⁠Getting Started

# Convert from SCXML to scjson
scjson convert --from scxml path/to/file.scxml --to scjson path/to/file.scjson

# Validate a scjson file
scjson validate path/to/file.scjson

⁠Java Module

The Java implementation uses Maven. If your environment requires an HTTP/HTTPS proxy, create ~/.m2/settings.xml with proxy settings before building:

<settings>
  <proxies>
    <proxy>
      <id>internal-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy</host>
      <port>8080</port>
      <nonProxyHosts>localhost|127.0.0.1</nonProxyHosts>
    </proxy>
    <proxy>
      <id>internal-proxy-https</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>proxy</host>
      <port>8080</port>
      <nonProxyHosts>localhost|127.0.0.1</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

Build the module with:

cd java && mvn clean install -DskipTests -B && cd ..

⁠Package Repostory Availability

pypi: [https://pypi.org/project/scjson/⁠]

pip install scjson

For a full example of installing toolchains and dependencies across languages see codex/startup.sh⁠.

⁠Python Module

cd py
pip install -r requirements.txt
pytest -q

⁠JavaScript Module

cd js
npm ci
npm test --silent

⁠Ruby Module

cd ruby
gem install bundler
bundle install
bundle exec rspec

⁠Go Module

cd go
go test ./...
go build

⁠Rust Module

cd rust
cargo test

⁠Swift Module

cd swift
swift test

⁠C# Module

cd csharp
dotnet test -v minimal

⁠Lua Module

cd lua
luarocks install luaexpat --deps-mode=one
luarocks install dkjson --deps-mode=one
luarocks install busted --deps-mode=one
busted tests