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 reserved confidenceMethod property to the vocabulary #1226

Closed
wants to merge 7 commits into from
Closed

Added reserved confidenceMethod property to the vocabulary #1226

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
22e3730
Add section on Ecosystem Compatibility. (#1203)
msporny Aug 2, 2023
6592f3b
Update reservation table
OR13 Jun 6, 2023
0ca0f70
Update contexts/credentials/v2
OR13 Jun 6, 2023
839c3b4
Update URL to add confidenceMethod specification.
msporny Aug 1, 2023
f3e2b30
Update index.html
OR13 Aug 2, 2023
cf429b1
Update index.html
brentzundel Aug 2, 2023
866b855
Added confidenceMethod
iherman Aug 3, 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
4 changes: 4 additions & 0 deletions contexts/credentials/v2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,10 @@
"termsOfUse": {
"@id": "https://www.w3.org/2018/credentials#termsOfUse",
"@type": "@id"
},
"confidenceMethod": {
"@id": "https://www.w3.org/2018/credentials#confidenceMethod",
"@type": "@id"
}
}
},
Expand Down
101 changes: 99 additions & 2 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2230,7 +2230,7 @@ <h3>Data Schemas</h3>
</p>
<p>
If multiple schemas are present, validity is determined according to the
processing rules outlined by each associated <code>credentialSchema</code>
processing rules outlined by each associated <code>credentialSchema</code>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
processing rules outlined by each associated <code>credentialSchema</code>
processing rules outlined by each associated <code>credentialSchema</code>

<code>type</code> property.
</p>
</dd>
Expand Down Expand Up @@ -3555,6 +3555,26 @@ <h3>Reserved Extension Points</h3>
</thead>

<tbody>
<tr>
<td>`confidenceMethod`</td>
<td>
A property used for specifying one or more methods that a verifier
might use to increase their confidence that the value of an attribute in or of
a verifiable credential or verifiable presentation is accurate, including but not
limited to attributes such as `initialRecipient` (a/k/a `issuee`), `presenter`,
`authorizedPresenter`, `holder`, etc.
The associated vocabulary URL MUST be
`https://www.w3.org/2018/credentials#confidenceMethod`.
<p class="issue" title="(AT RISK) Reservation depends on implementations">
This property reservation might be deleted in favor of an existing section
in the specification if at least one specification with two independent
implementations are demonstrated by the end of the Candidate Recommendation
Phase. If that does not occur, this reservation will remain, but the existing
section in the specification will be removed.
See <a href="https://w3c-ccg.github.io/confidence-method-spec/">Verifiable Credential Confidence Methods</a>.
</p>
</td>
</tr>
<tr>
<td>`evidence`</td>
<td>
Expand Down Expand Up @@ -3588,13 +3608,14 @@ <h3>Reserved Extension Points</h3>
<tr>
<td>`renderMethod`</td>
<td>
A property used for specifying how to render a credential into a visual,
A property used for specifying one or more methods to render a credential into a visual,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A property used for specifying one or more methods to render a credential into a visual,
A property used for specifying how to render a credential into a visual,

auditory, or haptic format. The associated vocabulary URL MUST be
`https://www.w3.org/2018/credentials#renderMethod`.
<p class="issue" title="(AT RISK) Reservation depends on implementations">
This reserved property is at risk and will be removed from the
specification if at least one specification with two independent implementations
are not demonstrated by the end of the Candidate Recommendation Phase.
See <a href="https://w3c-ccg.github.io/vc-render-method/">Verifiable Credential Rendering Methods</a>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
See <a href="https://w3c-ccg.github.io/vc-render-method/">Verifiable Credential Rendering Methods</a>.

</p>
</td>
</tr>
Expand Down Expand Up @@ -3625,6 +3646,82 @@ <h3>Reserved Extension Points</h3>
</p>

</section>

<section class="normative">
<h3>Ecosystem Compatibility</h3>

