A JSON-based serialization of SCXML (State Chart XML) with SCXML/SCML execution tooling and converters.
npm install scjson
This directory contains the JavaScript implementation of scjson, a format for representing SCXML state machines in JSON. The package provides a command line interface to convert between .scxml and .scjson files and to validate documents against the project's schema.
For details on how SCXML elements are inferred during conversion see INFERENCE.md.
The package includes typescript types for the functions and default functions to return each.
``bash`
npm install scjson
You can also install from a checkout of this repository:
`bash`
cd js && npm install
After installation the scjson command is available:
`bashConvert a single file
scjson json path/to/machine.scxml
Harness CLI (SCION)
The package also ships a harness CLI that executes SCXML using the SCION engine
and emits JSONL traces compatible with compare tooling.
Install peer dependency:
`bash
npm i scion-core
`Usage:
`bash
npx scjson-scion-trace -I path/to/chart.(scxml|scjson) -e path/to/events.jsonl [--xml]
`Quick check (from this repo):
`bash
cd js
npm ci
npm run harness:sample
`Flags:
-
--leaf-only – emit leaf-only configurations (SCION already reports atomic states)
- --omit-delta – clear datamodelDelta
- --omit-transitions – clear firedTransitions
- --strip-step0-noise – at step 0, clear datamodelDelta and firedTransitions
- --strip-step0-states – at step 0, clear enteredStates and exitedStatesNotes:
-
.scjson input is converted to SCXML internally before execution.
- SCION does not model time; {"advance_time": N} control tokens emit a
synthetic step to keep streams progressing.Conversion Functions
`js
/**
* xmlToJson
* Convert an SCXML string to scjson.
*
* @param {string} xmlStr - XML input.
* @param {boolean} [omitEmpty=true] - Remove empty values when true.
* @returns {string} JSON representation.
*//**
* jsonToXml
* Convert a scjson string to SCXML.
*
* @param {string} jsonStr - JSON input.
* @returns {string} XML output.
*/
`Common JS Translate Usage
`js
const { xmlToJson, jsonToXml } = require('scjson');`ESR translate usage
`js
import { xmlToJson, jsonToXml }from "scjson/browser"
`Shared Converters
Both the Node and browser builds use the same conversion logic exposed in
scjson/converters. You can import these helpers directly if you need access to
the utility functions used by the CLI and browser modules.
`js
import { xmlToJson, jsonToXml } from 'scjson/converters';
`Axios Endpoint Example
`typescript
import axios from "axios"
import * as scjson from "scjson/props"// A function to creat a new doc with three states and transitions.
const newScxml = (): scjson.ScxmlProps => {
const doc: scjson.ScxmlProps = scjson.defaultScxml();
let state: scjson.StateProps = scjson.defaultState();
let transition: scjson.TransitionProps = scjson.defaultTransition();
doc.name = 'New State Machine';
doc.exmode = scjson.ExmodeDatatypeProps.Lax;
doc.binding = scjson.BindingDatatypeProps.Early;
doc.initial.push('Start');
state.id = 'Start';
transition.target.push('Process');
state.transition.push(transition);
doc.state.push(state);
state = scjson.defaultState();
state.id = 'Process';
transition = scjson.defaultTransition();
transition.target.push('End');
state.transition.push(transition);
doc.state.push(state);
state = scjson.defaultState();
state.id = 'End';
transition = scjson.defaultTransition();
transition.target.push('Start');
state.transition.push(transition);
doc.state.push(state);
return doc;
}
// Create Axios instance
const ax = axios.create({
baseURL: "https://api.example.com/scxml",
headers: { "Content-Type": "application/json" },
withCredentials: true,
});
// Export a function to send the doc
export const sendNewScxml = () => {
const doc = newScxml();
ax.post('/newDoc', doc);
}
`Known Issues
None at this time.Operational conformance testing is performed via uber_test.py
`bash
/py# python uber_test.py -l javascript 2>&1 | tee test.log
`
Note: uber_test.py applies all scxml files in Zhornyak's ScxmlEditor-Tutorial which provides a robest set of scxml test vectors useful for standard compliance verification. This is the only file in the test suite which fails to verify round-trip.
$3
$3
Each enumeration represents a restricted string set used by SCXML. The values
shown below mirror those defined in the SCJSON schema.
enums use this pattern to all static and dynamic portions to be treated separately,
but mapped to the same name.
`typescript
export const BooleanDatatypeProps = {
False: "false",
True: "true",
} as const;export type BooleanDatatypeProps = typeof BooleanDatatypeProps[keyof typeof BooleanDatatypeProps];
`-
AssignTypeDatatypeProps – how the element manipulates the datamodel.
Values: replacechildren, firstchild, lastchild, previoussibling,
nextsibling, replace, delete, addattribute.
- BindingDatatypeProps – determines if datamodel variables are bound early or
late during execution.
- BooleanDatatypeProps – boolean attribute values true or false.
- ExmodeDatatypeProps – processor execution mode, either lax or strict.
- HistoryTypeDatatypeProps – type of state: shallow or deep.
- TransitionTypeDatatypeProps – whether a is internal or
external.$3
Several generated classes share generic helper fields:
-
other_attributes: Record capturing additional XML attributes from
foreign namespaces.
- other_element: list[object] allowing untyped child nodes from other
namespaces to be preserved.
- content: list[object] used when elements permit mixed or wildcard
content.
$3
Plain typescript types without runtime validation.
- AssignProps AssignArray – update a datamodel location with an expression or value.
- CancelProps CancelArray – cancel a pending operation.
- ContentProps ContentArray – inline payload used by and .
- DataProps DataArray – represents a single datamodel variable.
- DatamodelProps DatamodelArray – container for one or more elements.
- DonedataProps DonedataArray – payload returned when a state is reached.
- ElseProps – fallback branch for conditions.
- ElseifProps – conditional branch following an .
- FinalProps FinalArray – marks a terminal state in the machine.
- FinalizeProps FinalizeArray – executed after an completes.
- ForeachProps ForeachArray – iterate over items within executable content.
- HistoryProps HistoryArray – pseudostate remembering previous active children.
- IfProps IfArray – conditional execution block.
- InitialProps InitialArray – starting state within a compound state.
- InvokeProps InvokeArray – run an external process or machine.
- LogProps LogArray – diagnostic output statement.
- OnentryProps OnentryArray – actions performed when entering a state.
- OnexitProps OnexitArray – actions performed when leaving a state.
- ParallelProps ParallelArray – coordinates concurrent regions.
- ParamProps ParamArray – parameter passed to or .
- RaiseProps RaiseArray – raise an internal event.
- ScriptProps ScriptArray – inline executable script.
- ScxmlProps – root element of an SCJSON document.
- SendProps SendArray – dispatch an external event.
- StateProps StateArray – basic state node.
- TransitionProps TransitionArray – edge between states triggered by events.$3
- Kind - unique marker for each of the types.
`typescript
export type Kind = "number" | "string" | "record" | "number[]" | "string[]"
| "record[]" | "assign" | "assigntypedatatype" | "bindingdatatype" | "booleandatatype"
| "cancel" | "content" | "data" | "datamodel" | "donedata" | "else" | "elseif"
| "exmodedatatype" | "final" | "finalize" | "foreach" | "history" | "historytypedatatype" | "if"
| "initial" | "invoke" | "log" | "onentry" | "onexit" | "parallel" | "param" | "raise"
| "script" | "scxml" | "send" | "state" | "transition" | "transitiontypedatatype"
| "assignarray" | "cancelarray" | "contentarray" | "dataarray" | "datamodelarray"
| "donedataarray" | "finalarray" | "finalizearray" | "foreacharray" | "historyarray" | "ifarray"
| "initialarray" | "invokearray" | "logarray" | "onentryarray" | "onexitarray" | "parallelarray"
| "paramarray" | "raisearray" | "scriptarray" | "sendarray" | "statearray" | "transitionarray";
`
- PropsUnion - a union of the types used in the scxml data model
`typescript
export type PropsUnion = null | string | number | Record | string[] | number[]
| Record[] | AssignProps | AssignTypeDatatypeProps | BindingDatatypeProps
| BooleanDatatypeProps | CancelProps | ContentProps | DataProps | DatamodelProps | DonedataProps
| ElseProps | ElseifProps | ExmodeDatatypeProps | FinalProps | FinalizeProps | ForeachProps
| HistoryProps | HistoryTypeDatatypeProps | IfProps | InitialProps | InvokeProps | LogProps
| OnentryProps | OnexitProps | ParallelProps | ParamProps | RaiseProps | ScriptProps
| ScxmlProps | SendProps | StateProps | TransitionProps | TransitionTypeDatatypeProps
| AssignArray | CancelArray | ContentArray | DataArray | DatamodelArray | DonedataArray
| FinalArray | FinalizeArray | ForeachArray | HistoryArray | IfArray | InitialArray
| InvokeArray | LogArray | OnentryArray | OnexitArray | ParallelArray | ParamArray
| RaiseArray | ScriptArray | SendArray | StateArray | TransitionArray;
`
- KindMap - maps string name to type for the objects used in the scxml data model
`typescript
export type KindMap = {
assign: AssignProps
assignarray: AssignArray
assigntypedatatype: AssignTypeDatatypeProps
bindingdatatype: BindingDatatypeProps
booleandatatype: BooleanDatatypeProps
cancel: CancelProps
cancelarray: CancelArray
content: ContentProps
contentarray: ContentArray
data: DataProps
dataarray: DataArray
datamodel: DatamodelProps
datamodelarray: DatamodelArray
donedata: DonedataProps
donedataarray: DonedataArray
else: ElseProps
elseif: ElseifProps
exmodedatatype: ExmodeDatatypeProps
final: FinalProps
finalarray: FinalArray
finalize: FinalizeProps
finalizearray: FinalizeArray
foreach: ForeachProps
foreacharray: ForeachArray
history: HistoryProps
historyarray: HistoryArray
historytypedatatype: HistoryTypeDatatypeProps
if: IfProps
ifarray: IfArray
initial: InitialProps
initialarray: InitialArray
invoke: InvokeProps
invokearray: InvokeArray
log: LogProps
logarray: LogArray
onentry: OnentryProps
onentryarray: OnentryArray
onexit: OnexitProps
onexitarray: OnexitArray
parallel: ParallelProps
parallelarray: ParallelArray
param: ParamProps
paramarray: ParamArray
raise: RaiseProps
raisearray: RaiseArray
script: ScriptProps
scriptarray: ScriptArray
scxml: ScxmlProps
send: SendProps
sendarray: SendArray
state: StateProps
statearray: StateArray
transition: TransitionProps
transitionarray: TransitionArray
transitiontypedatatype: TransitionTypeDatatypeProps
}
`
$3
github: [https://github.com/SoftOboros/scjson]
`bash
git clone https://github.com/SoftOboros/scjson.gitgit clone git@github.com:SoftOboros/scjson.git
gh repo clone SoftOboros/scjson
`pypi: [https://pypi.org/project/scjson/]
`bash
pip install scjson
`cargo: [https://crates.io/crates/scjson]
`bash
cargo install scjson
`dockerhub: [https://hub.docker.com/r/iraa/scjson]
(Full development environment for all supported languages)
`bash
docker pull iraa/scjson:latest
``
All source code in this directory is released under the BSD 1-Clause license. See LICENSE and LEGAL.md for details.