Skip to content

Commit

Permalink
Add missing titles for notes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed Jun 1, 2024
1 parent ec39e84 commit 5abaeed
Showing 1 changed file with 61 additions and 40 deletions.
101 changes: 61 additions & 40 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -478,7 +478,7 @@ <h3>Ecosystem Overview</h3>
</figcaption>
</figure>

<p class="note">
<p class="note" title="Other types of ecosystems exist">
<a href="#roles"></a> above provides an example ecosystem in which to ground the
rest of the concepts in this specification. Other ecosystems exist, such as
protected environments or proprietary systems, where
Expand Down Expand Up @@ -947,20 +947,23 @@ <h3>Credentials</h3>
</figcaption>
</figure>

<p class="note">
<p class="note"
title="Credential identifiers can lead to unwanted correlation">
[=Credential=] identifiers can be used to identify specific instances
of a [=credential=]. These identifiers could also be used for unwanted
correlation. A [=holder=] wanting to minimize correlation is advised
to use a selective disclosure scheme that does not reveal the
[=credential=] identifier.
</p>

<p class="note">
<p class="note"
title="Credentials can refer to multiple subjects">
It is possible to have a [=credential=], such as a marriage certificate,
containing multiple [=claims=] about different [=subjects=] that are not
required to be related.
</p>
<p class="note">
<p class="note"
title="Credentials do not have to be about the holder">
It is possible to have a [=credential=] that does not contain any
[=claims=] about the [=entity=] to which the [=credential=] was issued.
For example, a [=credential=] that only contains [=claims=] about a
Expand Down Expand Up @@ -1257,7 +1260,8 @@ <h3>Contexts</h3>
This concept is further expanded on in Section <a href="#extensibility"></a>.
</p>

<p class="note" title="See JSON-LD for more information about @context.">
<p class="note"
title="See JSON-LD for more information about @context.">
In JSON-LD, the `@context` [=property=] can also be used to
communicate other details, such as datatype information, language information,
transformation rules, and so on, which are beyond the needs of this
Expand Down Expand Up @@ -1288,7 +1292,8 @@ <h3>Identifiers</h3>
(`https://id.example/things#123`), and DIDs (`did:example:1234abcd`).
</p>

<p class="note">
<p class="note"
title="Identifiers of any kind increase correlatability">
Developers should remember that identifiers might be harmful in scenarios
where pseudonymity is required. Developers are encouraged to read Section
<a href="#identifier-based-correlation"></a> carefully when considering such
Expand Down Expand Up @@ -1340,7 +1345,8 @@ <h3>Identifiers</h3>
also known as a [=DID=].
</p>

<p class="note">
<p class="note"
title="Decentralized Identifiers are optional">
As of this publication, [=DIDs=] are a new type of identifier that are not
necessary for [=verifiable credentials=] to be useful. Specifically,
[=verifiable credentials=] do not depend on [=DIDs=] and [=DIDs=] do not depend
Expand Down Expand Up @@ -1471,7 +1477,8 @@ <h3>Types</h3>
</tbody>
</table>

<p class="note">
<p class="note"
title="The Verifiable Credentials Data Model is based on JSON-LD">
The [=type=] system for the Verifiable Credentials Data Model is the same as
for [[JSON-LD11]] and is detailed in
<a href="https://www.w3.org/TR/json-ld/#specifying-the-type">Section 3.5:
Expand Down Expand Up @@ -1535,7 +1542,8 @@ <h3>Types</h3>
the same URL.
</p>

<p class="note" title="Creating new verifiable credential types">
<p class="note"
title="See the Implementation Guide for creating new credential types">
Explaining how to create new types of [=verifiable credentials=] is beyond
the scope of this specification. Readers that are interested in doing so are
advised to read the section on
Expand Down Expand Up @@ -1616,7 +1624,8 @@ <h3>Names and Descriptions</h3>
<a href="#language-and-base-direction"></a> for further information.
</p>

<p class="note">
<p class="note"
title="@direction is not required for single-language strings">
The `@direction` property in the examples below is not required
for the associated single-language strings, as their default directions are the
same as those set by the `@direction` value. We include the `@direction` property here
Expand Down Expand Up @@ -1863,7 +1872,8 @@ <h3>Issuer</h3>
}
</pre>

