SBML Development Process

Table of Contents

An intrinsic aspect of SBML’s development has been the adoption of a participatory, community-oriented approach. In the early years of SBML, this process was highly informal. The use of SBML has grown to the point where its original, informal approach to development is no longer sufficient to meet the needs of the SBML community and the continued evolution of SBML. Beginning in 2003, the SBML Team and SBML Editors developed a more formal organization and systematic process, one that aims to be less ambiguous and subjective and more responsive to the needs of the SBML community. This page describes the plans for this SBML Development Process, and the current status of its implementation.

This SBML Development Process has been followed since mid-2008.

The process described here is an evolution of past discussions about the SBML Development Process. Previous proposals were presented at the following SBML Forum meetings: the 7th, the 10th, the 11th, and the 12th. Several other organizations served as sources of inspiration and ideas for the process described here. These include BioPAX, CellML, HL7, the IETF, the OASIS, the OMG, and the W3C.

During 2015–2016, this process was revised to remove the need for a Chair of the SBML Editors, introduce a Coordinator and a Secretary, and make other adjustments to account for miscellaneous developments over the years.

Goals and Motivations for SBML

The ultimate goal of the Systems Biology Markup Language (SBML) is to serve as a declarative representation language for computational models in biology. More precisely, the goal of SBML is to serve as a software lingua franca supporting the encoding of models such that those models can be exchanged and interpreted unambiguously by different software systems. SBML is not intended to encode the details of algorithms used to instantiate the models, nor the procedures used to process and analyze the models. Further, SBML is not linked to any specific software system.

SBML will always be available free of cost and restrictions to all users, developers, and other interested persons and organizations, whether they are academic or commercial.

Goals of the SBML Development Process

The process of SBML language development must be open, systematic, transparent and capable of producing standards that are useful to the modeling community. To this end, the goal of the SBML Development Process is to provide an explicit set of procedures and guidelines for how SBML will be systematically evolved and refined in a way that promotes the collaborative development of high-quality standards based on community consensus. The purpose of this SBML Development Process document is to provide a written description of this process.

The following are specific points that the SBML Development Process must address:

  1. The election and rotation of decision-makers involved in steering and developing SBML.
  2. The identification and articulation of goals for SBML development.
  3. The development and release of SBML specifications.
  4. The procedures and mechanisms for reporting and correcting errors and other issues in SBML specifications.

All of the procedures in the SBML Development Process will be carried out in the English language.

SBML Community Organization

This section defines who is involved in decision-making and development of SBML, how those individuals are selected, and how and when they are replaced by other individuals. For the purpose of establishing roles and responsibilities, the SBML community is first divided into the following four broad groups:

  1. The SBML Forum
  2. The SBML Editors
  3. The SBML Team
  4. The SBML Scientific Advisory Board

The divisions are not mutually exclusive; members are often part of more than one group. The following subsections describe these groups in more detail.

The SBML Forum

The SBML Forum is simply the community of people sufficiently interested in SBML that they take the trouble to observe and participate in discussions about SBML. By implication and necessity, all other subgroups of the SBML Community (i.e., the Editors, the Scientific Advisory Board and the SBML Team) are subsets of the SBML Forum. Membership in the SBML Forum is open to all interested parties.

Requirements for membership

There is only one requirement for being counted as a member of the SBML Forum: subscribing to the electronic mailing list sbml-discuss@googlegroups.com. This requirement simultaneously satisfies three goals. First, it requires nothing more from members than supplying an email address and paying attention to a mailing list. Second, it provides a means of communicating with members and disseminating information. And third, it supplies a concrete list of unique names for determining the validity of votes cast in community voting processes (discussed below in voting for Editors and general procedures for voting on issues).

The requirement specifically demands the use of the mailing list. To be counted as a member of the SBML Forum for purposes of being able to vote, individuals cannot simply monitor the list via the web interface or RSS feed. The reason is simply that there is no way of determining membership for people who use the web or RSS feed. We need a registry of members of the SBML Forum, and subscribing to the mailing list provides this. People who want to participate in community voting must subscribe to the sbml-discuss mailing list.

(Those who prefer to minimize the amount of mail they receive from sbml-discuss may wish to investigate the mailing list system’s option to receive digests. Turning on the digest mode in your personal subscription options will cause you to receive sbml-discuss postings in one-a-day batches, rather than as individual messages.)

Conduct of meetings

