Preprocessing JSON

Some JSON preprocessing capabilities are included in PlantUML, and available for all diagrams.

That extends the current preprocessing.

🛈 If you are looking for how to display JSON data: see rather Display JSON Data.

Variable definition

In addition to existing type (String and Integer), you can define JSON variable.

Example:

!$foo = { "name": "John", "age" : 30 }

Corresponding of this structure:

🎉 Copied!
@startjson
{
"$foo": { "name": "John", "age" : 30 }
}
@endjson

Access to data

Once a variable is defined, you can access to its members:

🎉 Copied!
@startuml
!$foo = { "name": "John", "age" : 30 }
Alice -> Bob : Do you know **$foo.name** ?
@enduml

Complex structures

It is possible to use complex JSON objects and arrays, with definition on several lines.

Let $foo, the structure:

🎉 Copied!
@startjson
{
"$foo":{ "company": "Skynet", "employees" : [
  {"name" : "alice", "salary": 100 },
  {"name" : "bob", "salary": 50} ]
}
}
@endjson

You can acess to the values:
  • $foo.employees[0].name
  • $foo.employees[0].salary

🎉 Copied!
@startuml
!$foo = { "company": "Skynet", "employees" : [
  {"name" : "alice", "salary": 100 },
  {"name" : "bob", "salary": 50} ]
}
start
:The salary of <u>$foo.employees[0].name</u> is <u>$foo.employees[0].salary</u>;
@enduml

Loading data

This has not been implemented yet.

Some standard function provides a way to load JSON object from URL or local files:

!$foo = %loadJSON("http://foo.net/users/list.json")
!$foo2 = %loadJSON("myDir/localFile.json")

Loop [foreach]

If you define array, you can loop over.

🎉 Copied!
@startmindmap
!$foo = { "company": "Skynet", "employees" : [
  {"name" : "alice", "salary": 100 },
  {"name" : "bob", "salary": 50} ]
}

* The salary of  
!foreach $emp in $foo.employees
  ** **$emp.name** 
  *** is 
  **** **$emp.salary**
!endfor
@endmindmap

[SW] Some remarks
  • for or better foreach ? -> foreach
  • It would be nice to also have "break" and "continue"
  • It would be nice to also have the for or while loop with a standard variable

Full Example

From a example worked in a forum question, with this JSON structure:

🎉 Copied!
@startjson
{
"data":
  {
  "participants": [
    {"name": "XYZ", "as": "xyz"},
    {"name": "RST", "as": "rst"},
    {"name": "UVW", "as": "uvw"}]
  }
}
@endjson

🎉 Copied!
@startuml
!unquoted function DRAW($x) return %set_variable_value($x, 1)

!procedure addComponent($part, $component, $as)
    !if %variable_exists($part)
        participant "$component" as $as
    !endif
!end procedure 

!procedure addBox2($part, $box, $colour, $data)
    !if %variable_exists($part)
        box "$box" #$colour
            !foreach $item in $data.participants
                addComponent($part, $item.name, $item.as)
            !endfor
        end box
    !endif
!end procedure 

DRAW(PART25)

!ifdef PART25
title  TESTING  (Boxes & Participants)  //Part25//
!endif

!$data={
  "participants": [
    {"name": "XYZ", "as": "xyz"},
    {"name": "RST", "as": "rst"},
    {"name": "UVW", "as": "uvw"}]
}

addBox2("PART25", "New Box", "white", $data)
@enduml

Self-descriptive example

Here is a self-descriptive example:

🎉 Copied!
@startuml
left to right direction

!$data={"parts":[
{"shape": "cloud",    "name": "id1", "colour": "#palegreen", "desc": "some text"},
{"shape": "folder",   "name": "id2", "colour": "#lightblue", "desc": "more text"},
{"shape": "database", "name": "id3", "colour": "#pink",      "desc": "even more text"}
]}

rectangle Outer {
rectangle Inner #tan as "
{{json
$data
}}
"
together {
!foreach $part in $data.parts
  $part.shape $part.colour $part.name as "$part.desc"
  Inner --> $part.name
!endfor
}
}
@enduml

[Adapted from QA-12917]