Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added an SVG diagram of the vocabulary. #1236

Merged
merged 9 commits into from
Aug 20, 2023
Merged

Added an SVG diagram of the vocabulary. #1236

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
255185d
Added an SVG diagram of the vocabulary.
iherman Aug 14, 2023
90f26e0
Changed the background color for reserved terms
iherman Aug 16, 2023
1992cf7
Unnecessary namespace usage in a script.
iherman Aug 17, 2023
fb7748f
Added reserved confidenceMethod property to the vocabulary.
iherman Aug 15, 2023
b0884d1
Added reserved class to diagram
iherman Aug 18, 2023
054d2d5
Updated diagram for dark mode
iherman Aug 19, 2023
23a0bac
Added a graph containment connector in the diagram
iherman Aug 20, 2023
212b4e1
Minor updates on the diagram description text
iherman Aug 20, 2023
196b12e
Fix typo in vocabulary diagram description.
msporny Aug 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions vocab/credentials/v2/template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,15 @@
const p = sotd.getElementsByTagName('p')[0];
sotd.removeChild(p);
}
// Note: The vocabulary URL must be adapted for the given environment!!!!
function massageSVGLinks(utils, content, url) {
const retval = content
.replace('<svg', '<svg aria-details="#vocabulary-diagram-alt" ')
.replace(/xlink:href/g, 'href')
.replace(/href="https:\/\/w3.org\/2018\/credentials\/#/g, 'href="#');
return retval;
}

</script>
<script class="remove">
var respecConfig = {
Expand Down Expand Up @@ -104,6 +113,17 @@
box-shadow: 0 2px 8px black;
text-align: center;
}

/* This is a bug in the base css setting at W3C. There is an open PR raised for it in the
relevant github repo; if and when that is merged, this statement may become
superfluous.
See https://github.com/w3c/tr-design/pull/336
*/
figure svg {
max-width: 100%;
margin: auto;
height: auto;
}
</style>
</head>
<body typeof="owl:Ontology">
Expand Down Expand Up @@ -141,6 +161,24 @@ <h2>Specification of terms</h2>
<p>
In some cases, a local explanation is necessary to complement, or to replace, the definition found in an external specification. For instance, this is so when the term is needed to provide a consistent structure to the RDFS vocabulary, such as when the term defines a common supertype for class instances that are used as objects of specific properties, or when <a href="https://www.w3.org/TR/rdf12-concepts/#section-rdf-graph">RDF Graphs</a> are involved. For such cases, the extra definition is included in the current document (and the `rdfs:comment` property is used to include them in the RDFS representations).
</p>
<figure id="vocabulary-diagram" style="text-align:center">
<!--
Original diagram is in https://drive.google.com/file/d/1-kg7AzhahSzIwiIHeh5ANGJB_JK-kugs/view?usp=drive_link
using the draw.io (diagrams.net plugin for google).
The diagram is exported into SVG, and then the following editorial changes should be done (using any text editor):
- The "width" and "height" attributes in the top level <svg> element must be removed (to make the diagram rescale if
viewed directly)
- add the aria-details="#vocabulary-diagram-alt" attribute to the top level svg element

The exported SVG can also be viewed and edited inkscape. (The reason draw.io is used, instead of using
exclusively inkscape, is because the connecting line feature of inkscape is buggy.)
-->
<div data-include="vocabulary.svg" data-include-replace="true" data-oninclude="massageSVGLinks"></div>
<figcaption>Overview diagram of the vocabulary (without the deprecated items).<br />
A separate, stand-alone <a href="vocabulary.svg" target="_blank">SVG version</a> of the diagram, as well as a <a href="#vocabulary-diagram-alt">textual description</a>,
are also available.
</figcaption>
</figure>
</section>
<section>
<h2>Namespaces</h2>
Expand Down Expand Up @@ -207,6 +245,55 @@ <h2>Deprecated individuals</h2>
</section>
</section>

<section class="appendix" id="vocabulary-diagram-alt">
<h2>Diagram description</h2>
<details>
<summary>Overview diagram of the vocabulary (without the deprecated items).</summary>
<p>
The diagram uses boxes, ellipses, and connecting lines with different "styles" (border color, end
marker, line type) to differentiate their semantic meaning; these styles identify
Property and Class used for shapes used for graph nodes, and Subclass, Domain, and Range for connector lines.
These style names are used in the explanation text in what follows.
</p>
<p>
In the middle of the diagram there is a column of labeled boxes, all styled as Property.
The labels, from top to bottom, are: "credentialSchema",
"credentialStatus", "credentialSubject", "issuer", "evidence",
"refreshService", "renderMethod", "confidenceMethod", "termsOfUse", "validFrom",
"validUntil", and "holder".
On the left side of this column, there are four labeled ellipses, styled as Class.
These are, from top to bottom, "VerifiableCredential", "JsonSchemaCredential",
"VerifiableCredentialGraph", and "VerifiablePresentation".
There is also a single circle, not styled as Property or Class, labeled as "OR", and another box
styled as a Property labeled as "verifiableCredential".
</p>
<p>
The "VerifiableCredential" ellipse is connected through a connecting line
styled as Domain to the "credentialSchema", "credentialStatus", "credentialSubject",
"issuer", "evidence", "refreshService", "renderMethod", and "confidenceMethod" boxes.
It is also related to the separate "OR" circle with a similar connecting line.
The "VerifiablePresentation" ellipse is connected to the "OR" box, as well as the "holder"
and "verifiableCredential" boxes with a similar connecting line styled as Domain.
The OR box is connected to the "termsOfUse", "validFrom", and "validUntil" boxes with a connecting line styled as Domain.
The "verifiableCredential" box is connected to the "VerifiableCredentialGraph" ellipse with a connecting
line styled as Range.
The ellipse "JsonSchemaCredential" is connected to the ellipse labelled "VerifiableCredential" with a
connecting line styled as Subclass.
Finally, the "VerifiableCredentialGraph" ellipse is connected, through a uniquely styled connector and with a text "contains" <em>on</em> the connector
line, to the "VerifiableCredential" ellipse.
</p>
<p>
On the right hand side of the column there is an extra column of ellipses styled as "Class", and labeled as "CredentialSchema",
"CredentialStatus", "CredentialEvidence", "RefreshService", "ConfidenceMethod", and "TermsOfUse".
The Property boxes labeled as "credentialSchema", "credentialStatus", "credentialEvidence,
"refreshService", "confidenceMethod", and "termsOfUse" are all connected by connecting lines styled as Range to these
ellipses, respectively.
On the right hand side of the diagram there is one more ellipse styled as Class and labeled as
"JsonSchema", connected to the the ellipse labeled as "CredentialSchema" via a connecting line
styled as Subclass.
</p>
</details>
</section>


</body>
Expand Down
Loading