Requirements should be derived from use cases

Typically, after documenting use cases, these are used to establish requirements which can then be referenced back from the specification to determine that given requirements have been satisfied. Requirements are also useful to capture the commonalities between different use cases.

The CSV on the Web: Use Cases and Requirements document is one example of how this can be done.

Are you suggesting that we add a requirements section to the existing use cases, similar to the CSV document?

@gkellogg, @stonematt, we do have requirements in the User Tasks section:

https://opencreds.github.io/vc-use-cases/#user-tasks

@msporny yes, that section is quite a bit different than the others, so we may also have some stylistic consistency issues. Also, in that section, each "requirement" depends on some use cases, which seems backwards.

Typically, I would expect use cases to be narrative of interactions. From each of these, we should be able to derive one or more requirements of a specification that extract a particular behavior identified by the use cases, with multiple use cases pointing to each requirement. Ideally, the specification then becomes a direct response to those requirements; if there is a normative statement, it should derive from some specific requirement.

At this point, the issue is for the WG to consider if it wants to take this approach.

Also, in that section, each "requirement" depends on some use cases, which seems backwards.

Hmm, the way I read it is that each requirement points to the "Needs" of a particular use case. So I think the word "Needs" is being interpreted in two different ways by each of us. I think your interpretation is "This requirement needs this use case", and my interpretation is "This requirement refers to a need from this use case". Is that right? Perhaps we need to use different terminology like "Requirement Derived From" or "Use Cases"?

I admit that the current layout is different from what I'm used to, but I think I like it. The document speaks loosely about the user roles and user needs of the ecosystem, and then it defines the requirements at the end.

In any case, I think @jandrieu may have some strong feelings about the layout of the document and has explained his thinking about the construction of the document elsewhere (but I have no clue where I may have read about/heard about it).

@gkellogg I believe the mapping from use case to requirement that you're looking for is essentially what the current document attempts to do when mapping from User Needs to User Tasks. That work has room for improvement, but I think that's where we'll find the best fit for the sort of requirements tracking you're asking for.

One challenge with the current language is that both "use case" and "requirements" are poorly defined. This is a universal problem in software development. The two terms are useful enough without a rigorous definition that they are used regularly with different meanings. This is true of many of the terms we need to use.

In my practice, functional requirements are represented by use cases: the functional requirement is that the system supports a particular set of use cases. I represent use cases in any number of ways, from high level titles to scenarios to detailed narratives, each a specific way to describe the same use case and I present them in maps and engagement models to give perspective on the whole.

For example, what I mean by narrative is probably not what you mean. Not that you are wrong to use it that way, just that we haven't established a common ground so we both can use the same terms the same way.

The way I use "narrative"--both concrete and essential narratives--is based on the work of Constantine and Lockwood in Software for Use. From context, I believe that what you described as a narrative is closer to what I call a Scenario, which is a brief prose description of an individual's interaction with the system in a particular use case.

In short, semantics are slippery and will require bringing people up to speed, which is key to building consensus around which use cases we support and what each implies. My presentation at the face-to-face meeting in October shared my general approach, in part, to start baselining a common language as we move forward. https://docs.google.com/presentation/d/1WWsv3Y1gcHzR1bE_CBbNxBTrIN1vDw_RohuPqUyfUxs/edit#slide=id.p3

There are also non-functional requirements, e.g., based on security or performance or regulatory compliance. Any and all of these could be a "specification" in that they are formally specified. This is an area where we have significant hidden assumptions which may or may not be appropriate for formalizing in the specification.

For example, I know that certain privacy and/or security requirements can be addressed by public/private key encryption and signing, but these requirements are nearly absent in the use case document. There is one mention of a signed credential in F1. Reuse Know Your Customer, but what that means is taken as given. And the string "crypt" is completely absent from the document: no "encryption", no "cryptographic".

Part of the reasoning behind this is to separate the requirements from the implementation choices. However, we have already had numerous conversations about what signature mechanisms are suitable. One challenge with these conversations is that we have almost nothing in our requirements model (as captured in the Use Cases document) that can provide a foundation for evaluating one approach relative to another. There's an assumption that we need certain technology, but little in the formal record to base technical decisions on.

