The ym JSON format

yasmine's model can be populated from a standardized JSON file. A yasmine model JSON (.ym) file has this structure:

{
"version":"2.0",
"event_list":[
{
"name":"",
"ID":0,
"priority":0
}
],
"state_machine": {
"transitions": [
{
"name": "",
"kind": "",
"source": "",
"target": "",
"event_name": [],
"guard": "",
"behavior": ""
}
],
"root": {
"name": "",
"type": "composite_state",
"regions": [
{
"name": "",
"vertices": [
{
"name": "",
"type": "",
"enter_behavior": "",
"do_behavior": "",
"exit_behavior": "",
"deferred_event_name": [],
"error_event": []
}
]
}
],
"pseudostates": [],
"enter_behavior": "",
"exit_behavior": "",
"deferred_event_name": []
}
}
}

Example

A small example populated with data:

{
"version":"2.0",
"event_list":[
{
"name":"E1",
"ID":1,
"priority":0
},
{
"name":"E2",
"ID":2,
"priority":0
}
],
"state_machine":{
"transitions":[
{
"event_name":[
],
"name":"transition1",
"kind":0,
"source":"root/main_region/Initial",
"target":"root/main_region/State1",
"guard":"",
"behavior":""
},
{
"event_name":[
],
"name":"transition2",
"kind":0,
"source":"root/main_region/State1/Region1S1/Initial_S1",
"target":"root/main_region/State1/Region1S1/State2",
"guard":"",
"behavior":""
},
{
"event_name":[
{
"name":"E1"
}
],
"name":"transition3",
"kind":0,
"source":"root/main_region/State1",
"target":"root/main_region/State2",
"guard":"",
"behavior":""
},
{
"event_name":[
],
"name":"transition4",
"kind":0,
"source":"root/main_region/State2",
"target":"root/main_region/State3",
"guard":"",
"behavior":""
}
],
"root":{
"name":"root",
"type":"composite_state",
"regions":[
{
"vertices":[
{
"name":"Initial",
"type":"initial_pseudostate"
},
{
"name":"State1",
"type":"composite_state",
"regions":[
{
"vertices":[
{
"name":"Initial_S1",
"type":"initial_pseudostate"
},
{
"name":"State2",
"type":"simple_state",
"do_behavior":"logic.do_work",
"enter_behavior":"logic.initialize_work",
"exit_behavior":"",
"deferred_event_name":[
],
"error_event":[
]
},
{
"name":"State3",
"type":"simple_state",
"do_behavior":"logic.start_process",
"enter_behavior":"",
"exit_behavior":"",
"deferred_event_name":[
],
"error_event":[
]
}
],
"name":"region1S1"
}
],
"pseudostates":[
],
"enter_behavior":"logic.print_start_message",
"exit_behavior":"logic.print_end_message",
"deferred_event_name":[
]
}
],
"name":"main_region"
}
],
"pseudostates":[
],
"enter_behavior":"",
"exit_behavior":"",
"deferred_event_name":[
]
}
}
}

Version

The "version" is the version of the model file (currently 2.0).

Name

Type

Explanation

Allowed values

version

string

version of model file

2.0

Event list

"event_list" represent a list of event objects.

Event

An event is an object that will have a string name and an integer ID as properties.

Name

Type

Explanation

Allowed values

name

string

name

no restriction

ID

int

identification number

int

priority

int

priority of event

int

State machine

The "state_machine" object describes the state machine's elements and behaviors. There are two major sections: transitions and the state machine description itself.

Transitions

"Transitions" is an array of transition objects. Each object has these properties:

Name

Type

Explanation

Allowed values

name

string

name

no restrictions

kind

string

kind

transition kind

source

string

URI of the source vertex

valid URI of a vertex

target

string

URI of the target vertex

valid URI of a vertex

event_name

array[string]

list of events names for which the transition can be enabled

valid event name

guard

string

implementation to use for the guard

implementation referrer

behavior

string

implementation to use for the behavior

implementation referrer

Root

"root" is the object representing the state machine's outer composite state that contains all vertices. "root" always implicitly has the "composite_state" type.

For the descriptions of the properties refer to the "composite state" object, since the "root" is a composite state.

Composite state

A composite state object is owned by a region. The root state is an exception because the root does not have an owner.

The properties of a composite state are summarized in the next table.

Name

Type

Explanation

Allowed values

name

string

name

No restriction.

type

string

type

composite_state

regions

array[region]

list of regions belonging to the composite state

region objects

pseudostates

array[pseudostates]

list of pseudostates objects belonging to the composite state object

  • entry_point object

  • exit_point object

  • shallow_history object

  • deep_history object

enter_behavior

string

implementation to use for the enter behavior.

implementation referrer

exit_behavior

string

implementation to use for the exit behavior.

implementation referrer

deferred_event_name

array[string]

list of names of events that shall be deferred

valid event name

Region

A region object is owned by a composite state object and have the following properties:

Name

Type

Explanation

Allowed values

name

string

name

no restrictions

vertices

array[vertex]

list of vertices belonging to the region

  • simple state object

  • async simple state object

  • composite state object

  • final state object

  • initial pseudostate object

  • terminate pseudostate object

  • fork object

  • join object

  • junction object

  • choice object

Simple state and async simple state

This objects have the same structure but the type is different for each.

Name

Type

Explanation

Allowed values

name

string

name

no restrictions

type

string

type

one of the following vertex types:

  • simple_state

  • async_simple_state

enter_behavior

string

implementation to use for the enter behavior.

implementation referrer

do_behavior

string

implementation to use for the do behavior.

implementation referrer

exit_behavior

string

implementation to use for the exit behavior.

implementation referrer

deferred_event_name

array[string]

list of names of events that shall be deferred

valid event name

error_event

array[event_names]

list of names of events that are processed when an error occurs.

valid event name

Pseudostates and final state

Pseudostates and the final state share the same structure. They contain a name and a type. The type is a predetermined string.

Name

Type

Explanation

Allowed values

name

string

name

no restrictions

type

string

type

one of the following vertex types:

  • final_state

  • initial_pseudostate

  • terminate_pseudostate

  • fork

  • join

  • junction

  • choice

  • entry_point

  • exit_point

  • shallow_history

  • deep_history

Data types

Transition kind

  • external

  • local

  • internal

URI

The URI represents a chain of names as a string. The URI of an element consists of the names of all the object's ancestors, both regions and composite states, up to the root of the state machine - excluding the root. The names in the URI chain are separated by the '/' character.

Implementation referrer

An implementation referrer is a description of a call to a behavior or a guard. It can be a method call or a free function call.

In the following table a list of possible calls can be seen. 'foo' and 'bar' will be replaced with the user's desired method/function and object name. The object has to be visible in the scope of the state machine.

Call

Explanation

this->foo

Call of method 'foo' of containing object.

bar->foo

Call of method 'foo' of object 'bar' via pointer.

bar.foo

Call of method 'foo' from object 'bar' via reference.

bar::foo

Call of static method 'foo' of class 'bar'.

foo

Call of free function 'foo'.

Vertex type

Vertices can have one of the following types:

Vertex

Type value

Simple state

simple_state

Asynchronous simple state

async_simple_state

Composite state

composite_state

Final state

final_state

Initial pseudostate

initial_pseudostate

Terminate pseudostate

terminate_pseudostate

Fork

fork

Join

join

Junction

junction

Choice

choice

Entry point

entry_point

Exit_point

exit_point

Shallow history

shallow_history

Deep history

deep_history