The primary face-to-face meetings of the SBML community are the biannual meetings organized by COMBINE (COmputational Modeling in BIology NEtwork), namely the annual COMBINE Forums and the annual HARMONY (Hackathon on Resources for Modeling in Biology). SBML-specific meetings are organized as sessions during these COMBINE meetings. The meetings are public; anyone is welcome to attend, subject to limitations of venue size. Meetings are announced on the sbml-announce@googlegroups.com mailing list with a minimum of one month lead time. The meetings are organized by the SBML Team and the SBML Editors, optionally with help from other interested parties. Records of the meeting are made available online in the SBML.org Events area. As much as possible, the SBML Team tries to take minutes or produce full recordings of meetings, in order to have a record of important decisions and discussions. These minutes or recordings are made available on the meeting web page.

Additional focused workshops may be organized at the discretion of the SBML Team and SBML Editors.

The SBML Editors

The SBML Editors are volunteers who are deeply interested in SBML and its continued success. The principal role of the SBML Editors is to organize the development, writing, and correction of SBML specifications. They are responsible for making the final decisions about SBML language design.

As will be clear from the descriptions below, SBML Editors have to be willing to invest time and effort into evaluating proposals for changes, researching the possible impact of those changes, thinking about how to implement the changes, writing new text in the SBML specification, dealing with practical matters of writing, editing, coordinating, tracking changes to documents, etc. To do this effectively, Editors must have a thorough and detailed understanding of SBML and the latest SBML specifications, as well as experience developing software or algorithms in support of SBML, and finally, excellent communication skills.

Responsibilities of SBML Editors

The following are among the specific responsibilities for SBML Editors:

  1. Track, respond to, and process error reports and requests for changes in SBML specifications. The procedure to be used by the SBML Editors for dispatching these reports is described on a separate page.
  2. Evaluate and reconcile proposals for changes to SBML and participate in writing updated versions of the SBML specifications.
  3. Participate in discussions between the SBML Editors about matters related to SBML. Most discussions take place over email (on a separate mailing list), electronic chat, telephone calls, teleconferences, and face-to-face meetings. When discussions take place outside of the sbml-editors mailing list or the issue trackers, the Editors should make an effort to keep minutes of the discussions and the reasoning that lead to specific decisions, to prevent these important work products from being lost. Minutes are listed on a separate page devoted to this purpose.
  4. Participate in discussions on the SBML mailing lists (particularly sbml-discuss@googlegroups.com).
  5. Perform research and critical thinking in support of the activities above.

The work of SBML Editors is performed on a voluntary basis and is not compensated.

Terms for SBML Editors

The following are the conditions of the terms served by SBML Editors:

  1. There is a total of 5 editors serving at any given time.
  1. Editors are elected via a majority vote by the members of the SBML Forum. The election process is described on a separate page.
  • Candidates must themselves be members of the SBML Forum.
  • The election process is managed by the Permanent Secretary.
  1. The duration of an Editor’s term is 3 years.
  • Terms begin on January 1 of the year following the year in which the Editor’s election is held.
  • Due care must be taken by the Permanent Secretary to ensure that Editors’ terms start and end in a staggered fashion, so that not all 5 Editors’ terms happen to end in the same year.
  1. Editors may serve more than one term, if they are nominated and elected at the end of their 3 year term, but must step down for a year following six years as Editor.
  2. If an Editor cannot or does not wish to serve a full term for any reason, a special election will be held to replace them as soon as possible.
  • The election process will be managed by the Coordinator of the SBML Editors and the Permanent Secretary.

Election process for SBML Editors

The step-by-step process for electing new SBML Editors is described in detail on a separate page.

Selection of the Coordinator of the SBML Editors

Each year in January, after the selection of new SBML Editors, the Editors select a Coordinator from among themselves. This person assumes the duties of organizing and chairing SBML Editor meetings. There are no restrictions on the length of time for which an individual might take this role, other than the fact that the person themselves must be a current SBML Editor.

The Permanent Secretary

The Permanent Secretary helps the SBML Editors perform their work by carrying out tasks under the Editors’ direction. The role of the Secretary can be burdensome and tedious, and should be undertaken by someone who is funded to devote the necessary time. For this reason, one of the members of the SBML Team is expected to act as Permanent Secretary, at the discretion of the principal investigator(s) of the grant(s) funding the SBML Team and core SBML resources.

The following are the responsibilities of the Permanent Secretary:

  1. Write/edit specification documents for content and appearance.
  2. Maintain and update the SBML Development Process documentation (i.e., this document).
  3. Issue calls for voting and tally the results, in cooperation with the Coordinator of the SBML Editors.
  4. Arrange meetings of the SBML Editors, in cooperation with the Coordinator of the SBML Editors.
  5. Coordinate the election of new SBML Editors each year. In the event that the Secretary is a candidate, the Coordinator will perform this task.