<p class="note">
<p class="note"
title="The identifier for an issuer can be any URL">
The value of the `issuer` [=property=] can also be a JWK (for
example, `"https://example.com/keys/foo.jwk"`) or a [=DID=] (for
example, `"did:example:abfe13f712120431c276e12ecab"`).
Expand Down Expand Up @@ -1939,7 +1949,8 @@ <h3>Validity Period</h3>
}
</pre>

<p class="note">
<p class="note"
title="Validity start period for Verifiable Credentials">
If `validFrom` and `validUntil` are not present, the
[=verifiable credential=] validity period is considered valid
indefinitely. In such cases, the [=verifiable credential=] is assumed to be
Expand Down Expand Up @@ -2554,7 +2565,8 @@ <h4>Presentations Using Derived Credentials</h4>
derived from a [=verifiable credential=].
</p>

<p class="note">
<p class="note"
title="Presentations using Zero-Knowledge Proofs are possible">
For an example of a ZKP-style [=verifiable presentation=] containing
derived data instead of directly embedded [=verifiable credentials=], see
Section <a href="#zero-knowledge-proofs"></a>.
Expand Down Expand Up @@ -2720,7 +2732,8 @@ <h3>Data Schemas</h3>
</dd>
</dl>

<p class="note">
<p class="note"
title="Credential type-specific syntax checking is possible">
The `credentialSchema` [=property=] provides an opportunity to
annotate type definitions or lock them to specific versions of the vocabulary.
Authors of [=verifiable credentials=] can include a static version of their
Expand Down Expand Up @@ -2770,10 +2783,10 @@ <h3>Data Schemas</h3>
[=verifiable credential=] is well-formed.
</p>

<p class="note" >
<p class="note"
title="See Implementation Guide for details on JSON Schema">
For information about linkages to JSON Schema [[?VC-JSON-SCHEMA]] or other
optional schema validation mechanisms, see the Verifiable Credentials
Implementation Guidelines [[VC-IMP-GUIDE]] document.
optional schema validation mechanisms, see the [[[VC-IMP-GUIDE]]] document.
</p>

<p>
Expand Down Expand Up @@ -2934,7 +2947,8 @@ <h3>Trust Model</h3>
models studied by the Working Group, see the [[[VC-USE-CASES]]] [[VC-USE-CASES]].
</p>

<p class="note">
<p class="note"
title="Trust model differs from the traditional Certificate Authority system">
The data model detailed in this specification does not imply a transitive trust
model, such as that provided by more traditional Certificate Authority trust
models. In the Verifiable Credentials Data Model, a [=verifier=] either
Expand Down Expand Up @@ -3153,7 +3167,8 @@ <h4>Semantic Interoperability</h4>
seeking interoperability.
</p>

<p class="note">
<p class="note"
title="Term redefinition is not allowed">
When processing the <a data-cite="JSON-LD11#dfn-active-context">active
context</a> defined by the base JSON-LD Context document <a
href="#dfn-context">defined in this specification</a>, compliant JSON-LD-based
Expand Down Expand Up @@ -3363,7 +3378,8 @@ <h3>Refreshing</h3>
that does not contain public information or whose refresh service is not
protected in some way.
</p>
<p class="note">
<p class="note"
title="Non-authenticated credential refresh">
Placing a `refreshService` [=property=] in a
[=verifiable credential=] so that it is available to [=verifiers=] can
remove control and consent from the [=holder=] and allow the
Expand Down Expand Up @@ -3635,10 +3651,11 @@ <h3>Evidence</h3>
</dd>
</dl>

<p class="note">
<p class="note"
title="See Implementation Guide for strategies for providing evidence">
For information about how attachments and references to [=credentials=] and
non-credential data might be supported by the specification, see the
Verifiable Credentials Implementation Guidelines [[VC-IMP-GUIDE]] document.
[[[VC-IMP-GUIDE]]] document.
</p>