This is a huge area for improvement: how can we capture the use cases that are driving our decisions about signatures?

So... once we get an update to the Use Case framework in place, I expect we will need to support flexibility in adjusting/updating the use cases to respond to what we learn in our technical discussions. I can guarantee that we will discover we missed some things no matter how diligent we try to be at the beginning. Which is why I call it requirements modeling: it is certainly incomplete and we'll be updating the model as we go. I expect this is why most W3C groups take the starting use cases as an initial vector without letting them formally limit development as the group moves forward.

At the same time, I want to acknowledge that, as you suggest, the approach itself is open to as much scrutiny and consensus as the content we put into it. So, I'll put together some additional framing to help the group make decisions about how we want to represent the use cases in our work.

This also applies to: https://github.com/opencreds/vc-use-cases/issues/20#issuecomment-271626669 alongside some of the other use-cases that were developed. It has been suggested that we simplify the use-cases; however, i'm not sure that is in fact the best approach given the rather radical implications for human activity the transference of 'claims' to online brings with it and the rather significant risk that these things are always easy to do badly.

akin to the often underestimated difficulties of producing a well-formed identity solution/framework.

it's easy to build a bad one; but really difficult to build a good one.

The current use-cases that have remained from the years of effort appear to focus upon the needs of 'persona ficta' actors; and many of the underlying principles / considerations pertaining to means of breaking down the claims structures (ie: simply over 18/21, not DOB, et.al), privacy, means to ensure user has an account/ledger record for the use of their cred/verifiable claim; all sorts of things about human actors and the use of these things in the interests of those people (even in cases where their actions need to be established on behalf of an organisational actor) are seemingly falling through the cracks - at least that is amongst my higher levels/areas of concern.

The works also seek to use 'linked data' / RDF. An on-going issue has been one of how that is communicated in specs, where an offered opinion has been "Neither TURTLE nor JSON-LD should be mandated in any RDF based spec. RDF is a Language associated with many notations." https://lists.w3.org/Archives/Public/public-webpayments/2014Jul/0083.html

Yet the bigger underlying challenge is in ensuring those who are more familiar with json/api or similar related methods can have it conveyed to them, the areas in which former non-rdf methods are simply not capable of providing similar characteristics. (even though these technologies may be unfamiliar to them and therefore require more effort to 'learn').

certainly if a 'technical expert' believes 'semantic web was a thing a few years ago that died' - then they may strongly argue for an array of alternative methodologies with that misunderstanding at the heart of their considerations.

It was also said to me sometime ago the difference between 'user stories' and 'use-cases' (being that the use-cases can be derived from user-stories).

In Summary; This continues to be a complex endeavors and amongst the bigger challenges is seemingly ensuring participants (and potential participants / contributors) have a good understanding of the underlying foundations to these works; alongside a fairly clear understanding of what it is the group is attempting to achieve and what the core principles to all use-cases include.

Whilst it is understood some groups prefer JSON-LD vs. N3 (et.al.) this is to some degree a distraction and should ideally be managed as part of the broader league of professionals (rather than simply focusing on the needs of 'a team')

If we do produce more sophisticated documentation around the use of VCs in their various iterations, and even indeed use badges to support the processes (and clarifications) this is likely to assist down the track as implementers and their stakeholders seek to have illustrative means in which to communicate to diverse stakeholders the opportunity and technical / operational implications.

FINALLY: VERSION CONTROL SYSTEMS...

Building a verifiable claims methodology in a manner that 'looses' works provided by previous contributors in earlier iterations is a less than ideal situation.

of implicit interest other areas of work such as: http://standards.ieee.org/develop/indconn/ec/autonomous_systems.html

Need means in which to cooperatively work with VCWG and, should RDF be elected, consider what ontological needs may be considered as to ensure we have a framework that provides progress to the broader contextual considerations of trust vs. more simplistic means that may erode them.

I'll follow-up with some more constructive considerations, which is my intent overall.

@msporny:

