doorstop-dev
ReqIF support (again)
An important feature of requirements managers is the interchange of requirements documents, between teams, companies, and programs. ReqIF is the standard interchange format for this class of products, and I suggest that it may be worthwhile to integrate ReqIF support into Doorstop to improve interchange capability.
Reading #361 , apparently the earlier issue was the lack of a parsing tool. That now exists : https://github.com/strictdoc-project/reqif
Looking through both doorstop and the ReqIF spec, most of the functionality maps 1:1. The major issues are, as I see them, the handling of UUIDs and the preservation of extraneous data for round-trips.
ReqIF requires that all objects have a UUID that is preserved across time. This should in principle be stored in the file, same as links currently are, and global objects like SpecAttribute UUID's stored in the .doorstop.yml file.
Finally, ReqIF is an extensible standard, supporting ReqIFToolExtension data which could be literally anything. This data could be stored in a compressed format in the .doorstop.yml file, to be incorporated when unparsing back out into ReqIF.
I'm happy to take the lead in this, as we would like to integrate Doorstop into our toolchain, which requires ReqIF functionality for the Requirements : MBSE interface.
Reading https://github.com/doorstop-dev/doorstop/issues/361 , apparently the earlier issue was the lack of a parsing tool. That now exists : https://github.com/strictdoc-project/reqif
Author of this library here. Thanks for considering it for your implementation. I have put in a considerable time to make it robust and wish I could do even more in the future.
If you would need any support, I am happy to help. Note that reqif is a satellite project of StrictDoc which used to be a fork of Doorstop several years ago but is now an independent project.
If you are going to implement a ReqIF interface for Doorstop, we could ensure that both Doorstop and StrictDoc can talk the same ReqIF language. You probably know at this point that ReqIF does not provide a single schema recommendation, so there is a zoo / "wild west" of several schemas possible, and I collected them over time in the reqif's integration tests. I would be great to gather enough people someone seriously interested in this and agree on a good single ReqIF schema that would scale across several tools.
And finally, note that https://github.com/DSD-DBS are working on integrating Capella MBSE with StrictDoc, and independently from StrictDoc's reqif, their tools are ReqIF-aware. Which MBSE tool are you working with?
If answering this gets too detailed, feel free to write me an email.
cc @vik378
Happy to hear that you're willing to help. I think I have a handle on what needs to be done, but I'll get in touch if I have questions.
We are indeed using Capella MBSE, although Doorstop's atomized approach is interesting for downstream engineering purposes (linking requirements directly to individual parts/systems without the need to parse a large document). I will look into StrictDoc more in depth to see if its a good fit.
Finally, I am 100% on board for standardizing the format across tools. I think these loosely defined interchange formats (like STEP) cause more problems than they solve, when compared to strictly defined formats. That said, it's worth avoiding format wars.
Just to touch base on this, is this extension still being worked on or there is not enough bandwidth to work on ReqIF support? I am considering to propose the adoption of doorstop within our workflow to replace IBM DOORS but we still need to have interoperability towards it. We could do with CSV/XSLX but supporting this would make the workflow smoother. I am available to support in the implementation if you (@mumbricht @stanislaw) are still working on this.
Hi @salvioli, I never got feedback on this, so I was waiting to do this when I had the need. If you need this done, I'll make it a priority. That said, I'm not part of the doorstop team so all I can do is make a PR when its ready.
Thanks for the quick feedback, makes total sense. An implementation on a fork would be more than sufficient for me to demo this. As I mentioned I am available to support.
@stanislaw I'm finally getting around to implementing reqif in doorstop, and I had a question as to your use of UUID's. ReqIF standard section 10.2, "Identifiers", talks about "global unique identifiers", which is not strictly UUID's. UUID's is probably a good approach though, so that's the direction I'm going in (see https://github.com/Mumbri-systems/doorstop/blob/develop/reqs/REQ021.yml). Do you have an opinion on the use of UUID's vs local UID definitions?
Hi @mumbricht,
The UUID is not the same as UID. To recognize this, StrictDoc supports a concept of MID (machine identifier) which maps directly to the UUID of ReqIF.
Note that some ReqIFs produced can maintain both UID and UUIDs separately but also there are cases when only UUID is used for linking as this ticket demonstrates: https://github.com/strictdoc-project/strictdoc/issues/1935. In that case, there are documents with non-unique UID but they are still part of the same ReqIF because their UUIDs are different.
I don't know whereto you would map ReqIF UUID in Doorstop. In StrictDoc, I map UUID to MID because that's what I made StrictDoc to support to handle this.
@stanislaw So in strictdoc, MID + UID guarantees uniqueness, as opposed to a UUID? My basic idea was to add an item attribute to store the UUID, potentially as a compressed string. If the string is compressed, I can add some mapping information without cluttering the .yml
@mumbricht,
StrictDoc right now requires the uniqueness of UID but this is what I want to change with an optional parameter where the uniqueness will be required on MID (UUID). In addition to the uniqueness, to support 100% interop with ReqIF, the relations will also use MID/UUID instead of UID if that option is activated. It is one of the 2025 Q1 work items for StrictDoc.
@salvioli, would it be possible to provide a sample reqif document from Doors? There may be differences with the ones from StrictDoc
There is no such thing as "ReqIF from StrictDoc" but rather ReqIF from tools A, B, C, .... Over the years, the reqif repo collected quite a few examples of ReqIF files, and they are stored in tests/integration in an anonymized way, see this and around: https://github.com/strictdoc-project/reqif/tree/main/tests/integration/reqif_software.
Having that said, there is always a user who sends a ReqIF file that is different compared to what the reqif repo has seen before, and some minor tweaks are still needed. This is coming from the fact that there is no single ReqIF format but rather several 'flavors' implemented by the tools like Doors, Polarion, Enterprise Architect, etc. The tools themselves recognize this fact very well, this is why they usually provide (non-trivial) GUI wizards for doing customized export/import to/from ReqIF.
If you plan to work closely with the ReqIF repo, I highly encourage you to identify any ReqIF flavors that may not yet be tested in the repo and submit PRs to integrate them with integration tests.
When I say "flavors", I specifically refer to the differences in how the tools handle the document type system, which types a document can have, which type a requirement corresponds to and which type a section corresponds to, custom types for document elements may or not be used, which fields are used for relations, relation types, etc. One challenge that you could prepare yourself for is to handle bi-directional export/import roundtrips. To be able to recover the original ReqIF structure back from Doorstop, you will probably have to level up Doorstop's type system because it has to match that of ReqIF.
It is not a trivial topic and I am curious if you could solve all these compatibility issues between ReqIF and Doorstop in a reasonable time. Luckily, the reqif library solves the first 50% of the challenge very well but the rest is still on you to take on.
So @stanislaw @mumbricht do you think it would be useful to have an anonymized version of our DOORS generated reqif files? Or should we give up to support all flavors and provide some level of flexibility to the user so that an expert user with a guide can configure his doorstop instance to support the file? what is your experience @stanislaw on StrictDoc with respect to this?
@salvioli an anonymized Doors-generated ReqIF file would be great to have to enable the following:
-
I could ensure that the reqif library is happy about this file, and there are no unhandled tags or attributes. Feel free to send me an email (see GitHub profile). If reqif is happy, I will do nothing, otherwise I will integrate your file as a yet another test case.
-
@mumbricht could start working on the Doorstop ReqIF export/import scripts.
The file should be anonymized but still have a realistic structure just like you would have it in your real projects. Ideally it should contain multiple, possibly nested, sections and a handful of representative requirements and other elements as is maintained by you / your company (text, images, etc).
(I cannot help with the task 2 because I have enough to do with StrictDoc š )
Iām also interested in this!
On Fri, 7 Feb 2025 at 08:32, Federico Salvioli @.***> wrote:
Ok I will provide one ASAP.
ā Reply to this email directly, view it on GitHub https://github.com/doorstop-dev/doorstop/issues/646#issuecomment-2642249562, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAB4O4HBSJXMCZQZPI36RMD2ORVS7AVCNFSM6AAAAABVZJ4JR2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNBSGI2DSNJWGI . You are receiving this because you are subscribed to this thread.Message ID: @.***>
@stanislaw So I've started by working on export in order to get a feel for the reqif library. Most of it is straightforwards, but I have a question about type definitions.
In your create example : https://github.com/strictdoc-project/reqif/blob/main/tests/integration/examples/01_create_reqif_objects/script.py you generate a new definition of string type, complete with UUID and "last_change" date at runtime.
So first off, I think that at a minimum this definition should be static in the exporter, with a UUID and last_change hardcoded.
Although that begs the question, would it not make sense to try and synchronize common types across tools? Does a stringtype really need to be uniquely defined on a per-tool basis? If so, where can I find these ID's and parameters?
Also: the Header includes two ID's: the "identifier" and the "repositoryID" (using ReqIF nomenclature). Currently, I am treating the identifier as an id of the Doorstop root document, and the repositoryID as an ID of the VCS, to be implemented later. Is this correct? A certain reading of the spec suggests the identifier is generated at export and the repositoryID should refer to the Doorstop root document.
@stanislaw So I've started by working on export in order to get a feel for the reqif library. Most of it is straightforwards, but I have a question about type definitions.
In your create example : https://github.com/strictdoc-project/reqif/blob/main/tests/integration/examples/01_create_reqif_objects/script.py you generate a new definition of string type, complete with UUID and "last_change" date at runtime.
So first off, I think that at a minimum this definition should be static in the exporter, with a UUID and last_change hardcoded.
Although that begs the question, would it not make sense to try and synchronize common types across tools? Does a stringtype really need to be uniquely defined on a per-tool basis? If so, where can I find these ID's and parameters?
Please note that the example is as basic as it can possibly be. Don't consider the way I am setting up UUIDs there as how it should be.
As I understand it, ReqIF allows having multiple String or other types because they can have slightly different constraints. For example, on a string type, you can impose a max length constraint and on an integer type mix/max values.
In StrictDoc I didn't proceed to model 1-1 the Boolean, Integer, Float and Date types, but I did model the single and multiple enum types. It is possible to make a 100% compatible type system with StrictDoc's text markup already, I just didn't push for it as it would bring (IMO) only a marginal value, given the most of the time people export strings (singleline and multiline which handling is another workout for a converter).
I mentioned before that StrictDoc has an option to enable Machine Identifiers (MID) which correspond to UUID in ReqIF. Ideally, each entity in a requirements graph should have a unique identifier (independently from UID), so if you create a converter ReqIF -> to your format ABC, your format should have a notion of UUID in some way. The example you are looking at hardcodes UUID to dummy strings just for the sake of simplicity, whereas a real implementation must read proper UUIDs if the tool supports their modeling or create fake UUIDs which still must be used correctly within the resulting output file if you are exporting from your tool back to ReqIF.
Also: the Header includes two ID's: the "identifier" and the "repositoryID" (using ReqIF nomenclature). Currently, I am treating the identifier as an id of the Doorstop root document, and the repositoryID as an ID of the VCS, to be implemented later. Is this correct? A certain reading of the spec suggests the identifier is generated at export and the repositoryID should refer to the Doorstop root document.
This is an open question for StrictDoc as I haven't implemented this part. I didn't consider this metadata to be important and none of the users highlighted the importance of it.
Hi, sorry for the long silence on the topic, it took a while to procure the file and then I realized it is taking quite a bit of effort to anonymize it, did you ever had to perform this on other files? are you aware of some (semi-)automatic ways to do it or you did it entirely by hand?
Hi, sorry for the long silence on the topic, it took a while to procure the file and then I realized it is taking quite a bit of effort to anonymize it, did you ever had to perform this on other files? are you aware of some (semi-)automatic ways to do it or you did it entirely by hand?
Please check this out: https://github.com/strictdoc-project/reqif?tab=readme-ov-file#anonymizing-reqif