<pre class="example nohighlight"
Expand Down Expand Up @@ -3715,16 +3732,13 @@ <h3>Evidence</h3>
]
}
</pre>
<p class="note">
In this `evidence` example, the [=issuer=] is asserting that they
physically matched the [=subject=] of the [=credential=] to a physical
copy of a driver's license with the stated license number. This driver's license
was used in the issuance process to verify that "Example University" verified
the subject before issuance of the credential and how they did so (physical
verification).
<p>
In the `evidence` example above, the [=issuer=] is asserting that they have
video of the [=subject=] of the [=credential=] demonstrating the achievement.
</p>

<p class="note">
<p class="note"
title="Evidence has a different purpose from securing mechanisms">
The `evidence` [=property=] provides information that is different from and
information to the securing mechanism utilized. The `evidence`
[=property=] is used to express supporting information, such as documentary
Expand Down Expand Up @@ -3804,7 +3818,8 @@ <h3>Zero-Knowledge Proofs</h3>
do not define such a request schema in this specification, but an example of one
method for doing so is [[?PRES-EX]].
</p>
<p class="note">
<p class="note"
title="Take care when designing schemas for selective disclosure">
`credentialSchema` implementers are encouraged to consider the
implications of selective disclosure credentials and provide guidance for
processing depending on the construction. If a schema is not formed with
Expand Down Expand Up @@ -4451,7 +4466,8 @@ <h3>Lists and Arrays</h3>
In general, a JSON array is ordered, while a JSON-LD array is not ordered unless
that array uses the `@list` keyword.
</p>
<p class="note">
<p class="note"
title="Array order might not matter">
While it is possible to use this data model without any JSON-LD processing,
those who do so and make use of arrays need to be aware that unless the above
guidance is followed, the order of items in an array cannot be guaranteed in
Expand Down Expand Up @@ -4981,7 +4997,8 @@ <h3>Spectrum of Privacy</h3>
Privacy solutions are use case specific.
</p>

<p class="note">
<p class="note"
title="Proof of age might be insufficient for some use cases">
Even for those wanting to remain anonymous when purchasing alcohol, photo
identification might still be required to provide appropriate assurance to the
merchant. The merchant might not need to know your name or other details (other
Expand Down Expand Up @@ -5397,7 +5414,8 @@ <h3>The Principle of Data Minimization</h3>
transaction.
</p>

<p class="note">
<p class="note"
title="Minimum disclosure can still lead to unique identification">
While it is possible to practice the principle of minimum disclosure, it might
be impossible to avoid the strong identification of an individual for
specific use cases during a single session or over multiple sessions. The
Expand Down Expand Up @@ -6233,7 +6251,8 @@ <h4>Unauthorized Use</h4>
scopes defined in the `termsOfUse` would be considered unauthorized
use.
</p>
<p class="note">
<p class="note"
title="Digital Rights Management is out of scope">
Further study is required to determine how a [=holder=] can assert and
enforce authorized use of their data after [=presentation=].
</p>
Expand Down Expand Up @@ -6439,7 +6458,8 @@ <h3>Language and Base Direction</h3>
}
</pre>

<p class="note">
<p class="note"
title="Properly rendering internationalized text is challenging">
The text above would most likely be rendered incorrectly as left-to-right
without the explicit expression of language and direction because many systems
use the first character of a text string to determine its [=base direction=].
Expand Down Expand Up @@ -6551,10 +6571,10 @@ <h3>Credential Subject</h3>
identify a [=subject=].
</p>

<p class="note">
<p class="note"
title="Authentication is out of scope">
For information on how authentication and WebAuthn might work with
[=verifiable credentials=], see the Verifiable Credentials Implementation
Guidelines [[VC-IMP-GUIDE]] document.
[=verifiable credentials=], see the [[[VC-IMP-GUIDE]]] document.
</p>

</section>
Expand Down Expand Up @@ -6607,7 +6627,8 @@ <h4>Holder</h4>
[=subject=] and [=holder=].
</p>

<p class="note">
<p class="note"
title="Validation is the process of applying business rules">
Validation is the process by which verifiers apply business rules to
evaluate the propriety of a particular use of a [=verifiable credential=].
</p>
Expand Down

0 comments on commit 5abaeed

Please sign in to comment.