So I think the word "Needs" is being interpreted in two different ways by each of us. I think your interpretation is "This requirement needs this use case", and my interpretation is "This requirement refers to a need from this use case". Is that right?

Sure, I can see this interpretation.

@jandrieu:

I believe the mapping from use case to requirement that you're looking for is essentially what the current document attempts to do when mapping from User Needs to User Tasks.

Yes, in that light, User Tasks is the requirements derived from the use cases. It would be useful if each use case in User Roles was referenced from such a requirement, otherwise it either represents an unmet need, or is not, in fact, a necessary use case; this is of course also valid information, and should probably be described as such. (H.3, L.2, L.3, and L.4 are the ones I've found that are not referenced).

For example, what I mean by narrative is probably not what you mean.

Scenario may be a better term; scenarios are typically written in a narrative form.

There are also non-functional requirements...

Indeed, but we may be able to describe some scenario which motivates the requirement, perhaps not a narrative. It's up to us to decide how exhaustive to be; if these requirements are clear, I wouldn't expect to be challenged on the lack of an associated scenario, but it would be useful to have the requirement stated none the less. Perhaps we can import requirements and/or use cases from related work.

Ultimately, we just need to be sure that people know what their looking for. W3C UCR documents are common, and if there are common patterns we can draw on, that might help avoid confusion. For example, it wasn't obvious to me that the User tasks section would essentially describe our requirements (a more detailed look makes this clear). For example, it may be useful to have our requirements numbered, similar to how use cases are numbered, and change the section name to "Requirements", if indeed that is how it's intended.

@gkellogg We're still a bit out of sync on terms. I'm using "Narrative" in a very specific way, distinct from a prose description and while we agree that "Scenario" is aligned with what you meant, I can't use "narrative" to describe it because "Narrative" is a term of art.

This distinction, along with @mediaprophet's observations, suggests that in order to promote conversation and consensus, we have to do better at using the simplest, most familiar terms, and providing the guidance to distinguish what those terms mean in an accessible way.

I'm particularly sensitive to this need because the language in my own practice is evolving. I'm open to alternatives that improve rigor, yet also wary of suggestions that introduce vagueness.

For example, the term "requirements" as you, @gkellogg, use it, doesn't map cleanly to a rigorous definition for me. For example, both use cases and user stories are ways to capture requirements. In my practice, the use cases are the functional requirement: serve these use cases. I use non-functional requirements to capture performance, security, and privacy needs as well as other constraints (budget, schedule, technology, etc).

I've spent some time reviewing the CVS On the Web (CSVW) Use Cases . I like it. It's a coherent and exhaustive representation of the use cases for CVSW. It gives a great review of how CVS is actually used on the web.

It is a challenging read for me, however, because it uses "Use Cases" and "Requirements" in a way that differs from my own practice. To wit, building on Constantine & Lockwood's work, I prefer to boil use cases down to a specific human-system interaction, where the CVS document treats use cases as situations in which CSV on the Web is, or could be, used:

The City of Palo Alto, California Urban Forest Section is responsible for maintaining and tracking the cities public trees and urban forest. In a W3C Data on the Web Best Practices (DWBP) use case discussion with Jonathan Reichental City of Palo Alto CIO, he brought to the working groups attention a Tree Inventory maintained by the city in a spreadsheet form using Google Fusion. This use case represents use of tabular data to be representative of geophysical tree locations also provided in Google Map form where the user can point and click on trees to look up row information about the tree.

The example below illustrates the first few rows of data:

CSV is, of course, an incredibly mature format, with lots of usage and lots of variations, for example, Use Case #9 Chemical Imaging states "All values are comma separated, but they can be delimited by tabs as well." This type of legacy variation suggests that simply capturing all the multiple ways that CSV is currently in use is a good way to discover the requirements for CSVW. However, it is worth noting that several "Requirements" are cited in use cases, then later noted as "beyond the scope":

R-MultipleHeadingRows Ability to handle headings spread across multiple initial rows, as well as to distinguish between single column headings and file headings. Row headings should be distinguished from file headings (if present). Also, in case subheadings are present, it should be possible to define their coverage (i.e. how many columns they refer to).

Motivation: PublicationOfNationalStatistics, AnalyzingScientificSpreadsheets, IntelligentlyPreviewingCSVFiles, CollatingHumanitarianResponseInformation, ExpressingHierarchyWithinOccupationalListings and PlatformIntegrationUsingSTDF.

NOTE The Working Group decided to rule headings spanning multiple columns out of scope. However, it is possible to skip initial rows that do not contain header information using skipRows and to specify that a table contains multiple header rows using headerRowCount when describing a dialect, as described in [tabular-metadata].

I can appreciate that we will also be dealing with needs and concepts that are beyond our scope of work. However, it seems to me that if something is beyond the scope of work, it isn't a proper requirement, because by definition it will not be required to be compliant.

Finally, I want to acknowledge that my experience comes from building user interfaces and applications. CSVW is focused on representations of a data model embedded in existing protocols (on the web). The Verifiable Claims work will initially also focus on a data model and not on the eventual protocols, architectures, or applications that might use that data model. As such, maybe we should entertain a more documentary-like approach of cataloguing existing activity that could be improved with Verifiable Claims.

My counter to that possible focus is that I believe there remains significant confusion in the marketplace about how claims and/or attributes should best be combined to provide identity-based capabilities. In other words, unlike CSV where there are undoubtedly thousands if not millions of instances of CSV being published on the web, the world of "identity" is littered with the remains of once promising solutions. Our use cases don't have a network of cowpaths to document. Instead, we need to explain in the most technology-independent way what real-world problems our proposed approach addresses, and we need to clearly link those problems to our proposed solution. And I agree our current document can use improvement in that.

One area that is sorely lacking is a concise list of non-functional requirements and their motivation. These are scattered throughout the User Tasks in ways that are not always clear where they come from. For example, the Requirement in 4.1 Issue Claim states:

It must be possible for any entity to issue a verifiable claim.

I don't know if that is a description of "Issue Claim" or if it is an additional requirement of the capability of claims issuance. The motivation listed is:

Individuals and organizations need a way to issue claims about themselves or others that can be verified and trusted.

This motivation is essentially tautological. The motivation for issuing claims is because entities need to issue claims? It also doesn't explain the motivation for allowing ANY entity can issue a claim. This is a significant requirement. I get that there are some understood limitations of entities (they are all capable of operating software connected to the Internet) and we should probably spell these out. But for this use case in particular, the requirement as stated suggests the goal of moving beyond Certificate Authorities and top-down addressing and naming systems. If that's true we should clarify that the necessary capability is that claims can be issued without participation or approval of external authorities, and be clear that there is no presumption that entities are registered with or approved by anyone else. IMO, this requirement gets buried in this section.

The motivation could be discussed any number of ways, depending on the use case. For web of trust use, the point is to enable peer-to-peer communities independent of authoritarian oversight. For refugees, the need is for aid workers and border agents to be able to keep track of refugees without alerting potentially hostile parties--either because their ethnic heritage itself might trigger harm in their current location or because the regime from which they fled might harm friends and family. In both cases, the value of issuing a claim independent of central authority is clear.

To address your concerns, I recommend we:

Convert User Tasks to well-formed Use Cases a. Single value-creating transaction (most are already) b. Clear Action/Reaction (also pretty good today) c. Explained with a Scenario (prose description of the interaction)
Illustrate all User Tasks with Essential Narratives (described in issue #33)
Separate non-functional requirements into their own list
Consider renaming User Tasks to Capabilities
Expand, concisely, the section explaining our process-related terms, e.g., use case, narrative, etc.

+1 to @jandrieu's suggestions above. Let's let him make another pass on the document making these changes and see where we are after the dust has settled.

+1 @jandrieu this looks like a good approach.

Very thought provoking and interesting discussion all - that is helpful for some of my current work on both the definition and disambiguation of use cases, and user needs and the requirements for both in some of my work at W3C.

Unfortunately, restructuring as proposed by me in January of 2017 ended up being more work than sensible.

w3c / vc-use-cases

Requirements should be derived from use cases #30