Skip to content

Update introductory examples. #52

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

Open
wes-smith wants to merge 3 commits into
base: main
Choose a base branch
from
+156 −129
Open

Update introductory examples. #52

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
48ea8e0
Apply grammar and wording updates.
wes-smith May 4, 2026
4690a6d
Update introductory DL example.
wes-smith May 4, 2026
53f2dc0
Reorder and modernize introductory examples.
wes-smith May 4, 2026
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
285 changes: 156 additions & 129 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,20 +272,94 @@ <h2>Introductory Examples</h2>
specification can be used to enhance existing physical credentials with
digital signatures via [=verifiable credentials=].
</p>
<section>
<h3>Birth Certificate</h3>

<p>
This section provides an example of how the technology in this specification can
be used to secure a birth certificate as a [=verifiable credential=], which
is then expressed as a QR Code on the printed paper document.
</p>

<figure id="birth-certificate">
<img style="margin: auto; display: block; border-radius:15px; width: 50%;"
src="diagrams/bc-front.png"
alt="A picture of the front of a birth certificate containing information such as the newborn's name, parent's names, information about the hospital, attendees, and person responsible for the registration.">
<figcaption style="text-align: center;">
The front of a birth certificate issued by a hospital in the state of Utopia.
</figcaption>
</figure>

<p>
The QR Code encodes the following [=verifiable credential=]. The details of
the encoding are available as separate tabs below:
</p>

<pre class="example vc nohighlight"
title="A verifiable credential expressing a short-form birth certificate"
data-vc-vm='https://vital-records.utopa.example/issuers/123'
data-vc-tabs="cbor-ld qr">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/vital-records/v1rc1"
],
"type": [
"VerifiableCredential",
"BirthCertificateCredential"
],
"issuer": "https://hospital.example/issuer",
"validFrom": "2023-09-30T11:30:00Z",
"credentialSubject": {
"type": "BirthCertificate",
"certificationDate": "2023-09-30T13:44:52Z",
"newborn": {
"type": "Newborn",
"name": "Tim Doe",
"gender": "Male",
"birthDate": "2023-10-05T14:29:00Z",
"birthPlace": {
"type": "PostalAddress",
"streetAddress": "123 Hospital Rd",
"addressLocality": "Utopia Town",
"addressRegion": "Utopolis",
"postalCode": "12345",
"addressCountry": "Utopia"
},
"parent": [{
"type": "Mother",
"name": "Jane Doe",
"namePriorToMarriage": "Jane Smith"
}, {
"type": "Father",
"name": "John Doe"
}]
}
}
}
</pre>
<p>
This is an example of a straightforward use case where a barcode
containing a [=verifiable credential=] is added to a document
that does not currently contain machine-readable data. Once
the [=verifiable credential=] is issued and compressed with CBOR-LD,
the CBOR-LD payload can be added to a QR code and the QR code added
to the physical document.
</p>
</section>
<section>
<h3>Driver's License</h3>

<p>
This section provides an example on how the technology in this specification
can be utilized to secure the optical barcode on a driver's license that
uses a PDF417 barcode. We start off with an example driver's license:
This section provides an example of how the technology in this specification
can be used to secure a PDF417 optical barcode on a driver's license. We start
with an example driver's license:
</p>

<figure id="dl-front">
<img style="margin: auto; display: block; border-radius:15px; width: 50%;"
src="diagrams/dl-front.png"
alt="Picture of the front of a driver's license issued by the state of Utopia which contains a picture of the individual that is the subject of the driver's license along with their attributes, such as name, address, height, weight, eye color, and driving privileges.">
alt="Picture of the front of a driver's license issued by the state of Utopia, containing a picture of the individual that is the subject of the driver's license along with their attributes, such as name, address, height, weight, eye color, and driving privileges.">
<figcaption style="text-align: center;">
The front of a driver's license issued by the state of Utopia.
</figcaption>
Expand All @@ -306,75 +380,88 @@ <h3>Driver's License</h3>

<p>
The PDF417 data contains information that is secured using the algorithms
described in this specification. Namely, the PDF417 barcode contains a
<a>verifiable credential</a> of the following form.
described in this specification. More specifically, the PDF417 barcode
contains a [=verifiable credential=] of the following form.
</p>