The SBML Team

The SBML Team strives to support the development and evolution of SBML. Team members devote significant portions of their time to SBML-related activities and are typically (though not necessarily) employed and paid specifically to do this work. The Team is chiefly responsible for the following items and activities:

  1. Maintain the resources and infrastructure supporting the SBML community and SBML development in general. The physical infrastructure consists mostly of the following:
  • The SBML.org website software, hardware, and network access, along with associated backup systems
  • Source code repositories, bug trackers, and other systems
  • Electronic forums/mailing lists for the SBML community
  • Miscellaneous hardware and software used for various purposes, such as audio-video recording of SBML workshops
  1. Arrange for the development and support of critical software, including libSBML, the SBML Test Suite, and other online facilities.
  2. Organize SBML events.
  3. Perform other support and development activities as the need may arise.
  4. Seek financial support for 1–4 above.

Members of the SBML Team are employed and not elected, and they have no specific power for controlling the direction or process of SBML development by virtue of being members of the SBML Team. (However, SBML Team members may also be members of the SBML Forum or SBML Editors, in which case, they may have the normal voting powers or influence on SBML development that result from those positions.)

The activities of the SBML Team are under the direction of the principal investigator(s) on the grant(s) funding the work of the SBML Team.

The SBML Scientific Advisory Board

Formed in 2013, the SBML Scientific Advisory Board (SAB) is composed of scientists and researchers with expertise in topics covered by SBML. The SAB provides guidance to the SBML Editors and the SBML Forum regarding the goals, features, applications, and other aspects of SBML development and use. Although the board does not exert direct decision-making power on the content of SBML, its advice carries considerable weight in in the decisions made by the SBML Editors and the SBML community as a whole.

More information about the SBML Scientific Advisory Board and its members is available on a separate page.

SBML Development Procedures and Guidelines

This section describes specific procedures and guidelines used by the SBML community for the continued evolution of all aspects of SBML.

General Procedures and Guidelines

Public participation

The SBML effort relies crucially on the participation of interested groups and individuals. The project is not as decentralized as (for example) the Apache Project largely because of the management needs that arise from relying on government grant funding to support core work on software, the website, meeting support, specification development, etc. However, beyond that, the SBML effort strives to be inclusive and encompassing of community involvement, and works by building consensus. Newcomers are viewed as volunteers who genuinely want to help and are welcomed cheerfully.

Communication and transparency

SBML has been, and continues to be, developed in collaboration with an international community of researchers and software developers. As with many other projects, the primary mode of interaction between members is electronic mail. Discussions about SBML language development take place on sbml-discuss@googlegroups.com; discussions about SBML software and interoperability experiences take place on sbml-interoperability@googlegroups.com.

As a general principal, discussions that have an impact on SBML development are conducted in public as much as possible, either at workshops or over one of the SBML mailing lists. All messages to the mailing lists are publicly archived, with links at http://sbml.org/community/forums. The public discussions and archives improve transparency, provide a public record of arguments and reasoning, and stimulate the broader community. Written text also helps bridge language barriers, because written text is often easier to understand than speech for non-native English speakers.

The records of discussions and materials presented and produced at the various SBML workshops (the Forums, Hackathons, and focused workshops) are made publicly available from the SBML.org website. The SBML Team is responsible for organizing, collecting and managing the workshop materials.

A public issue tracking system is available for anyone to report issues with SBML specifications, request feature changes, and request packages for SBML Level 3 development. The history of issues and records of actions are publicly available to support transparency and accountability on the part of the SBML Editors and SBML Team.

The sources to all SBML specification documents, as well as other related documents, are made freely available from the SBML repository in the /trunk/project subdirectory.

Achieving consensus

Many questions that initially appear to be a matter of opinion are ultimately resolvable on the basis of rational, technical reasoning. This is one reason why public archives of communications (such as the SBML mailing lists) are so valuable: they provide a trace of the reasoning (or at least the discussions) behind various technical decisions during SBML development.

In situations where a decision appears to have no obvious right or wrong answer on technical grounds alone, the SBML Editors may initiate a public vote on the matter. Public votes can be conducted in one of two ways.

  1. For minor issues, the SBML Editors may describe the topic during an SBML Forum meeting and call for a vote to be conducted via a show of hands. What constitutes a minor issue is left to the discretion of the SBML Editors.
  2. Major issues must be taken to a full community vote. This must be conducted using an electronic voting system, with the topic and call-for-votes announced on the sbml-discuss@googlegroups.com mailing list. The issue must be described in detail and in as neutral a fashion as possible, to avoid biasing the vote. Voting will be open only to the registered members of the sbml-discuss@googlegroups.com mailing list. (The latter requirement is necessary to allow a minimal level of verification of votes cast, for example to prevent multiple anonymous votes by the same person.)

