ReqIF support (again)

[mumbricht]

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.

[stanislaw]

Reading #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

[mumbricht]

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.

[salvioli]

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.

[mumbricht]

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.

[salvioli]

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.

[mumbricht]

@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?

[stanislaw]

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: strictdoc-project/strictdoc#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.

[mumbricht]

@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

[stanislaw]

@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.

[mumbricht]

@salvioli, would it be possible to provide a sample reqif document from Doors? There may be differences with the ones from StrictDoc

[stanislaw]

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.

[salvioli]

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?

[stanislaw]

@salvioli an anonymized Doors-generated ReqIF file would be great to have to enable the following:

1. 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.

2. @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 😄 )

[salvioli]

Ok I will provide one ASAP.

[robtaylor]

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 <#646 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAB4O4HBSJXMCZQZPI36RMD2ORVS7AVCNFSM6AAAAABVZJ4JR2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNBSGI2DSNJWGI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>