The POEM Format for OPM

POEM is a text-based data format for OPM graphs which aims to be easy and succinct to write by hand. It is particularly intended for creating graphs to test software tools with, or to generate examples and illustrations. POEM does not attempt to allow everything expressible by the OPM specification to be expressed, just some common usages. At the moment it is fairly limited, though we intend it to become more expressive over time. Below, we explain how to construct a POEM file.

Processes

Nodes (artifacts, processes and agents) are denoted in POEM by different styles of bracket. With square brackets, we denote a process. The text within the brackets is the label of that process (i.e. the value of an opm:label annotation). If the label is more than a single identifier (sequence of digits and/or letters), then it should be given in quotes.

[wrote]
["ran on cluster"]

Agents

Agents are represented in the same way as processes except using angle instead of square brackets.

<Simon>
<"Simon Miles">

Artifacts

Artifacts in POEM are (currently) always in the context of a used or wasGeneratedBy edge, and therefore has a role in the related process. An artifact is denoted by round parentheses containing two elements, separated by a space: the role name and then the artifact label (either an identifier or quoted string as for processes).

(written article)
(writtenOn "sheets of paper")

Edges

POEM currently allows used, wasGeneratedBy, and wasControlledBy edges to be expressed. A POEM file is a series of in-out assertions, each describing one process, including what artifacts it used and generated and what agents controlled it. An in-out assertion starts by listing the artifacts used and agents controlling the process, followed by the process itself, then the artifacts it generates, terminating with a full stop/period. It may be helpful to use indentation to distinguish the used from the generated artifacts.

<Simon>
(writtenOn "sheets of paper")
  [wrote]
    (written article).

There can be as many artifacts or agents as is desired, but only one process.

Annotations

Nodes (artifacts, processes, agents) can be annotated. An annotation is denoted by a plus, the annotation key, an equals, and the value in quotes. The annotations of a node immediately follow that node, and are of any number.

(written article)
  + title = "The POEM Format for OPM"
  + length = "2 pages"

Accounts

An account can be represented in POEM by putting curly braces around a set of in-out assertions. Accounts may be nested within other accounts, by putting one set of curly braces inside another. This is demonstrated below.

{
<Simon>
(writtenOn "sheets of paper")
  [wrote]
    (written article).

{
(uncompressed image)
  [compressed]
    (compressed zippedImage).
}

}

References

Following the above, an OPM graph of any size can be represented. However, it would be largely disconnected: the artifacts and agents are unique to each in-out assertion. To connect up in-out assertions, so that, for example, an artifact can be generated by one process can then be used by another, we use references. These are not part of OPM, but simply part of the POEM serialisation.

A POEM reference is denoted by a star followed by an identifier. When a reference is placed immediately following an artifact or agent, that artifact or agent can then be referred to in in-out assertions later in the file. To say that an artifact/agent in an in-out assertion is the same as a node in a previous in-out assertion, replace that node's label with the reference.

<Simon>*1
(writtenOn "sheets of paper")
  [wrote]
    (written article)*2.

<*1>
(beforePublishing *2)
  [published]
    (afterPublishing "article in publication").

-- SimonMiles - 03 Sep 2010
to top