Language Development Process

Most of the activities described below are organized and directed by the SBML Editors. However, other members of the SBML Forum are free to raise questions or concerns about any aspect of the process and SBML itself. One of the most important aims in SBML development is to reach consensus among a majority of SBML users and developers; thus, feedback and dissenting opinions must always have a voice.

SBML Levels, Versions, and Releases

Major editions of SBML are termed levels and represent substantial changes to the composition and structure of the language. Models defined in lower levels of SBML can always be represented in higher levels, though some translation may be necessary. The converse (from higher level to lower level) is sometimes also possible, though not guaranteed. The levels remain distinct; a valid SBML Level 1 document is not a valid SBML Level 2 document, and likewise, a valid SBML Level 2 document is not a valid SBML Level 1 document.

Minor revisions of SBML are termed versions and constitute changes within a level to correct, adjust, and refine language features. Changes in versions of a level do not introduce large architectural or conceptual changes to SBML; such large changes are only made between SBML levels.

Specification documents inevitably require minor editorial changes as their users discover errors and ambiguities. As a practical reality, these discoveries occur over time. In the context of SBML, such problems are formally announced publicly as errata in a given specification document. Borrowing concepts from the W3C, we define SBML errata as changes of the following types: (a) formatting changes that do not result in changes to textual content; (b) corrections that do not affect conformance of software implementing support for a given combination of SBML level and version; and (c) corrections that may affect such software conformance, but add no new language features. A change that affects conformance is one that either turns conforming data, processors, or other conforming software into non-conforming software, or turns non-conforming software into conforming software, or clears up an ambiguity or insufficiently documented part of the specification in such a way that software in which conformance was once unclear now becomes clearly conforming or non-conforming. In short, errata do not change the fundamental semantics or syntax of SBML; they clarify and disambiguate the specification and correct errors. These errata are corrected in new releases of the SBML specification. Each release is numbered with an integer, with the first release of the specification being called Release 1.

The SBML Editors announces new levels, versions, and releases of SBML specifications on the sbml-announce@googlegroups.com mailing list.

Process for SBML Level 2

With the introduction of Version 4 in late 2008, SBML Level 2 entered a maintenance mode. Refinements and error corrections continue, and on rare occasions an update is released (as it was with SBML Level 2 Version 5 in 2015); however, serious SBML development has instead moved on to SBML Level 3 (see the next section below).

The development process for SBML Level 2 is the following:

  1. Problems, requests, and other issues must be reported using the SBML issue tracker. This system assigns a tracking number to each issue and provides a means of associating a trail of actions and discussions with the issue. Reports may be logged by anyone at any time.
  2. The SBML Editors follow a specific procedure for evaluating and addressing the issue report.
  • The Editors will inform the person who logged the initial report about the status of the discussions and decisions for action on the issue.
  • If the issue does not have a clear resolution path, the Editors may bring up the issue with the SBML Forum (either in face-to-face meetings or on the electronic mailing list) and request broader community input.
  1. After a period of time, an accumulation of issues may warrant the development of a new release of Version 5, or possibly a new version of Level 2 altogether. This decision, and the timing, is left up to the discretion of the SBML Editors, who must evaluate the significance of the issues in the SBML specifications against the impact on software developers.
  • Releases have less impact on software developers since releases introduce no substantive changes to the SBML Level 2 Version 5 language; however, a new release still takes time and effort to develop, and potentially has some implications for software developers.
  • As a general principle, additional versions of SBML Level 2 after Version 5 should be avoided unless truly important issues arise.

The specification documents for SBML Level 2 are maintained in a source code management system (the SVN repository for SBML), thereby providing detailed document change history and versioning. For Level 2, the specific subdirectory is /trunk/specifications/sbml-level-2. The documents and revision information are made public.

Process for SBML Level 3

SBML Level 3 is modular, in the sense of having a defined core set of features and optional packages adding features on top of the core. This modular approach means that models can declare which feature-sets they use, and likewise, software tools can declare which packages they support. It also means that the development of SBML Level 3 can proceed in a more modular fashion. SBML Level 3 Version 1 Core (Release 1) was released on 6 October 2010; development of software support for the Core and development of Level 3 packages is under way.

The development process for SBML Level 3 is described in detail on a separate page.

Translations

Translations of this page are available for the following languages. We gratefully acknowledge the efforts of the individuals who have kindly undertaken the translation: