StatesLanguage - Declaratively design state machines that compile to Elixir based :gen_statem processes with the States Language JSON specification


Declaratively design state machines that compile to Elixir based :gen_statem processes with the States Language JSON specification.


States Language is the JSON specification behind AWS Step Functions, a powerful way to coordinate many disparate services into a cohesive “serverless” system. This library uses the same JSON specification and compiles to Elixir based :gen_statem processes.


The initial idea for the Elixir implementation came about while working on an IVR system and we wanted a way to describe “call flows” in a declarative manner. Ideally building a system on top to allow for solution engineers to visually build call flows for a client, without writing any code.

After researching the space a bit, we landed on the States Language spec and decided it was a great fit for describing state machines. With the power of Elixir macros in-hand, this library was born.

I’ve been working on this for a few months now and have found it to be a super useful way to design state machines. Using JSON as a declarative format has also opened up a lot of opportunities for sharing this structure across projects and UIs. There’s even some mix tasks to quickly output your state machines to Graphviz and DagreD3.

The Hexdocs documentation is pretty robust, but feel free to post any questions you have here.

I hope the community finds this as useful of a tool as we have.

Brought to you by Citybase


I’ve updated the docs a bit to be more explicit about how to follow along with the example code.


New Release 0.2.4

Big improvements to the JSONPath support. No breaking changes, but handles more edge cases and deeply nested structures better.


Really enjoying following this project and no doubt I will have use for it. Keep up the good work!

Thank you! I’ve found a ton of uses for it.

IVR call flows
LiveView state manager
API input normalization
Microservice orchestration

It’s great being able to vidualize your state machines, and build editors around them.

For building editors, I’ve found being able to use the JSON Schema along with JSON Schema UI for domain specific customization to be really powerful. With dropdowns for known Resource types and TransitionEvents, it’s easy to let non programmers design their state machines.

Would you care to make a blog post with some examples? I’m considering something like this for months but still can’t quite put my finger on it.

I’ll have a repo of a LiveView example up shortly.

I could probably put something together for an editor as well, but that’s a little more involved, so may take some time.

What would you like to see an example of?

I’d mostly be happy to see a flow of some sort, where you can’t get to an invalid state if the previous state invariants aren’t satisfied. Doesn’t have to be complex.

I struggle with a complex DB structure in my work where too much objects in the DB can be left in an inconsistent state and something that relies on them down the line can easily break, so I am wondering if a state machine can be a frictionless solution to that.

Here’s an example repo that uses LiveView along with StatesLanguage to define a multi-step form.

In the I’ve linked to a few files that I’ve commented on, hopefully it gives you a good idea of how to utilize the library.

This example does have a state that can only be reached given certain criteria.


This sounds quite interesting. I‘ve been looking at xstate in js a few weeks ago, which seems to be similar to this library.

It’s similar in that it uses a declarative text format to define your states and transitions. However Javascript doesn’t have gen_statem :slight_smile: And although it abstracts some of the complexities away from utilizing gen_statem, you still have complete access to all the functionality if need be.

I’m pretty excited by this - I’ll look through the examples.

I’d be interested in seeing a couple of things:

I work quite a bit with network protocols, and also with things that get serialised to disk. Having them be independent of a BEAM process and surviving serialisation make testing these things very very nice.

Maybe its already there, & I haven’t finished the examples yet. Thanks for publishing this!


For a visual design tool, you can actually use the AWS Step function editor. I’ll hopefully be working on an editor over the next month or so. We have one at work, but it’s not ready to open source.

Hmm, a process-less version could be really interesting. I hadn’t thought of that. I’m interested in your thoughts around it. How would it maintain it’s current state, would you rely on another process to maintain that?

I’ll dig a little more deeply into Sasa’s work for an idea.