<p>
There are a number of digital credential formats that do not natively use the
data model provided in this document, but are aligned with a number of concepts
in this specification. At the time of publication, examples of these digital
credential formats include
<a href="https://www.rfc-editor.org/rfc/rfc7519.html">
JSON Web Tokens</a> (JWTs),
<a href="https://www.rfc-editor.org/rfc/rfc8392.html">
CBOR Web Tokens</a> (CWTs),
<a href="https://www.iso.org/standard/69084.html">ISO-18013-5:2021</a>
(mDLs),
<a href="https://hyperledger.github.io/anoncreds-spec/">
AnonCreds</a>,
<a href="https://www.ietf.org/archive/id/draft-mcnally-envelope-02.html">
Gordian Envelopes</a>, and
<a href="https://www.ietf.org/archive/id/draft-ssmith-acdc-02.html">
Authentic Chained Data Containers</a> (ACDCs).
</p>

<p>
If conceptually aligned digital credential formats can be transformed into a
<a>conforming document</a> according to the rules provided in this section, they
are considered <em>"compatible with the W3C Verifiable Credentials ecosystem"</em>.
A <a>conforming document</a> is either a <a>verifiable credential</a> serialized
as the `application/vc+ld+json` media type or a <a>verifiable presentation</a>
serialized as the `application/vp+ld+json` media type. Specifications that
describe how to perform transformations that enable compatibility with
the Verifiable Credentials ecosystem:
</p>

<ul>
<li>
MUST identify whether the transformation to this data model is one-way-only or
round-trippable.
</li>
<li>
MUST preserve the `@context` values when performing round-trippable
transformation.
</li>
<li>
MUST result in a <a>conforming document</a> when transforming to the data
model described by this specification.
</li>
<li>
MUST specify a registered media type for the input document.
</li>
<li>
SHOULD provide a test suite that demonstrates that the specified transformation
algorithm to the data model in this specification results in
a <a>conforming document</a>.
</li>
<li>
SHOULD ensure that all semantics utilized in the transformed
<a>conforming document</a> follow best practices for Linked Data. See
Section <a href="#getting-started"></a>, Section
<a href="#extensibility"></a>, and Linked Data Best Practices [[?LD-BP]]
for additional guidance.
</li>
</ul>

<p class="note" title="What constitutes a verifiable credential?">
Readers are advised that a digital credential is only considered
compatible with the W3C Verifiable Credentials ecosystem if it is a
<a>conforming document</a> and it utilizes at least one securing mechanism, as
described by their respective requirements in this specification. While some communities might call some digital
credential formats that are not <a>conforming documents</a>
"verifiable credentials", doing so does NOT make that digital credential
compliant to this specification.
</p>

</section>

Comment on lines +3649 to +3724
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<section class="normative">
<h3>Ecosystem Compatibility</h3>
<p>
There are a number of digital credential formats that do not natively use the
data model provided in this document, but are aligned with a number of concepts
in this specification. At the time of publication, examples of these digital
credential formats include
<a href="https://www.rfc-editor.org/rfc/rfc7519.html">
JSON Web Tokens</a> (JWTs),
<a href="https://www.rfc-editor.org/rfc/rfc8392.html">
CBOR Web Tokens</a> (CWTs),
<a href="https://www.iso.org/standard/69084.html">ISO-18013-5:2021</a>
(mDLs),
<a href="https://hyperledger.github.io/anoncreds-spec/">
AnonCreds</a>,
<a href="https://www.ietf.org/archive/id/draft-mcnally-envelope-02.html">
Gordian Envelopes</a>, and
<a href="https://www.ietf.org/archive/id/draft-ssmith-acdc-02.html">
Authentic Chained Data Containers</a> (ACDCs).
</p>
<p>
If conceptually aligned digital credential formats can be transformed into a
<a>conforming document</a> according to the rules provided in this section, they
are considered <em>"compatible with the W3C Verifiable Credentials ecosystem"</em>.
A <a>conforming document</a> is either a <a>verifiable credential</a> serialized
as the `application/vc+ld+json` media type or a <a>verifiable presentation</a>
serialized as the `application/vp+ld+json` media type. Specifications that
describe how to perform transformations that enable compatibility with
the Verifiable Credentials ecosystem:
</p>
<ul>
<li>
MUST identify whether the transformation to this data model is one-way-only or
round-trippable.
</li>
<li>
MUST preserve the `@context` values when performing round-trippable
transformation.
</li>
<li>
MUST result in a <a>conforming document</a> when transforming to the data
model described by this specification.
</li>
<li>
MUST specify a registered media type for the input document.
</li>
<li>
SHOULD provide a test suite that demonstrates that the specified transformation
algorithm to the data model in this specification results in
a <a>conforming document</a>.
</li>
<li>
SHOULD ensure that all semantics utilized in the transformed
<a>conforming document</a> follow best practices for Linked Data. See
Section <a href="#getting-started"></a>, Section
<a href="#extensibility"></a>, and Linked Data Best Practices [[?LD-BP]]
for additional guidance.
</li>
</ul>
<p class="note" title="What constitutes a verifiable credential?">
Readers are advised that a digital credential is only considered
compatible with the W3C Verifiable Credentials ecosystem if it is a
<a>conforming document</a> and it utilizes at least one securing mechanism, as
described by their respective requirements in this specification. While some communities might call some digital
credential formats that are not <a>conforming documents</a>
"verifiable credentials", doing so does NOT make that digital credential
compliant to this specification.
</p>
</section>

