Template for requirements

[hzbarcea]

No description provided.

[csarven]

It seems there may be some confusion about the intent of this task, so I'd like to clarify a few points.

It's considered good practice to reference the issue or action that a PR addresses. This helps others understand the context and purpose of the PR, improves record-keeping, and clearly distinguishes related or alternative solutions.

For example, assuming this PR is a follow-up to an action from the LWS WG 2025-01-27 meeting, it should state something like:

"Resolves ACTION to define a requirements template for the lws-ucs repository."

If that's the intention, I don't believe this PR aligns with the ACTION's goal. The template proposed here resembles a template for conformance clauses in a specification, which differs from a template to help derive functional and non-functional requirements from use cases - what the ACTION is meant to address.

(This ACTION arose because issues referenced in #117 presented requirements framed as use cases without linking back to the actual use cases.)

Solution-centric references have no place in a UCR document.

Ensure that functional/non-functional requirements are traceable back to their corresponding use cases. Requirements in a specification respond to these, with conformance clauses representing possible solutions - there can be multiple solutions to the same requirements in a UCR document.

For reference, see:

• https://www.w3.org/TR/ldp-ucr/
• https://www.w3.org/TR/did-use-cases/
• https://solid.github.io/notifications-panel/notifications-ucr (focus on the structure, not the content)
• ...

Note how the last two include a Requirements Matrix for clarity.

[hzbarcea]

Thanks for your thoughts @csarven. I am aware of the documents you link, I reviewed them last year. Out of all three, I like ldp-ucr, the most. But even that uses the term "shall" in the requirements extensively and pretty much follows the format I chose. I struggled a bit with with the term "component" and I was sure somebody will come up with a better phrasing. I am looking forward to the conversations in the group to best decide how to phrase this and everything will flow from there.

I also liked the dependency diagram in did-use-cases and plan to incorporate something like that in this doc.

[pchampin]

The template proposed here resembles a template for conformance clauses in a specification, which differs from a template to help derive functional and non-functional requirements from use cases

+1

Out of all three, I like ldp-ucr, the most. But even that uses the term "shall" in the requirements extensively

the LDP-UCR document uses the term "shall" indeed, but without any reference to [RFC2119]. It is used in lowercase, and not contrasted with must / should / may ...

[pchampin]

Suggested change

	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
	NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in
	RFC 2119.
	[RFC2119](https://www.rfc-editor.org/rfc/rfc2119.txt), [RFC8174](https://www.rfc-editor.org/rfc/rfc8174.txt)
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
	NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in
	RFC 2119.
	[RFC2119](https://www.rfc-editor.org/rfc/rfc2119.txt), [RFC8174](https://www.rfc-editor.org/rfc/rfc8174.txt)

As discuss, requirements are not conformance clauses (and anyway, the UCR document is non-normative)

[pchampin]

Should we have two "sub-tags" for functional / non-functional requirements?
e.q. [REQ-F] / [REQ-NF]

[pchampin]

Suggested change

	Supporting use-case(s):
	- [link to use-case issue]
	- ...

[pchampin]

• as suggested, I believe that normative language must not be used here
• the proposal below also aims at giving a little more guidance (my 2¢)

Suggested change

	**A [component],**
	**[MUST,SHOULD,MAY...] <<description or requirement>>**
	[component / actor] shall [behave like this | have that property]