< To: ORMF
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)
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).
And 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)