SVG Based Diagram Editor/Viewer for Requirements Engineering

...a path to a SVG Wiki

Dr. Laurent Fournier

The author is Software Engineer at Rockwell Collins France. He is working on software development methods and tools for avionics critical and industrial applications. He is investigating Web based technologies like Mozilla XUL,... to achieve requirements of the growing Model Based Engineering. In such context, SVG is one of the best candidates to handle 2D graphics.


Requirements Engineering (RE) is a domain where actors are requesting the ability to capture, share and verify more or less formalized artifacts within graphical 2D diagrams. We present in this paper a prototype web tool/service, part of the next coming open-source project Formose (FOrmal Requirements Modelling in an Open-Source Environment). This tool tries to fill gaps detected in the today tool offering for RE. It is a full SVG application using Graphviz service for layout and Git for version management. The main principle is to provide in SVG for graphics editing what Wiki use to provide for text editing in order to make easy nested diagrams. These diagrams are both editable following a simple text syntax or buildable with a SVG graphic interface. We also discuss the need in Requirement Engineering for a mechanism to insure integrity of connected diagrams in documents to avoid transformation from SVG to images. The paper is concluding on a demonstration of the early prototype tool/service.

Table of Contents

Requirements Engineering
Tools offering for RE
Word processors, spreadsheets and drawing tools
Database Oriented Tools
Traceability tools
UML editors
Other tools for RE
A small SVG tool for a Web service
The choice of SVG
The layout engine
The glue
Text and Graph
Nested diagrams
How to avoid dead (non SVG) diagrams
Demonstration and conclusion

Requirements Engineering

Requirements Engineering (RE) [REF3] is the activity aiming to capture, manage, verify and trace all the expectations of a customer for designing a product or a service within technological and business constraints. This is a long chain between the first ideas of the marketing, engineering brainstorming sessions (use of napkins diagrams),... to the definition of coding non ambiguous statements for design engineers for doing the right product, not another one.

This activity makes intensive use of various technical documents containing linked requirements.

Showing requirements and their links in a partial graphs (diagrams) seems to help in the engineering task.

One main challenge of Requirements Engineering is in sharing these requirements among the project team and managing changes all over the development cycle. In particular it is required by standards (DO-178B [REF6] for avionics software) that all functional tests on the system to build have to trace all the requirements.

Some methodology for RE has been defined and we are mainly focusing on KAOS [REF2]

A strong research topic remains to capture requirements and define them as some Linear Temporal Logic formulae, first step to apply Formal Methods to verify or generate software.

This will be the effort of the Formose (Figure 1) project, involving several French Computer Science laboratories on the subject. The Event-B language is proposed to help in this process.

Our interest here is just on a small tool that may facilitate requirements capture. All formal transformations are allowed in batch or real-time on the server side.

This SVG editor/viewer is a secondary task for the Formose project but we believe that providing simple utility tools soon can help to get industrial users cases and makes users motivated to follow a stronger engineering process.

Diagram Formose AGENT Formose FOrmal Requirements\nModelling in an Open-Source\nEnvironment FOrmal Requirements Modelling in an Open-Source Environment Formose->FOrmal Requirements\nModelling in an Open-Source\nEnvironment

Figure 1. The Diagram Tool

Tools offering for RE

The today tools offering for Requirements Engineering does not satisfy our main needs and the choice is more a matter of habits and background preferences than directed by rational.

Let us browse the families of tools currently used for Requirements Engineering.

