w3c
Revise DPV main spec page for ease of access
The DPV specification at https://w3id.org/dpv/2.2/dpv/ is a mammoth document that is difficult and unfriendly in several aspects:
- It is large and it is difficult to navigate when one is unfamiliar with the DPV
- The role of extensions and how they should be used is not clear
- It is difficult to understand where to start
While the Primer provides a simpler (in comparison) introduction, this is not sufficient as per reported experiences. Adopters still find it difficult to understand how the structure of DPV is supposed to help. The specific examples given were:
- how to choose purposes for a health use-case? There are purposes in DPV, EU-EHDS, SECTOR-HEALTH -- but this is apparent only when one knows about this structure of DPV.
- how to understand which extensions or concepts apply for specific use-cases? For example, for AI Act compliance, DPV + AI + EU-AIAct + RISK + TECH extensions might be most relevant.
To address this, a revision of the main DPV spec and the structure of links between extensions is proposed. In this, the main DPV spec will be a short document, similar to how https://www.w3.org/TR/prov-overview/ gives an overview of other documents with a small introduction. The DPV spec should be similarly "condensed" to core descriptions, and the rest of the information should be moved to "module" pages as per the current structure. Additionally, guidance on how to select extensions or common extension collection should be added (e.g. in a table). The existing open issues regarding guides(#242 #377 #242 #221 #220 #191 #103 #66 #67) should be prioritised going ahead for this reason.
Issue contributors: @DelaramGlp @besteves4
Example structure https://harshp.com/dpv-x/dpv-simplification/dpv.html - another section for applications and which extensions are relevant is to be added.
In terms of release management, I think a clear structure (directory/URL organization + artefact generation + release cycle policy) between the spec and the guidance will help us manage things easier as well.
Guidance updates/additions can be made independently of the spec release, for example.
And with that, I think the base URL that shared between the spec and the guidance should be something that is not tied to a spec version. For example, https://w3c.github.io/dpv/, instead of https://w3c.github.io/dpv/2.2/dpv/.
--
On URL, in terms of mental model, a person may also expect that https://w3id.org/dpv/2.2/ or https://w3c.github.io/dpv/2.2/ will bring them to somewhere valid, like a DPV 2.2 spec, not a 404 page.
(Note that https://w3id.org/dpv/ does redirect to the latest DPV spec version, but https://w3id.org/dpv/X.Y/ will not redirect to the X.Y DPV spec version)
Maybe we should include the URL structure as part of consideration when we discuss ease of access too. Provide some documentation "base" URL and a predictable pattern for the user (predictability contributes to accessibility).
For example,
- https://w3c.github.io/dpv/ - base/home (links to specs and guidances)
- https://w3c.github.io/dpv/guides/ - guidances
- https://w3c.github.io/dpv/X.Y/ - spec version X.Y (can be redirected to https://w3c.github.io/dpv/X.Y/dpv/ to keep current structure/generation. btw, as extensions are under this, it means extension release cycle will be the same as the core DPV concept)
We already have (2). (3) is currently a 404. (1) is there but may not be considered as part of "release" or "official publication" (it is a GitHub README).
I would love to see/contribute to a concise https://w3c.github.io/dpv/ that can help ease of access.
Hi @bact thanks for the detailed explanation. I don't think we can implement such change of URL for important reasons.
For (1) https://w3c.github.io/dpv/ that is automatically generated by github from our root repo README. We can change the content of that READ to reflect what should be on the page. The current structure is based on providing a comprehensive overview of all specs + guides.
For (3) https://w3c.github.io/dpv/X.Y/ giving 404 is because the structure is that we don't have an index page at version level i.e. in folder 2.2 there is no index.html. We can put an index to avoid a 404, but by default this url will not direct to DPV because the format for versioned urls is <x.y>/dpv or <x.y>/pd. The prefix before that is something that we do not control. The use of w3id.org/dpv is because initially DPV was the only spec, so we cannot change that IRI now.
For me, we do have a clear structure, but the url of w3id and the w3c github repo creates the complexity you mention. I don't expect most users to be fiddling with urls directly. Giving links to overview pages in the documentation + repo + other places is my preference.
I think if there are both index.html and README.md in the root, GitHub will pick index.html first for GitHub Pages (https://w3c.github.io/dpv/).
This way, we may able to adjust the README.md to targets potential contributors (has more detailed content) and index.html to targets potential users (latest spec, user guide).
@bact I meant index.html in the versioned folder i.e. /2.2/index.html. This way the url https://w3c.github.io/dpv/2.2 should not give a 404 and will show something useful (i.e. overview of what's in 2.2)
Oh. I meant for (1). If we like to use https://w3c.github.io/dpv/ as an overview, we still can. GitHub will not prevent us. We can have the overview as index.html and keep the repo readme as README.md.
okay, I will test this @bact ; assuming it works, what should be put there? Same information as README but with better styling? (if different, let's continue in a separate issue)
The issue is also about the main specification being complex, so regardless of whether the core url has minimal information or not, the proposed changes for main spec should be discussed separately from this.
Agreed that I was mixing two things together: "main page" and "main spec page"
Will put the discussion about main page separately from this main spec page issue.
Update: put is as #400 - demo: https://bact.github.io/dpv/
(using dpvbot:) This was discussed in Meeting 2025-10-29 accepted to add simple version of DPV main spec; to add search feature; and also accepted #400 for simple overview page
(using dpvbot:) This was discussed in Meeting 2025-11-12 The simplified main spec page will be implemented next week for v2.3-dev