<pre class="example nohighlight"
title="Verifiable Credential embedded in the PDF417 barcode">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/vdl/v2",
"https://w3id.org/vdl/utopia/v1"
"https://w3id.org/vc-barcodes/v1",
"https://w3id.org/utopia/v2"
],
"type": [
"VerifiableCredential",
"OpticalBarcodeCredential"
],
<span class="comment">// the issuer value below is defined as a URL in the 'utopia/v1' context above</span>
"issuer": "did:web:dmv.utopia.example",
"credentialStatus": {
"type": "TerseBitstringStatusListEntry",
"terseStatusListBaseUrl": "https://dmv.utopia.gov/statuses/12345/status-lists"
"terseStatusListIndex": 123567890
},
"credentialSubject": {
"type": "AamvaDriversLicenseScannableInformation",
"protectedComponentIndex": "uP_BA"
"protectedComponentIndex": "uggAg"
},
"issuer": "did:key:zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj",
"credentialStatus": {
"type": "TerseBitstringStatusListEntry",
"terseStatusListBaseUrl": "https://sandbox.platform.veres.dev/statuses/z19rJ4oGrbFCqf3cNTVDHSbNd/status-lists",
"terseStatusListIndex": 3851559041
},
"proof": {
"type": "DataIntegrity",
"type": "DataIntegrityProof",
"verificationMethod": "did:key:zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj#zDnaeWjKfs1ob9QcgasjYSPEMkwq31hmvSAWPVAgnrt1e9GKj",
"cryptosuite": "ecdsa-xi-2023",
<span class="comment">// the public key below is defined as a URL in the 'utopia/v1' context above</span>
"verificationMethod": "did:web:dmv.utopia.example#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z4peo48uwK2EF4Fta8P...HzQMDYJ34r9gL"
"proofValue": "z4g6G3dAZhhtPxPWgFvkiRv7krtCaeJxjokvL46fchAFCXEY3FeX2vn46MDgBaw779g1E1jswZJxxreZDCrtHg2qH"
}
}
</pre>

<p>
The <a>verifiable credential</a> above is then compressed using [[CBOR-LD]]
This is an example of the use case where a barcode is augmented with
a [=verifiable credential=]. As such, the subject of the credential is the
other data in the barcode that is protected by the Verifiable Credential's
digital signature. The `protectedComponentIndex` field in
`credentialSubject` indicates exactly what data in the rest of the barcode
is protected.
</p>
<p>
The <a>verifiable credential</a> above is compressed using [[CBOR-LD]]
to the following output (in CBOR Diagnostic Notation):
</p>