</section>

<section>
Expand Down
12 changes: 12 additions & 0 deletions vocab/credentials/v2/vocabulary.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ class:
label: Credential status
comment: A Credential Status provides enough information to determine the current status of the credential (for example, suspended or revoked). This class serves as a supertype for specific status types.

- id: ConfidenceMethod
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This appears to be reserving a "class" not a "predicate"... I guess we really need to add Credential or we will have a weird mismatch between how to handle classes in the spec.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not understand what you are saying, @OR13. The vocabulary includes a number of "Classes" that serve as some sort of an "abstract" superclass. I fail to see how this has any relation to the presence or not of a separate class for credentials.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iherman previously you had raised a PR to define Credential, which failed to gain consensus in relation to VerifiableCredential... and yet, all the other parts of the vocab seem to leverage abstract classes.

As a consumer of this ontology, I am wondering what leads the working group to decide when to use an abstract class and when not too.

If we see abstract classes for ConfidenceMethod as valuable, why did we not see an abstract class for Credential as valuable?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer not to discuss this issue here. It is a valid question, but it would turn this PR into an endless discussion thread, going way beyond a simple addition to the vocabulary. Let us avoid that; this is what may lead to problems like #1226 (comment)

label: Confidence method
defined_by: https://w3c-ccg.github.io/confidence-method-spec/
comment: A Confidence Method provides enough information for a verifier to determine whether the holder can generate a verifiable presentation to increase the verifier's confidence that they are the same entity referenced by the confidence method. This class serves as a supertype for specific status types.
status: reserved

- id: JsonSchema2023
label: JSON schema validator 2023
defined_by: https://www.w3.org/TR/vc-json-schema/#jsonschema2023
Expand Down Expand Up @@ -79,6 +85,12 @@ property:
range: IRI
comment: An entity about which claims are made.

- id: confidenceMethod
label: Confidence method
defined_by: https://w3c-ccg.github.io/confidence-method-spec/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We reserved this in a table... do we expect that term definition to show up here?

https://www.w3.org/2018/credentials#confidenceMethod

https://w3c.github.io/vc-data-model/#reserved-extension-points

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current vocabulary includes entries for the other reserved terms already, and the definition in the spec explicitly refers to a URL in the credentials vocabulary. Ie., consistency requires to put this entry into the table, too.

Copy link
Contributor

@OR13 OR13 Aug 4, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you are saying, we don't expect to see these URLs in the vocabulary.

And defined by URL can change in the future if the working group decides to define reserved terms?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am saying there is no definition as of today. We are not yet at Rec and the reserved terms are somehow at risk. If they become "regular" than a proper URL must come to the fore.

status: reserved
range: cred:ConfidenceMethod

- id: evidence
label: Evidence
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#defn-evidence
Expand Down