These are the most used tools for capturing requirements. Open-source Suite ( or not (Microsoft Office including Visio) are general purpose applications not easy to customize in order to follow a given methodology.

The individual centric design of such tools makes them hard for sharing requirements within a team. Even with a version managing system (cvs, svn, hg, git,...), user can manage change only at the granularity of a file, that is a document, not at the level of the requirement itself.

The leading tool for managing requirements is DOORS (IBM) that is more or less a classical database for storing requirements.

Very suited for sharing thousand of requirements, this family of tools can build traceability matrix and manage well revisions. They raise an undesired concurrency with traditional version managing systems used for other artifacts (source and test code).

These are poorly adapted for diagrams editing and heavy to use in the every day work.

DOORS database is proprietary, meaning it's not SQL. Sending formalized Queries is not easy.

The family of traceability tools is dedicated to directly find uncovered requirements, build covering matrix and make impact analysis.

Examples are Geesoft Reqtify or Polarion Requirements 2.0. These tools are usually not diagram oriented and address only a part of the Requirements Engineering task.

UML diagrams are mostly used for the design phase and are partially adapted for Requirements Engineering.

For example, handling alternative goals, obstacles and more widely Risk Management is not possible in UML, SysML nor AADL.

There are many of such tools. We can site the Open-source Topcased initiative. If an Eclipse environment may be basically installed for software developers, it is less common for every project team members involved in RE.

Another interresting approach is the yUML [REF10] web service. Nested diagrams, SVG editing/publishing and version management are missing.

Objectiver™ is the closest tool to follow the KAOS method. As a non Open-source tool, it lacks to be used widely.

This is the solution for sharing requirements. Modern Wikis offer full traceability for version management. Every one has a web application to install.

However, the support of diagrams is secondary. They are mostly text oriented. A macro usually transforms a text description into one image, but we did not found a Wiki supporting nested vector diagrams (viewing and editing).

At some early stage, Mind-mapping (Free-mind) tools are used. Not completely Web oriented, the diagrams do not follow a RE method.

An issue, a bug or an evolution request can be a requirement, the reverse is not true and many requirements cannot be managed by problem trackers. These tools (Bugzilla, Trac, ...) are process oriented usually with a nice a Web interface.

Facing our needs for RE and browsing the today tool offering, the development of a new tool is requested. That is why inside the Formose project, it is going to be provided an Open-source, SVG diagram editor an web service to support the KAOS method and Formal Verifications.

A small SVG tool for a Web service

SVG was the natural solution for doing 2D graphics on the Web. Most web browsers now support the XML syntax of SVG without any dedicated plug-in.

SVG code can be directly inserted in HTML making graphics well integrated with text. The code is relatively small and not dispatched in multiple files like for external elements (images). The best rendering quality is achieved with the vector nature of SVG. Also, to reference external graphics, HTML provides the <object> tag with its "data" attribute for linking SVG object, like it is done with the <img> tag and "src" attribute for images (gif, png, jpeg,...).

Finally, event handlers are operational in SVG, so we realized that all the HTML code can removed from our application!

In practice with Firefox browser [REF7], it remains in our tool code only two HTML objects embedded in the SVG <foreignObject > tag:

  • <textarea> for multiline text editing,

  • <input> with the "readonly" attribute to get text pre selection.

The SVG Tiny 1.2 [REF1] TextArea tag and SVG Text selection are currently not supported by Firefox but we hope to have these issues fixed soon to be able to write a pure SVG application, with no HTML code.

It is not acceptable to rely on the user for placing diagram nodes on a page. First, the end user must concentrate on the requirements, the content of each node and on the links, the diagram edges, not on the graphics attributes. Second, we want a deterministic layout. For a given textual description, the rendering has to be always identical.

The tool uses Graphviz [REF4] "dot" layout engine, but we may switch to another Open-source processor.

The "dot" tool exports graph in SVG (-tsvg option). Our tool uses an XML parser to provide two modified features:

  • a more flexible custom node shapes than the one provided by the "dot" language, all the KAOS diagram elements are in the palette,

  • auto line break because the "dot" language requests to insert explicit '\n' characters in node label. Currently, the dot SVG output code from "dot" does not use the <textArea> tag specified by SVG Tiny 1.2.

The application uses CSS styling facilities on the SVG code. It is planed to provide some skinable rendering. Profesional Graphic Designers may be helpful on the project.

The dynamics needs JavaScript on the client side. Usage of jQuery is under investigation.

The HMI and the current diagram are updated asynchronously by common AJAX requests.

Diagrams links are xlink.

On the server side, the glue language for building SVG code is Python. Any other language could have been used instead.

The current prototype is someway small (500 lines of JavaScript, 500 lines of Python and few lines of CSS) and available with GPL v2 license.

Text and Graph

RE people are not able to directly write the SVG code of the diagrams and it is not desirable. They request both for editing (see Figure 2):

Editing modes

Figure 2. Editing Modes

Providing only one would raise frustrations. We recommend looking at the very powerful svg-edit [REF8] project that also enable to edit the SVG code.

The Application Specific Language used shall be suitable for Requirements Engineering and we start with a dialect of the Graphviz "dot" language. It is a task of the Formose project to define completely this language in order to support Formal Methods.

Compare the two statements to produce the diagram Figure 3.

The following short description is intuitive:

B:Agent A:Goal A->B B->C A->C

The generated XML SVG code is becoming nearly unreadable:

<?xml version="1.0" ?>
<svg xmlns="" viewBox="0.00 0.00 89.00 188.00" xmlns:xlink="" 
  height="188pt" width="89pt" >

<defs><radialGradient id="grad" cx="0%" cy="0%" r="90%">
 <stop offset="0%" stop-color="#FFF"/><stop offset="100%" stop-color="#DDD"/>

 <g transform="scale(1 1) rotate(0) translate(4 184)" id="graph0" class="graph">
  <polygon style="fill:white;stroke:white;" points="-4,4 -4,-184 85,-184 85,4 -4,4"></polygon>
 <g id="node1"><title>B</title>
   <g transform="translate(27, -90)" stroke-width="1" stroke="gray" fill="none">
    <polyline fill="url(#grad)" points="-20,-18 -30,-1 -20,18 -9,17 20,18 30,1 20,-18, 0,-19 -20,-18"/>
    <text class="ro" x="-19" y="-14" fill="gray" stroke-width="0" style="font-family:Arial;font-size:2pt;">AGENT</text>
  <text y="-86.025" x="27" style="font-family:purisa,cursive;font-size:14.00px;" text-anchor="middle">B</text> 

 <g id="node5"><title>C</title>
  <g transform="translate(54, -18)" stroke-width="1" stroke="gray" fill="none">
   <ellipse fill="url(#grad)" rx="27" ry="18"/></g>
   <text y="-14.025" x="54" style="font-family:purisa,cursive;font-size:14.00px;" text-anchor="middle">C</text>

  <g id="edge4" class="edge"><title>B->C</title>
   <path style="fill:none;stroke:grey;" d="M34,-72C37,-64 40,-54 44,-45"></path>
   <polygon style="fill:grey;stroke:grey;" points="47,-46 48,-36 40,-43 47,-46"></polygon>

  <g id="node2"><title>A</title>
   <g transform="translate(54, -162)" stroke-width="1" stroke="gray" fill="none">
    <path fill="url(#grad)"  d="M-24,-18 -27,-3 -30,18 -14,17 24,18 27,-3 30,-18 2,-19 z"/>
    <text class="ro" x="-22" y="-14" fill="gray" stroke-width="0" style="font-family:Arial;font-size:2pt;">GOAL</text>
   <text y="-158.025" x="54" style="font-family:purisa,cursive;font-size:14.00px;" text-anchor="middle">A</text>

  <g id="edge2" class="edge"><title>A->B</title>
   <path style="fill:none;stroke:grey;" d="M47,-144C44,-136 41,-126 37,-117"></path>
   <polygon style="fill:grey;stroke:grey;" points="40,-115 33,-108 33,-118 40,-115"></polygon>

  <g id="edge6" class="edge"><title>A->C</title>
   <path style="fill:none;stroke:grey;" d="M57,-144C59,-134 62,-120 63,-108 64,-92 64,-87 63,-72 62,-64 61,-54 59,-46"></path>
   <polygon style="fill:grey;stroke:grey;" points="62,-45 57,-36 55,-46 62,-45"></polygon>

Diagram B AGENT B C C B->C A GOAL A A->B A->C

Figure 3. Simple diagram example

Nested Diagrams

One of our main requests for the tool is to be able to write nested diagrams.

Traditional Wiki makes possible to edit and browse virtually infinite tree (graph) of HTML pages from any word (hyperlink). But the atomic element for a diagram is the node (might be edge also) rather than a word. Clicking on a node shall enter the children diagram if exist or create a new one if it does not already exist.

Because nodes are SVG objects, thanks to xlink for browsing in SVG nested diagrams, HTML is not needed anymore.

As text pages for Wikis, the user sees nested diagrams as pages whether or not a database or a file system is used on the server side.

Unlike most UML tools that store nested diagrams in the same file, our tool always associates the current diagram with the current description. This way, the user works on a limited number of elements (nodes and text) at the same time. Diagrams are simply linked with their diagram id

Diagrams are given a unique id but the user has never to create it. He or she can reuse this generated diagram id as a shareable short URL. Other users can then access to the same diagram and also to the children's diagrams. Changing the content of a diagram does not change its diagram id.

Persistance and history management of all the diagrams are automatically managed by Git [REF9] on the server side. We also use a Berkeley database [REF5] to maintain hash tables that store diagrams links with diagram id as key. This solution has far a better performance than SQL like Database System.

Another id is introduced, called revision id. This id is the sha1 signature given by a a Git commit. Social editing with Git for requirements management is today not completedunder developement. The idea is that the diagram id plays the role of a file name (a git blob) and the diagram description corresponds to the file content. Git commands are transparent for the user but it is still under investigation at which frequency the tool has to make commits during diagram editing.

The revision id (or Git commit) is important for two reasons:

The benefits of Git will be valuable by cloning the diagram servers and making Git push/pull possible.

How to avoid dead (non SVG) diagrams

The architecture of the tool is clearly 'client-server(s)'. A server can recover a diagram for a client with a short url (the diagram id) or from a full textual description and it renders the SVG code in real time. More and more documents are using resources on some intranet server or directly on the WWW. These "connected" documents can be short (to the extreme, as short as an URL), but unfortunately no mechanism checks that linked resources won't change. This behavior is clearly not requested for Requirement Engineering. So people use to export their documents to standalone format like PDF and SVG code is transformed into dead images.

In many cases, this transformation is justified by the request of preserving document integrity, not by the constraint to be connected.

To avoid such transformation that produces in worse case poor images, reader tools have to interpret SVG, making them Web browsers, so possibly with the facility to take resources from any http server. Then it makes sense to keep server doing part of the job (graph generation with Graphviz, storage with a Berkeley database, version management with Git).

For nested diagrams, a simple rule shall insure integrity:

if a diagram is referenced by a revision id (not with a HEAD keyword), then all possibly linked diagrams, parent or children shall use revisions id links.

This rule applies recursively. Obviously, in edit mode, one cannot reference a revision id diagram.

Document readers has just to check that all linked resources are frozen to insure integrity of the connected document and have nice SVG rendered diagrams. It is up to the server administration to provide the service with a good quality to have the document content anywhere anytime.

Our proposal is to extend integrity checking in the browser code itself. Exactly as today a browser warms users with secure https connections, we can imagine some "integrity flag" saying that the current document (and its links) are coming from a revision managing system (i.e. Git) for concurrency editing and insures that the content will never change. The URL is in some way a key of the recursive data content hash. More, Digital Signature of authors may be validated and evolutions time stamped by trustable servers.

The need for PDF and SVGtoPDF transformation will decrease.

Let us see Figure 4 if SVG Open proceedings generation tool is connected to the Net.

Figure 4. Linked diagram

Demonstration and Conclusion

The diagram service is available for Firefox browser at this address just for testing. The kick-off meeting for the Formose project is scheduled for the end of 2010 year.

We are taking opportunity of the SVGOpen 2010 to call for contribution of SVG experts, graphics designers to this Open-source project.

By the time a full forge is installed for the development project, I will be your focus point;