<pre class="example nohighlight"
title="CBOR-LD compressed Verifiable Credential (145 bytes)">
1281{
1 => [ 32768, 32769, 32770], <span class="comment">// @context</span>
155 => [ 116, 164 ], <span class="comment">// type</span>
192 => 174, <span class="comment">// issuer</span>
186 => { 154 => 166, 206 => 178, 208 => 1234567890 }, <span class="comment">// credentialStatus</span>
188 => { 154 => 172, 180 => h'753FF040 }, <span class="comment">// credentialSubject</span>
194 => { <span class="comment">// proof</span>
154 => 108, <span class="comment">// type</span>
214 => 4, <span class="comment">// cryptosuite</span>
224 => 230 <span class="comment">// verificationMethod</span>
228 => 176, <span class="comment">// proofPurpose</span>
210 => Uint8Array(65) [ ... ], <span class="comment">// proofValue</span>
title="CBOR-LD compressed Verifiable Credential">
51997([
100,
{
1: [32768, 32769, 32770], <span class="comment">// @context</span>
157: [118, 164], <span class="comment">// type</span>
184: {156: 166, 206: 178, 208: 3851559041}, <span class="comment">// credentialStatus</span>
186: {156: 160, 168: h'75820020'}, <span class="comment">// credentialSubject</span>
190: 170, <span class="comment">// issuer</span>
192: { <span class="comment">// proof</span>
156: 108,
214: 4,
224: 230,
226: h'7AB...',
228: 172
}
}
])
</pre>
<p>
Once encoded as CBOR-LD, the [=verifiable credential=] is inserted into the
PDF417. For more details regarding this example, see Section
<a href="#test-vectors"></a>.
</p>

</section>

<section>
<h3>Employment Authorization</h3>

<p>
This section provides an example on how the technology in this specification
can be utilized to secure the machine-readable zone on an employment
This section provides an example of how the technology in this specification
can be used to secure the machine-readable zone (MRZ) of an employment
authorization document that uses a machine-readable zone (MRZ) on the back of
the card. We start off with an example employment authorization document:
</p>
Expand Down Expand Up @@ -405,8 +492,8 @@ <h3>Employment Authorization</h3>

<p>
The MRZ data contains information that is secured using the algorithms
described in this specification. Namely, the QR Code on the front of the
card contains a <a>verifiable credential</a> of the following form, which secures
described in this specification. Specifically, the QR Code on the front of the
card contains a [=verifiable credential=] of the following form, which secures
the information on the back of the card.
</p>

Expand All @@ -415,126 +502,66 @@ <h3>Employment Authorization</h3>
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/citizenship/v2",
"https://w3id.org/citizenship/utopia/v1"
"https://w3id.org/vc-barcodes/v1",
"https://w3id.org/utopia/v2"
],
"type": [
"VerifiableCredential",
"OpticalBarcodeCredential"
],
<span class="comment">// the value below is defined as a URL in the 'utopia/v1' context above</span>
"issuer": "did:web:immigration.utopia.example",
"credentialSubject": {
"type": "MachineReadableZone",
"type": "MachineReadableZone"
},
"issuer": "did:key:zDnaeZSD9XcuULaS8qmgDUa6TMg2QjF9xABnZK42awDH3BEzj",
"proof": {
"type": "DataIntegrity",
"type": "DataIntegrityProof",
"verificationMethod": "did:key:zDnaeZSD9XcuULaS8qmgDUa6TMg2QjF9xABnZK42awDH3BEzj#zDnaeZSD9XcuULaS8qmgDUa6TMg2QjF9xABnZK42awDH3BEzj",
"cryptosuite": "ecdsa-xi-2023",
<span class="comment">// the value below is defined as a URL in the 'utopia/v1' context above</span>
"verificationMethod": "did:web:immigration.utopia.example#key-4"
"proofPurpose": "assertionMethod",
"proofValue": "z4peo48uwK2EF4Fta8P...HzQMDYJ34r9gL"
"proofValue": "z4B8..."
}
}
</pre>

<p class="note" title="credentialStatus is optional">
Readers might note that the credential above does not contain the optional
`credentialStatus` property. Not every optical barcode credential issuer will
have the requirement to have revocable optical barcode credentials.
require that the optical barcode credentials they issue be revocable.
</p>
<p>
Similarly to the previous example, here we are augmenting existing
machine-readable data (an MRZ) on a document with a [=verifiable credential=].
As such, the subject of the credential is the MRZ.
</p>

<p>
The <a>verifiable credential</a> above is then compressed using [[CBOR-LD]]
The [=verifiable credential=] above is compressed using [[CBOR-LD]]
to the following output (in CBOR Diagnostic Notation):
</p>

<pre class="example nohighlight"
title="CBOR-LD compressed Verifiable Credential (120 bytes)">
51997([
100,
{
1 => [ 32768, 32769, 32770], <span class="comment">// @context</span>
155 => [ 116, 176 ], <span class="comment">// type</span>
208 => 194, <span class="comment">// issuer</span>
204 => { 154 => 192 }, <span class="comment">// credentialSubject</span>
210 => { <span class="comment">// proof</span>
154 => 108, <span class="comment">// type</span>
226 => 4, <span class="comment">// cryptosuite</span>
236 => 242 <span class="comment">// verificationMethod</span>
240 => 196, <span class="comment">// proofPurpose</span>
210 => Uint8Array(65) [ ... ], <span class="comment">// proofValue</span>
1: [32768, 32769, 32770], <span class="comment">// @context</span>
157: [118, 164], <span class="comment">// type</span>
186: {156: 162}, <span class="comment">// credentialSubject</span>
190: 174, <span class="comment">// issuer</span>
192: { <span class="comment">// proof</span>
156: 108,
210: 4,
220: 226,
222: h'7A9EC7F688F60CAA8C757592250B3F6D6E18419941F186E1ED4245770E687502D51D01CD2C2295E4338178A51A35C2F044A85598E15DB9AEF00261BC5C95A744E7',
224: 176
}
}
])
</pre>

</section>

<section>
<h3>Birth Certificate</h3>

<p>
This section provides an example on how the technology in this specification can
be utilized to secure a birth certificate as a [=verifiable credential=], which
is then expressed as a QR Code on the printed paper document:
Once encoded as CBOR-LD, the [=verifiable credential=] is inserted into the
PDF417. For more details regarding this example, see Section
<a href="#test-vectors"></a>.
</p>

<figure id="birth-certificate">
<img style="margin: auto; display: block; border-radius:15px; width: 50%;"
src="diagrams/bc-front.png"
alt="A picture of the front of a birth certificate containing information such as the newborn's name, parent's names, information about the hospital, attendees, and person responsible for the registration.">
<figcaption style="text-align: center;">
The front of a birth certificate issued by a hospital in the state of Utopia.
</figcaption>
</figure>

<p>
The QR Code encodes the following [=verifiable credential=]. The details of
the encoding are available as separate tabs below:
</p>

<pre class="example vc nohighlight"
title="A verifiable credential expressing a short-form birth certificate"
data-vc-vm='https://vital-records.utopa.example/issuers/123'
data-vc-tabs="cbor-ld qr">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/vital-records/v1rc1"
],
"type": [
"VerifiableCredential",
"BirthCertificateCredential"
],
"issuer": "https://hospital.example/issuer",
"validFrom": "2023-09-30T11:30:00Z",
"credentialSubject": {
"type": "BirthCertificate",
"certificationDate": "2023-09-30T13:44:52Z",
"newborn": {
"type": "Newborn",
"name": "Tim Doe",
"gender": "Male",
"birthDate": "2023-10-05T14:29:00Z",
"birthPlace": {
"type": "PostalAddress",
"streetAddress": "123 Hospital Rd",
"addressLocality": "Utopia Town",
"addressRegion": "Utopolis",
"postalCode": "12345",
"addressCountry": "Utopia"
},
"parent": [{
"type": "Mother",
"name": "Jane Doe",
"namePriorToMarriage": "Jane Smith"
}, {
"type": "Father",
"name": "John Doe"
}]
}
}
}
</pre>

</section>

</section>
Expand Down
Loading