SBML Development Process for SBML Level 3
The overall SBML Development Process is detailed on a separate page. The present page describes specific aspects of the process that concern the development of SBML Level 3, particularly SBML Level 3 packages.
This process description was revised and updated in January, 2012.
Principles for development of 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 permits the development of SBML Level 3 as a whole to proceed in a modular fashion. The development process for Level 3 is designed around this concept.
Any member of the SBML Forum may propose the creation of a package for SBML Level 3. Whether this proposed package is ultimately accepted as being a desirable addition to the set of SBML Level 3 specifications is a decision made collectively by a majority vote of the SBML Forum. The decision-making process is implemented using electronic voting organized by the SBML Editors.
Packages take significant time and effort to develop. It would be unreasonable to require the production of a complete specification for a package before the SBML Forum is asked to vote on whether the package is even considered worthwhile and appropriate for SBML Level 3. Therefore, the development of packages is divided into two main stages:
This separation means that proposals for packages may be produced at relatively low cost in terms of effort, time and other resources. As explained below, the specification stage requires more effort, including software implementations. Only after the purpose and general outline of a proposed package are accepted does the full specification need to be produced.
Developers of SBML Level 3 packages are generally free to make decisions they feel are most appropriate for their packages. Nevertheless, some basic ground rules are important so that development of SBML packages and the SBML Core can take place in a reasonably coherent fashion. The following general principles for Level 3 packages are intended to provide basic guidance to package developers. There are three types: architectural principles, structural principles, and community principles. Collectively, they constitute the basis for voting by the community on the suitability of a package at different stages in its life cycle. These principles, and only these principles, will be used to judge the acceptability of packages. The principles have been drawn from the history of SBML, from the specification documents for the SBML Levels 1–3 Core, and from discussions between the SBML Editors and the SBML community at large.
This group of principles concerns the purpose and general orientation of a package. They are also used as the basis for voting on a package proposal (one of the stages of the SBML Level 3 Development Process for Level 3 packages). All package proposals and specifications must be formulated with these points in mind:
- Utility: A package must concern itself with a subject or problem area that enough SBML users find useful to sustain interest in the package.
- Biological orientation: The overall aim of a package must be to support the description of biological processes and phenomena. (However, this does not preclude supporting the description of other phenomena, if doing so serves the overall aim.)
- Coherence: A package must extend SBML in a way that follows naturally from Level 3 Core and other packages, reusing concepts as appropriate and integrating new concepts into the existing frameworks in a reasonably natural manner.
- Orthogonality: As a general goal, SBML Level 3 and all its packages must strive to encode every given concept only once. Data and concepts should not be duplicated in multiple components or packages, except in extenuating circumstances or when a package is intentionally proposed as a replacement for another package.
If the developer(s) of a given package believe(s) that the package should not or cannot follow one or more of these principles, they must provide a compelling argument for their case.
Once a package proposal has been accepted and work has begun on a specification for the package, the following additional guidelines must be followed:
- Effective abstractions: A package must provide ways to store data using the most useful and general abstractions possible, to facilitate the exchangeability of models between different mathematical frameworks, different software tools, and possibly even different modeling paradigms.
- Implementability: A specification for an SBML package must be described clearly enough that readers can understand how to implement software support for it.
- Explicitness: All of SBML Level 3, including packages, must avoid defining attributes and elements with implicit default values that may be omitted from a syntactically-valid model definition. All non-optional attribute and element values must always be written out explicitly.
- Note that this is not the same as inheritance. Attributes are allowed to be optional with no default values, and a specification can define how a missing value is inherited from another attribute elsewhere in the model. (For example, the Model attributes for units in Level 3 Core provide values that can be inherited by other SBML constructs.)
- Validity after reduction: The reader of an SBML model must be able to ignore constructs in the namespace of a package used in the model, and the result should still be a syntactically valid SBML model. This model may or may not give the expected mathematical results when being simulated, but a reader must be able to read the Level 3 Core parts of the document without encountering syntactic errors.
- This principle has numerous implications, among them being the following:
- The model cannot refer to non-Core objects from within Core objects. For example, it cannot use the Core InitialAssignment construct to assign to the id of an object that is defined in a package being used in the model. (If it did, and the package was stripped, then the initial assignment would refer to an identifier that no longer existed in the model. This has been nicknamed the "dangling identifier" problem.)
- MathML content within Core elements cannot refer to entities outside of SBML Core constructs. For example,
<ci>elements inside the
<math>of Core constructs cannot reference identifiers of elements defined by package constructs. (The reason is the same as for the previous point: if the package was stripped, then the object corresponding to the identifier would no longer exist in the model.)
- A package definition cannot redefine the MathML subset permitted in Core constructs. (This may appear to be a serious limitation, but in practice, it can be overcome. One approach for extending the mathematical constructs without redefining the Core MathML subset is for a package to extend FunctionDefinition. This has the advantage of allowing a model to define a default result returned by the regular Core part of the FunctionDefinition when the package is ignored.)
- This principle has numerous implications, among them being the following:
The implications of the principles above, especially validity after reduction, can be subtle and fundamental. The SBML Core specification explicitly ascribes specific semantics to most core constructs, especially species, compartments and reactions. SBML "species" are assumed to be pools of entities considered indistinguishable from each other, with their essential property being the quantity of the species. The attributes of species in SBML Level 3 Core, such as
substanceUnits, are oriented towards this physical interpretation of species. Similarly, SBML "reactions" are assumed to be processes that change the quantities of species. An SBML Level 3 package may reinterpret or extend the semantics of these constructs, but the way it does so must preserve the validity after reduction principle. There are two alternative ways that this can be achieved:
- The "no new MathML container approach": The simpler approach is to maintain the data type and units associated with Core object classes extended by a package. That is, the semantic requirements of using an identifier in MathML extend only so far as to require that the identifier continue to be of the same data type, and the units of measurement associated with the identifier should also match. For example, the identifier of a species is associated with a numerical value and therefore any alternate interpretation of a species must also associate the identifier with a numerical value—in this approach, reinterpreting a species as having a boolean value would violate the validity after reduction principle on the grounds that the identifiers of such modified species would no longer represent quantities.
- The "separate MathML container approach": This more complex approach is necessary if a package needs to redefine a construct in such a way that it changes the data type of the identifier, or if the package needs MathML constructs that extend the subset of MathML defined by SBML Level 3 Core. The approach rests in confining the package's alternate interpretation of the SBML constructs (or classes of objects derived from SBML Core constructs) to constructs only defined by the package. This may require (for example) the definition of separate MathML container elements within which objects with those alternate semantics can be used. An example may help clarify this. Suppose the package needs to reinterpret a species as something that has a state or condition, and reactions as processes that change the state or condition. The package would have to define a subclass of reactions and provide it with a mathematical formula in parallel with the
kineticLawwhere the identifiers of these extended species could be used without violating the validity after reduction principle.
SBML only exists to serve common purposes shared by a community of users. To serve those purposes, it must continue to be developed with input from the SBML community. This leads to one simple but important principle:
- Community involvement: The development package must proceed with opportunities for involvement by, and contributions from, other interested members of the SBML community.
Package proposal development
In the following text, "proposer(s)" refers to individuals or groups who propose a package for SBML Level 3.
The pre-proposal stage
- Individuals or groups who wish to propose a package for SBML Level 3 must first consult the Level 3 activity area in the SBML.org Community Wiki and check whether a similar package has already been proposed or is already in development.
- If a package with similar goals has already been proposed, the proposer(s) should evaluate the details of the existing proposal and compare it to their own plans.
- If the existing proposed package can satisfy the proposer(s)'s needs, then it is probably more worthwhile for the proposer(s) to join the existing package's development efforts. By doing so, they can save themselves considerable effort, and perhaps also influence some of the details of the ongoing effort to better suit them.
- If, however, the proposer(s) judge(s) the existing efforts to be limited or unsuitable, the proposer(s) should proceed to step 2 ("The proposal stage") described below.
- If no existing activity in Level 3 is similar enough to the new proposal, the proposer(s) must proceed to raise the topic on the sbml-discuss mailing list and ask for community input about whether proceeding with a proposal is worthwhile. (Motivation for this step: functionality may often be achieved in more than one way, and the SBML community may already have discussed developing a given feature through a different approach. Therefore, before spending effort on a detailed proposal, it is worth first checking with the rest of the community to make sure there is enough interest.)
The proposal development stage
- Using the SBML issue tracker with the category "SBML Level 3 package requests" (see screenshot at right), the proposer(s) must log their intention to develop a proposal for a Level 3 package. This will provide a tracking number and a place for the SBML Editors and other people to record comments related to the topic.
- Proposers must develop their Level 3 package proposal using the Level 3 Package Proposal Template.
- There is no prescribed file format for Level 3 proposals; the template only prescribes the content that should be provided. Many proposals are written as wiki pages in the SBML.org Community Wiki, but they could equally be written as LaTeX documents or another format.
- Proposers are invited to store their proposals in the SVN repository for SBML. Interested persons should contact the SBML Editors for guidance and assistance in doing this.
- There are no length requirements for a package proposal. The proposal should be long enough to allow the SBML community to assess and vote on the proposal as described below. Some packages may be simple enough that a few paragraphs suffice; others may need more detailed explanations. In all cases, authors of package proposals are advised to pay particular attention to giving clear explanations of (i) the needs that the proposed package is meant to address and (ii) the approach being proposed to address those needs.
- After writing the proposal according to the template, the proposer(s) should ask the Chair of the SBML Editors to add a link to the proposal in the Level 3 area on the SBML.org Community Wiki. The link should be placed on the appropriate topic page (if one exists) or added to the table of activity areas.
- Next, the proposer(s) must notify the SBML community about the proposal by posting on the sbml-discuss mailing list.
- A period of discussion will ensue. The proposer(s) should engage in a period of requesting comments and replying to them. During this time, the proposer(s) should modify the proposal if needed in response to issues raised by other people.
The proposal voting/selection stage
- The period of discussion described in step (5) of the proposal development stage must last a minimum of 2 weeks. Any time after the minimum period of discussion, either the proposer(s), or the SBML Editors, can request a formal vote on whether the proposal should be pursued further.
- The request can be made by posting a request on sbml-discuss or by contacting the SBML Editors directly.
- The SBML Editors must respond publicly in a timely fashion to the request.
- The timing and other conditions for issuing the voting survey are left to the judgment of the SBML Editors.
- The SBML Editors will construct a survey for the purpose of holding a public vote on the proposal. The voting form will allow members of the SBML community to indicate one of 4 choices: (i) accept: the proposal addresses a need that SBML should cover, and it is clear the proposed approach follows the stated principles; (ii) reject: the proposal does not address a need that SBML should cover; (iii) revise: the proposed approach either does not follow the stated principles, or there is insufficient information to tell if it does; (iv) abstain: the voter does not wish to take a position or cannot fully assess the proposal as given.
- The Chair of the SBML Editors will issue the call for votes. A minimum period of 2 weeks will be given before the vote is closed to give the SBML community sufficient time to evaluate the technical aspects of the proposal. At the Chair's discretion, a longer period may be chosen if it is warranted.
- At the end of the voting period, the SBML Editors will report the outcome publicly. The results will be assessed according to the formula described in the section titled "Formula for assessing the outcome" below.
- Unless the outcome of the previous step is reject, the SBML Editors will form a Package Working Group (PWG) consisting of at least one of the package proposers, at least one SBML Editor, and any other members of the sbml-discuss mailing list who request to be part of the PWG. The Editors will further create a mailing list that will serve as both a basic notification/communication mechanism as well as a membership list for the PWG. The Editors will announce the formation of the PWG on the sbml-discuss mailing list, and optionally via other means.
- The mailing list should have the name
labelis the short-form label for the package. (Example:
sbml-multi.) If technical reasons prevent using
sbml-label, the list should have the next-best alternative name that the purpose of the list clear.
- The grandfather clause detailed in Special case #1 applies.
- The mailing list should have the name
Contents of the voting form
The voting form for package proposals will reflect the principles described in the section on architectural principles. To encourage thoughtful and thorough consideration of the proposed packages with respect to those architectural principles, the form will request voters to address the points individually, and ask for an overall assessment as a separate question. The following is an outline of the basic content of the voting form:
In addition to the above, the voting form will include comment boxes that allow voters to provide more detailed feedback about the proposal and why they voted they way they did.
Formula for assessing the outcome
To assess the outcome of the vote, the SBML Editors will use only the question titled "Overall assessment of the package proposal" in the form described above. The formula to be used is as follows:
- For the decision to be accept, 50% or more of the non-abstaining voters must have chosen the accept option.
- For the decision to be reject, more than 50% of the non-abstaining voters must have chosen the reject option.
- Any other outcome is deemed equivalent to revise.
Resubmission of proposals
Any proposal that is not approved by the community (where the majority of non-abstaining voters did not vote Accept) may be rewritten and resubmitted after a minimum period of 3 months has passed. Proposal authors are advised to consider the reason(s) the vote failed the first time—if several people checked Disagree for one for more of the proposal characteristics, a new approach is probably called for, while if people checked Insufficient information, more detail may be all that is needed.
The proposal acceptance stage
- If there is only one proposal for a given topic or purpose, and the outcome of step (4) of the proposal voting/selection stage is the acceptance of that package, then no further action is needed. The authors of that package can move to The package specification development stage.
- If there are multiple proposals for a given topic or purpose, then the authors of the different proposals should be encouraged by the SBML Editors to either (i) combine their proposals to reach a single combined proposal, or (ii) remove the overlap in their proposals so that they address distinct problems and can be treated as solutions to different problems.
- If, after the previous step, multiple proposals still remain, then a separate community vote must be performed to select which one of the proposals should be adopted as the accepted approach for a given problem area. The following are the steps for that process.
- The Chair of the SBML Editors will construct a survey for the purpose of holding a public vote to select between the alternative proposals. The survey will allow members of the SBML community to indicate which one of the proposals they prefer.
- The Chair of the SBML Editors will issue the call for votes. A minimum period of 4 weeks will be given before the vote is closed to give the SBML community sufficient time to evaluate the merits of the alternative proposals. At the Chair's discretion, a longer period may be chosen if it is deemed appropriate.
- At the end of the voting period, the SBML Editors will report the outcome publicly using the same rules as described in step (4) of the proposal voting/selection stage. The proposal chosen by majority vote will be the one moved to the stage of Package specification development.
Package specification development
At any time, but especially after a package proposal is accepted, the proposer(s) and other interested individuals may begin writing a full specification for the package. Coordination and communication during the development of the specification(s) is intended to be helped by the Package Working Group described below. There are also guidelines for the format of the specification, and there is a process for approving the final specification.
The Package Working Group (PWG)
SBML, being a community standard, depends vitally on community participation for development and review. The Package Working Group (PWG) is intended to promote focused participation centered around a subset of SBML, namely, an SBML Level 3 package. The goal is to bring together individuals who have relevant expertise and interests, and enable them to collaborate throughout the life of a package—not only taking the package proposal from inception to full specification, but also supporting the package's maintenance throughout its existence.
The requirements for a PWG are as follows:
- The existence of a mailing list, as noted in point (5) of the section on "The proposal voting/selection stage". This list serves the dual purpose of providing a basic mechanism for notification and discussion, and identifying the membership list the PWG. (PWGs are of course free to implement other mechanisms of communication in addition to the list.)
- Inclusion, as member of the PWG, of one or more of the original authors of the proposal for the package, at least during the initial creation of the PWG. Original authors of the proposal may subsequently depart the PWG at any time after the PWG is created.
- Inclusion, as member of the PWG, of one or more SBML Editors, to act as liaison. It is up to the SBML Editors to decide who will be the member.
- Regular reporting to the SBML Editors about the progress on the development of the specification for the SBML Level 3 package. Reporting will take place not less than once a year at the occasion of the SBML Forum's general meeting. (However, PWGs are encouraged to report and discuss activities with the SBML Editors and the wider SBML community much more frequently than once a year.)
PWGs are free to organize themselves and make decisions as they deem appropriate, but the development of the SBML Level 3 package must follow the overall principles for development of SBML Level 3. The developers of an SBML Level 3 package should strive to solicit feedback from the other members of their relevant PWG, and to keep the PWG abreast of package developments in a timely manner, so that concerns can be addressed quickly and new ideas can be incorporated early in the process. The PWG should be viewed as a resource to help bring the package to realization, not as an obstacle or bureaucratic hurdle.
The format of the specification
In order for the collection of SBML Level 3 specifications to form a better-integrated whole despite being written by different people at different times, the SBML Development Process places a few requirements on the format of specification documents.
- Specification documents must use the official document template for SBML Level 3 package specifications.
- The specification must include UML 1.0 class diagrams describing all data structures defined by the package. (The specification may also use other means to describe the structures, in addition to using UML 1.0.)
- If the package extends components of SBML Level 3 Core, the specification must make clear what the extensions are.
- The specification must follow the SBML Level 3 package numbering and declaration scheme.
The approval of the specification
Package authors may seek approval of the specification when they feel it is appropriate to do so and the specification has met the criteria listed below. No time limit is set for this part of the process because different packages will differ in their needs, complexity, scale, and other factors.
Criteria for approval
A proposed package specification becomes an Approved SBML Level 3 Package after it satisfies the following criteria:
- There exist at least two separate software implementations. There must be at least two software systems that implement support for manipulating the constructs defined in the package specification.
- The software must be able to manipulate the constructs in the package, and not simply store and retrieve the package constructs. (For this reason, implementing support for the package in a library such as libSBML alone does not qualify as one of the implementations, although of course other software may use the libSBML package support as part of their qualifying implementations.)
- Each software package must be able to manipulate a majority of the features defined in the package. (The precise definitions of what constitutes a majority of the features and able to manipulate are left to the PWG to decide. The operational criteria may be different for different SBML Level 3 packages.)
- Every feature in the package specification must be supported and manipulated by at least one of the two tools.
- The SBML Editors approve the package specification. Approval by the SBML Editors means that the package will be judged according to its adherence to (i) the package design guidelines, (ii) the format guidelines, and (iii) the process described in this document. With respect to the design guidelines, the SBML Editors will consider the following points:
- Utility: Does the package concern itself with a subject or problem area that SBML users find useful?
- Biological orientation: Is the overall aim of the package to support the description of biological processes and phenomena?
- Coherence: Are there concepts in this package that are already encoded in a different package? If so, could they be synchronized? Are the new constructs tied, where appropriate, to Level 3 core concepts, or to other package constructs?
- Orthogonality: Does the package overlap any other SBML Level 3 package? Are the data it stores represented only once, or is data being duplicated unnecessarily?
- Effective abstractions: What are the various ways one can analyze the data stored with this package? Are all (or a reasonable subset) accommodated by this package? Is there a bias in favor of a particular approach?
- Implementability: Are the two purported implementations of the package truly functional?
- Explicitness: Does the package define any implicit defaults anywhere?
- Validity after reduction: When this package is stripped from a model, is the remaining model valid SBML? Conversely, if other packages are stripped from the model, are this package's constructs still valid? If not, is there a clear reason, stated in the spec, why this is so?
- Community: As this package was developed, was the community invited to participate in the Package Working Group (PWG), and was the PWG consulted when making key decisions? Is there anyone who justifiably feels left out of the development process?
As mentioned above, a specific time schedule is not provided for seeking approval of a full specification. A request for approval can be initiated by the authors of the SBML Level 3 package specification whenever they feel it is appropriate. The process is as follows:
- The authors contact the SBML Editors and request approval of the specification. (They must also inform their relevant PWG at the same time.)
- The SBML Editors will evaluate the specification according to the criteria described above.
- The SBML Editors will report the results of their evaluation to the package authors and the relevant PWG.
- If the decision is not to approve the specification, the SBML Editors must provide a detailed justification to the authors and PWG. The justification must explain how the specification fails to adhere to the criteria described above. The authors of the specification may address the issues raised and revise the proposal as needed, then return to step (1) of this approval process.
- If the decision is to approve the specification, the SBML Editors will perform the following steps:
- Incorporate the package specification document(s) in the list of SBML Level 3 specifications.
- Arrange for a COMBINE Specifications URL for the specification document.
- Update the package activity web page(s) in the SBML.org Community Wiki.
- Issue a public announcement to the sbml-discuss and sbml-announce mailing lists.
Special cases and circumstances
As a result of the fact that the SBML process is being developed essentially at the same time as SBML itself and its community is evolving, sometimes special cases (such as grandfather clauses) are introduced in provide smoother continuity in official procedures. This section gathers these cases separately from the main body of the text above. The clauses are numbered sequentially, and the text above refers to the numbers.
- Grandfather clause for the creation of PWG's for package proposals in existence as of April 2011. In recognition of the fact that many package proposals were in existence for some years before these SBML process rules were created, and have achieved a type of de facto acceptance in the SBML community as being desirable packages, the formation of a Package Working Group (PWG) for each of these existing packages may be initiated at the same time as the call for votes described in (3.c). The justification is that the probability of these package proposals being ultimately rejected is considered low enough that the effort of creating the PWG is warranted: in other words, it appears reasonably clear that the packages are desired by the SBML community, and what remains is to work out the details of their formulations. The packages recognized under these terms are the following (listed here using their short labels):
annot. Note that this clause does not guarantee ultimate acceptance of the proposal, it merely hastens the formation of the PWG. This step is viewed by the SBML Editors as desirable to help accelerate the process of working out the details with a larger group of interested participants.