Skip to content

Add table of reserved properties #1082

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

Merged
merged 9 commits into from
Apr 24, 2023
Merged

Add table of reserved properties #1082

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
c59e683
Add section on reserved properties.
msporny Apr 7, 2023
dde4bff
Add table of reserved properties.
msporny Apr 7, 2023
34a9577
Add reference to vc-specs-dir.
msporny Apr 7, 2023
b8d5236
Clarify that properties serve as extension points.
msporny Apr 8, 2023
ddd1a30
Add refreshService to list of reserved properties.
msporny Apr 11, 2023
c8d2946
Apply fixes from @brentzundel and @TallTed in table of reserved prope…
msporny Apr 20, 2023
861577b
Minor editorial fixes for reserved properties table.
msporny Apr 20, 2023
a89757d
Add requirement to use `type` property in extension points.
msporny Apr 20, 2023
2d75b77
Update issue marker with expected reserved properties.
msporny Apr 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
7 changes: 7 additions & 0 deletions common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,13 @@ var vcwg = {
authors: ['Orie Steele', 'Michael Jones'],
status: 'ED',
publisher: 'W3C Verifiable Credentials Working Group'
},
'VC-SPECS': {
title: 'Verifiable Credentials Specifications Directory',
href: 'https://w3c.github.io/vc-specs-dir/',
authors: ['Manu Sporny'],
status: 'ED',
publisher: 'W3C Verifiable Credentials Working Group'
}
}
};
Expand Down
64 changes: 64 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3250,6 +3250,70 @@ <h3>Authorization</h3>
on top of this specification.
</p>
</section>

<section class="normative">
<h3>Reserved Extension Points</h3>

<p>
This specification reserves a number of <a>properties</a> to serve as possible
extension points. While some implementers signaled interest in these properties,
their inclusion in this specification was considered to be premature; these
extension points might be more formally defined in future versions of this
specification. It is important to note that these properties are not defined by
this specification and implementers are cautioned that usage of these properties
is considered experimental.
</p>
<p>
Implementers MAY use these properties, but SHOULD expect them and/or
their meanings to change during the process to normatively specify them.
Implementers SHOULD NOT use these properties without a publicly disclosed
Copy link
Contributor

Choose a reason for hiding this comment

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

Might want to move this to the directory, as a registration requirement.

specification describing their implementation.
</p>

<p>
In order to avoid collisions regarding how the following properties are used,
implementations MUST specify a `type` property in the value associated with the
reserved property. For more information related to adding `type` information,
see Section <a href="#types"></a>.
</p>

<p class="issue" title="Reserved properties under debate">
The following extension point properties are under consideration for being
marked as reserved: `presentationSchema`, `credentialRefresh`, `termsOfUse`,
`evidence`, `renderMethod`, `refreshService`, and
`confirmationMethod/confidenceMethod`.
</p>
Comment on lines +3280 to +3285
Copy link
Contributor

Choose a reason for hiding this comment

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

I'd remove the concrete reserved properties for now and only merge the PR with an empty list. A first stab on the list can then follow. Otherwise looks good to me.

Copy link
Member

Choose a reason for hiding this comment

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

In the previous conversations we've held there has been wide agreement that this PR should not contain any entries in the table, so it doesn't.
PR #1097 has been raised to introduce them.


<table class="simple">
<thead>
<tr>
<th>Reserved&nbsp;Property</th>
<th>Description</th>
</tr>
</thead>

<tbody>
<tr>
<td>
`example`
</td>
<td>
An example entry for a reserved property.
</td>
</tr>

</tbody>
</table>

<p>
An unofficial list of specifications that are associated with the extension
points defined in this specification, as well as the reserved extension points
defined in this section, can be found in the Verifiable Credentials
Specifications Directory [[?VC-SPECS]]. Items in the directory that refer to
reserved extension points SHOULD be treated as experimental.
</p>

</section>
</section>

<section>
Expand Down