< To: ORMF
- 1 Introduction
- 2 The high level view of the model
- 3 Current questions
- 4 Comments
This page describes the new requirements model, which is now based on the EMF framework. The model is currently defined only at a high level and will iteratively refine over the course of the next few weeks.
While the sections below describe the model in broad strokes, the actual ecore model may be accessed from the SVN repository. The repository is located at <https://dev.eclipse.org/svnroot/technology/org.eclipse.ormf> and the project that contains the ecore model is <trunk/analysis/org.eclipse.ormf.analysis.model>, with the actual model residing in the "model" folder. (Thanks to Rich and Achim for pointing out the missing link to the actual artefact).
The high level view of the model
The figure below shows the initial high level analysis model for the ORMF requirements. At this stage the model simply reflects the main elements and their mutual relationships.
At the highest level of abstraction we have the Requirement Artefact, which represents all general features that are shared by all types of requirements. The Requirement Artefact has two specialisations, namely the Requirement and the Requirement Narrative elements.
The Requirement element represents standard requirements, which can then be further specialised into Functional Requirements or Non Functional Requirements. Requirements may be specified by other Requirements, in a parent/child relationship.
Requirement Narrative elements are types of Requirements Artefacts that expect descriptive elements, such as flows of events. A Requirement may be associated with (and traceable to) a Requirement Narrative element. Special cases of Requirement Narratives are User Story and Use Case elements. A Use Case element in particular may have associations with (refer to) a number of Actor elements and zero or one Use Case Package element.
Any Requirement Artefact element may then contain a number of relationships to Requirement Elucidator elements. Requirement Elucidators are elements that may be utilised across a number of different types of Requirement Artefacts and that permeate the entire requirements model. Examples of Requirements Elucidators are Issues, Glossary Terms and Notes. The distinguishing features of Requirements Elucidator elements are a) the fact that each Elucidator may be referred to by multiple Requirements Artefacts (f.i. a Note may be related to, or elucidate, any number of Requirements Artefacts) and b) the fact that it is possible to compile lists of all Elucidators of a given type defined across the entire requirements model through generic reporting tools.
The model shows all the types of Requirement Elucidators we intend to support.
Any Requirement Artefact element is characterised by relationships with either other Requirement Artefacts (named “requirement relationships” in the model) or Requirement Elucidators (named “elucidator relationships” in the model). These relationships have many features in common, such as their stereotype, which defines the type of Requirement Artefact or Requirement Elucidator that is referred to as the target of the association, or their multiplicity. As such, these associations could be described by a common association class, generically called Relationship. The problem with doing this is that EMF does not support association classes. This is the reason why the Relationship element shown in the model is currently sitting in a corner as a simple reminder.
Requirement Document and Augmentation Text
The model finally defines two other types of elements, namely Requirement Document and Augmentation Text.
A Requirement Document represents a textual artefacts that acts as a “wrapper” around specific sub sets of Requirement Artefacts. A good example of this type of element is the Software Requirements Specification document, which is typically a high level survey of all functional, non functional and use case related requirements for a software project or for a specific component of the project. The analyst typically organises the survey in a particular way, that needs to be reproducible through the natural evolution of the requirements and that needs to contain sections of descriptive text that acts as a cohesive agent for all requirement artefacts proper. Examples of such sections are introduction, overview of the problem domain etc. This text is what the model refers to as Augmentation Text, which is represented as a separate model element; any Requirement Document makes use of an arbitrary number of Augmentation Text elements.
- How to represent the association class Relationship in EMF?
Please enter comments below by selecting the edit icon to the right. You will need a Bugzilla account to add comments.
Nitpicking: The Requirements parent/child relation should have a cardinality of 0..1:0..*
I just realized that I might have mismatched the cardinalities of parent/child and Requirement/Requirement Narrative. Would you please attach the model files to this page so we can look at the details directly.
I'm quite sure that Requirement, Requirement Narrative, Req Artifact and Req Elucidator are abstract classes. I for one like this information in the model, but this is a matter of personal preferences.
--Achim.Loerke.bredex.de 08:42, 26 December 2008 (UTC)
Thanks for pointing out the missing link to the model file.
Yes, all the classes you mention as abstract actually are abstract in the model, the diagram is a bit flaky and shows them as abstract at times, but keeps on reverting back.
I will also fix the cardinality in the parent/child relationship.
--Barbara.Rosi-Schwartz.Etish.org 15:58, 29 December 2008 (UTC)
I would like to suggest an important refinement: requirement versions Actually, every artefact any role will produce will actually be some version of that artefact, which, as far as I understand, ORMF will have to be able to deal with.
Another question is, why parent-child relationships between requirements are modeled explicitly when the model already contains the more generic "req relationships" relation on the Req Artefact level. Consequently, that generic relationship should be expressed using the Relationship class from which more specific relationships can be derived.
One more minor point for a suggestion would be to include "Design Constraint" or another, more general, constraint class as specialization of Requirement into the model, since constraints are a frequent thing to deal with in specifications. Constraints do not always map onto non functionals, so I would not treat them as specializations of the Non Functional class.
I am not sure, if it is wise to restrict the ability of packaging to Use Cases alone. I have worked with requirements packages quite effectively in the past. Maybe we should allow any Req Artefact to be packaged?
Another interesting point is the level of modeling abstraction covered here. If we view the requirements process from some distance away, it usually starts with some business vision or broad goals. These goals are often refined into capabilities required to achieve those goals, which are then captured in business rules or business processes (or simpler flows). To my understanding, these elements are as important as Use Cases or User Stories and provide similar information (just on a different level). I therefore would kindly ask you to explain why Use Cases and User Stories are children of Requirements Narrative, while Vision and Goals are missing and Business Rules and Flows (or processes) are only elucidators? I am not sure if I have understood the difference between elucidator and narrative properly.
--ORMF@IB-Ponikwar.de 09:42, 29 December 2008 (UTC)
Thanks for the many interesting points you brought up.
Versioning: it is definitely a very important topic and one that we get asked about often by interested parties. However, it is also a rather complex issue, and we have always made it clear that, while we desire to implement versioning at some point, we cannot tackle it in the first release(s) of the framework, simply due to lack of sufficient resources. We also see it as an implementation issue more than a core requirement model issue, so we do not really feel that it is appropriate for us to include it in the model at this point in time.
"parent/child" relationships vs. generic "req. relationship": the reason they are separate is that we view the first type of relationships as bidirectional ones: in the case of standard requirements, we have a tree hierarchy where any parent knows about its children and each child know about its own parent. The generic inter-requirement artefacts relationship is instead uni-directional in nature. For example, a base use case does not know about its extension use case; a requirement artefact may have a weak dependency relationship to another artefact (i.e. a simple reference), about which the referenced artefacts knows nothing.
Design Constraints: your suggestion of including them in the model is definitely interesting and appropriate, I think. However I do not understand why you view a Design Contraint as a type of Requirement object. Should it not simply be a class on its own, that any Requirement Artefact may use?
Vision, Goals and Business Rules: I agree with you that Vision should appear in the model. I am not sure about Goals, as I am not familiar with formal Goals specifications -- perhaps you can provide me with examples. As for Business Rules, we have them as Elucidators at present because we view them as finite rules that apply to and elucidate specific aspects of requirement artefacts. I am aware of the fact that, in some projects, Business Rules occupy a far more central position in the requirements model and are types of requirements themselves. However ORMF is not going to be a business rules engine or a tool to manage business rules in a big way. What I think is important is that we keep that whole aspect in mind and that we provide hooks that allow to invoke one of the existing business rules management systems if and when needed for a specific purpose.
--Barbara.Rosi-Schwartz.Etish.org 16:15, 29 December 2008 (UTC)
thanks for your quick reply.
I don't want to start any flame war here, but I consider change management a core facility of ORMF - without this it is a lot less attractive - or shall I say "useful"?. Linking use cases to requirements can be done with quite many tools on the market, some are so cheap you wouldn't care that they are not open source. ORMF in my opinion, must provide some benefit not available elsewhere. I also consider the versioning issue to be far too complex to be left "for later" or to be seen as implementation issue. The less you care for this when modeling your domain, the more difficult it will be to be implemented properly later.
On the relationship issue, we have misunderstood each other. As far as "uses", "extends" or "includes" relationships are concerned, I agree, those are mostly unidirectional. There exist many more relationships between requirements which are not parent-child (in fact, I have only seen this kind of relationship in very few projects), but are, as you stated bi-directional in nature: derivation, coincidence, contradiction, crosswise influence, to name a few. I would suggest to have two abstract relationship bases, a unidirectional one and a bidirectional one, of which parent-child is only one of many possible specializations.
Design Constraints could be their own class, that is true. I have seen them as special form of requirement, since that is simply the way we have treated them all the time. They state something that must be followed or obeyed like any other requirement (even in the same formal way), but can not be easily allocated as functional or non-functional requirement. Frequently, they are tied to some other functional requirements and may as such be seen as some form of elucidator, but I feel that is already too weak.
On the question whether Vision or Goal should be part of the model, well that depends on the scope of your modeling. The larger the scope (the more "enterprise" it gets), the more important will those be and the more information will be represented by those elements. And often it is those elements that "survive", while detailed requirements get rewritten frequently. They represent significant value for the overall understanding and objectives of the whole endeavour - guiding analysts and developers down the road.
The point is traceability. Not that tool-centric linking, I speak of understanding why some requirement is there and why it is there in that form. These overarching guidelines, objectives or, well, goals, are, in my opinion, a central part of every specification. They represent the glue to tie those hundred and so many requirements together that make up some system. I have worked on too many projects in the past, where exactly that happened: everyone knew the many detailed requirements, but noone understood why they were there - and consequently nobody understood the true ramifications of changes of the details.
Another point that came up during the last couple of minutes: we have use cases and user stories as narrative elements. If we have only those, they must exist on several levels of abstraction (see the many articles of Cockburn on Crystal or use cases in general) for the various levels they can span. In that case, use cases should have the possibility to have bi-directional relationships among each others.
Finally, I would like to ask you to specify what you consider a Requirement (no, I am serious). I have the impression that my understanding is far more general than how you see them. Just to avoid future confusion.
--ORMF@IB-Ponikwar.de 18:16, 29 December 2008 (UTC)
First off I want to say that this is great conversation and I am really pleased that the team and other contributors are now able to discuss these matters in detail. Keep up the insightful thoughts and have no worry about flame wars; what we need now is open exploration of what the project is about and were it going.
I just want to comment on the matter of versioning at the moment. Please do understand that I and Barbara fully understand the value of good versioning. (In fact is was the versioning capability that was most attractive about OSEE.) Without it traceability is at very best half baked. I also agree with you that it is so invasive into your model that tackling it as an after thought either leads to significant rework or a shabby job of it.
In my opinion, though, if we tackle versioning in the initial release we will most likely never deliver anything. At the moment, to be honest, B. and I are the only ones who are actively contributing to the development. On that basis of resourcing it is already terribly scary when I think about the amount of work involved. To add another major feature daunts even my hutzba.
I would also mention that when B. said "an implementation detail" what she was really saying is that it is a technical detail. This early in the model exploration I do not think it should be encumbered with these details because they make the model harder to understand from the users perspective. If I get convinced over the next couple of months that we can do versioning, then we can add it to model then but before the model is so concrete that it is difficult to do so.
Btw, for the record, there is work in the EMF community that we may be able to use to get versioning for free or near so. I need a lot more research into these, however, before being brazen enough to count on it.
--Joel.Rosi-Schwartz.Etish.org 19:06, 29 December 2008 (UTC)
here's my reply to your comment above point by point.
Regarding versioning, I agree with what Joel has already replied above and do not really have anything to add.
Concerning relationships, your idea of generic bidirectional relationships is a good one and I will add it to the model.
As for Design Constraints, I still see them as ancillary to requirements, not requirements in their own right; however I need to explore them more deeply before expressing a final opinion.
I agree totally in the benefit of including a Vision and/or Goals into the set of requirements we support. Again, a deeper exploration of both these artefacts is required on my part to see what, if anything, we require in the model in the way of support for them.
Finally, about my definition of requirement: do you want my definition of requirement as the generic word we use all the time in conversation or the Requirement type in the model?
--Barbara.Rosi-Schwartz.Etish.org 12:39, 2 January 2009 (UTC)
A generic requirements model?
After having taken some time to rething our discussion here I would like to raise the question whether we are taking the proper approach here, or not (thus the new discussion point).
The current ORMF model is neither the only requirements model out there, nor are we the first ones to develop such a model. Popular requirements models are (but not limited to) the Robertsons Volere model (2006), the RUP model (Leffingwell, Widrig, Kruchten 2003), the Hatley/Hruschka/Pirbhai model (2000), or the requirements model by Karl Wiegers (2006). All of them share some commonalities and expose several differences, but none maps easily onto the current ORMF model. What are we going to do about this? Are we expecting everyone who wants to use ORMF to abandon "their" model for the ORMF one? What would be the advantage of using ORMF as opposed to some other tool? Aren't we striving for a framework - i.e. a set of building blocks from which concrete tools can be built? What would that mean to our ORMF model?
I think we have the following choices:
1. We leave it as it is and expect people to change their way of modeling requirements if they want to use ORMF.
- in my opinion, ORMF would fail to meet one of its most important goals right from the start if we take this route.
2. We extend the current model and try to include the other concepts and models.
- I think this would bloat the ORMF model and make it unmanageable sooner or later. - And where would we stop? After we have included 2, 3 or 10 other models?
3. We identify the commonalities between a (arbitrarily chosen) set of popular models and adapt the ORMF model to allow a more straighforward mapping to increase the potential audience for ORMF. We might as well introduce additional hooks and extension points to make the model more "open".
- A potential approach, allowing to keep at least some part of the current model. - But we'll be missing the full potential of a true modeling framework.
4. We take a more generic approach, much in the sense of a modeling language to provide a framework (sic!) from which concrete requirements models can be derived (...parameterized, instantiated, etc.), maybe in the sense of profiles. I could imagine to have the generic ORMF model and concrete instantiations for RUP, H/H/P, Volere and others. This would make ORMF a true requirements modeling framework - at the expense of a more generic approach (more difficult?) and the need to instatiate concrete models (one more step to be considered).
- Although the most promising approach it will also be the most challenging one.
I have not come to a final decision yet , although I must admit, I do have a favourite. Nevertheless, I am sure this needs more in-depth deliberation and (hopefully) opinions and thoughts of other people.
--ORMF@IB-Ponikwar.de 7:51, 02 January 2009 (UTC)
Thanks for these thoughts, Wolfgang.
I will attempt to explain what the existing ORMF model (and indeed the entirety of ORMF) is about and why we still feel, after reading your comments, it is appropriate.
First of all, let me throw the cat in among the pigeons by completely differing from your opinion that "The current ORMF model is neither the only requirements model out there, nor are we the first ones to develop such a model". All the "models" you mention in your example are, in actual fact, not models at all, but methodologies or processes/best practices for requirements gathering and management. In actual fact, our approach has been very much guided and inspired by RUP, as well as the requirements specific works by Leffingwell, Wiegler, Armour, Constantine et al. All these resources express wonderful, rich ideas on what requirements should be about, but in the end of the day they all rely on free textual documents/templates for the definition of those requirements. The same is true for the Volere approach (they offer a template) and, I guess, for the Hatley/Hruschka/Pirbhai methodology (I am saying I guess because, after a brief research, I cannot find any information other than their -- somewhat outdated -- book, no other publicly available information).
The novelty of ORMF/Useme lies precisely in the fact that we are, I believe, the first ones to propose to treat all requirements, including their textual descriptions, as structured elements, at least in the open world.
Automated tools would not be possible without this structured nature. Please note that I am not talking about requirements management: there are many tools out there that help in managing requirements by assigning them standard attributes (priority, risk level, dependencies etc.). What I am referring to is the actual requirement description itself, which absolutely needs a structured approach for automation to be possible.
In this light, the model we are proposing should not be viewed as the ultimate model for all requirements, a bit like the unified theory (aka theory of everything) in physics. It is to be considered as an artifice to enable the handling of requirements by automated tools and to provide auto generation of requirements documents that satisfy the needs of the methodologies you mention in your post. Another way to say this is that our model is not really a requirements model, but a meta-model or more precisely a DSL for the automated handling of requirements via any CASE tools that are built on top of ORMF.
Of course the model still needs to be extensible for the benefit of third party adopters, and indeed we very much want to carefully engineer it to enable that in the most straightforward way.
And of course, most importantly, all the methodologies you refer to (along with others that we have and are still exploring) need to be taken into consideration when deciding which elements and aspects of the various requirements models to include in ORMF for capture. This is, after all, what the survey of standards that we have launched is all about. Let me point out once again, though, that our model should not and will not be one of those standards; it will simply be able to support as many of them as possible in terms of the documentation that the ORMF based tools will be capable of producing.
In our view, the various templates/documents proposed by the requirements gurus to which you point represent the end product, not the starting point, of ORMF.
I hope this goes some way to clarifying where we stand and what this model is all about. This is a very fundamental issue, and it is really important that we are all on the same wavelength on it.
--Barbara.Rosi-Schwartz.Etish.org 12:25, 2 January 2009 (UTC)
thanks for your answer. I am happy to find we have a similar understanding of what ORMF is supposed to be ("...our model is not really a requirements model, but a meta-model or more precisely a DSL for the automated handling of requirements via any CASE tools that are built on top of ORMF..."). That reminds me of the core point I wanted to address, but obviously failed to do so properly. The requirements models I have mentioned are in fact models and not processes or else, there you are wrong (I can point you to the literature or the tools where they have been implemented), but that was not my point. All I wanted to highlight, was the fact that I considered the ORMF model already far too constraining and too concrete to be a true Metamodel.
Since I am a visual person, I have quickly put together an idea of a model (really, take it as an idea only) of how I would like to understand ORMF.
The idea is, to keep ORMF abstract enough to be able to construct different requirements models, but yet to offer sufficient support to make use of the framework worthwhile. I would therefore be much more generic than the current model. The two basic entities are Artefacts and Relationships, which are all Taggable types, that is, they support being described by tags, that is named values. Both can be part of Packages, although each instance can only be at most in one package at any time. Independent from packages are Collections, which are arbitrary groupings of artefacts and relationships based on some Discriminator. These collections form the basis for RequirementsDocuments, which also nicely covers the versioning issue (consider a versioning tag as discriminator). Since one requirements model is often epxressed in several different documents depending on the stakeholder to be addressed, allowing to group artefacts and relationships independently from packages seemed advantageous. Artefacts have at most one Owner, which could be some stakeholder, the actual author, or any other role that has a special interest in this artefact. RequirementsElucidator, RequirementsNarrative and Requirement are the lowest level of entities that I would consider part of the framework - if I were very progressive. Don't drop this idea immediately, think about it for a second. I understand, there is value in modeling the level below, buit we might have to expand out current list of concrete elements to accommodate a wider audience, which comes at the cost of more and more elements.
As I said, the above is not a competing model, but my attempt to express my concerns with the current model and how I could imagine to find a way forward.
--ORMF@IB-Ponikwar.de 15:11, 05 January 2009 (UTC)
Really great that you put your thoughts together into a diagram, it is a lot clearer and easier to discuss.
I will need a bit of time to think your model through properly, although I already find it as covering interesting points. In the meatime, I would really appreciate it if you cold spend a few more words to describe what Profiles are and how they would play in the overall scenario.
--Barbara.Rosi-Schwartz.Etish.org 16:41, 5 January 2009 (UTC)
This is a comment I received from Francine Wolfe, a member of the LinkedIn Catalyze Community group, who agreed to share it.
Thanks for sharing this model; it's a good start, but I believe it needs more fleshing out -- especially around the items at the bottom of the page. One preliminary suggestion: Instead of "Functional" vs. "Non-Functional" requirements, I'd use the 6 types identified in the BABOK (Business, Functional, User, Quality of Service, Assumptions & Constraints, and Implementation). You may be able to find additional useful concepts in the BABOK (see www.theiiba.org).
My reply to Francine
Thank you very much for your very speedy reply. I am definitely aware of the fact the the model needs *a lot* of fleshing out. We thought we would put it out there at the very beginning of inception in order to gather comments as early as possible, to increase the chances of getting it right from the start.
Your suggestion of taking a look at Babok's recommendation for possible types is quite a good one and I will look into it very shortly.
--Barbara.Rosi-Schwartz.Etish.org 16:20, 29 December 2008 (UTC)
This is a comment I received from Ali Nasir, a member of the LinkedIn RQNG group, who agreed to share it.
After reviewing the model I would like a little elaboration regarding User Story class. In my opinion Use Case Class should have some other relationships with the zero or one to many attributes like pre-conditions, pos-conditions, triggers etc related with use case. A use case can have dependency on one or more other use case so a relationship can be shown at high level to depict this scenario if required.
My reply to Ali
Thank you very much for taking the time to review the model.
We are definitely planning on modelling use case specific elements on which a use case depends, such as pre and post conditions etc. We have simply not reached that level of detail yet!... :-)
As for relationships between use cases, we have a generic relationship, called "requirement relationship", at the level of the generic Requirement Artefact class. This relationship is meant to include, among others, all inter-use case associations of the types that you mention. Such associations will have all the concepts that you would expect in, say, an include relationship, such as multiplicity and stereotype.
Thanks again, B.
--Barbara.Rosi-Schwartz.Etish.org 15:47, 3 January 2009 (UTC)
This is a comment I received from Ed Merks (yes, THE Ed Merks), who very kindly reviewed the model and agreed to share his suggestions.
I've attached an EMF project with the Ecore model modified to generate well-formed Java code, i.e., removing spaces from names. It includes the Ecore Tools diagram which looks like this:
Your spelling of artifact is not the usual English spelling, so I corrected that. Your use of plurals also wasn't consistent, so I consistently gave multi-valued features plural names. I very much dislike abbreviations so I turned "req" into "requirement".
Some things that strike me as odd. I.e., Relationship has not relationship to anything, which makes it pointless. I suppose many of the empty subclasses are placeholders where features will be added, otherwise one might argue that "functional" should be a boolean property on Requirement, rather than having subclasses. I don't get the sense that some references ought to be containment. I.e., shouldn't RequirementDocument contain RequirementArtifacts? Shouldn't packages contain UseCases and Actors? Shouldn't something contain RequirementElucidators? Given that a Requirement contains at most one RequirementNarrative, why make them separate classes? To get your containment structure right, think about the hierarchical nesting of these things in an instance; generate the editor and try to create an instance document...
My reply to Ed
Hi Ed. Happy new year to you!
Thank you very much for your speedy review and for taking the time to actually change the model.
Regarding your first statement, we were actually thinking in terms of an analysis model, so all mundane and down to earth issues of well-formed Java code were still too beneath us!... :-)
I beg to differ on the artifact/artefact diatribe!... "Artefact" may not be the usual *American* spelling, but it definitely is the correct (and preferred) Queen English spelling. ;-) However, for the sake of conviviality, tolerance, cooperation and universal peace, I will be happy to stay with "artifact". Happy about removing abbreviations, I do not much care for them either.
As for the lone Relationship class in the model, I was hopeful you would shed some light on a workaround to that one. In my descriptive text I mention that the Relationship class would ideally be an association class, attached to both the "requirements relationships" and the "elucidator relationships" associations. I know however that, for well documented reasons, EMF does not support association classes, so I wonder how you would suggest solving that quandary. Something like an association class would be very useful as it would embody attributes that go beyond a simple association.
As you suspect, all of the classes in the model are going to be fleshed out considerably. We have decided to put the model out for comments and review at an early (very high level) stage in order to encourage improvements and corrections early on (in keeping with the old "the earlier the less expensive etc." adage).
Finally, thanks for the observation about containment; I agree I need to revisit the containment aspects of the model and your suggestion of using the generated editor as an aid may be a really good one.
Ed's further comment
My reply was followed up by Ed with the following pointers to how relationships are handled in EMF: a blog about associations for Ecore: http://ed-merks.blogspot.com/2008/01/modeling-associations-with-ecore.html and some work in progress: https://bugs.eclipse.org/bugs/show_bug.cgi?id=105920
--Barbara.Rosi-Schwartz.Etish.org 15:47, 3 January 2009 (UTC)