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

Add test suite to readme; term definition for jsonschema #211

Merged
merged 5 commits into from
Sep 7, 2023
Merged

Add test suite to readme; term definition for jsonschema #211

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4d7f715
update readme, update term dfn
Sep 5, 2023
1c4bd15
Update index.html
decentralgabe Sep 6, 2023
f517cb5
add note
Sep 6, 2023
d1e1f8c
Update index.html
decentralgabe Sep 6, 2023
c1d214b
term links
Sep 6, 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 README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ https://w3c.github.io/vc-json-schema/
We encourage contributions meeting the [Contribution Guidelines](CONTRIBUTING.md). While we prefer the creation of issues
and Pull Requests in the GitHub repository, discussions may also occur on the [public-credentials](http://lists.w3.org/Archives/Public/public-credentials/) mailing list.

### Test Suite

A [docker](https://www.docker.com/)-based test suite for the specification can [be found here](https://github.com/w3c/vc-json-schema-test-suite). All impelementers are encouraged to add to the test suite.
Copy link
Member

Choose a reason for hiding this comment

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

The things that jump out after a PR is merged...

Suggested change
A [docker](https://www.docker.com/)-based test suite for the specification can [be found here](https://github.com/w3c/vc-json-schema-test-suite). All impelementers are encouraged to add to the test suite.
A [docker](https://www.docker.com/)-based test suite for the specification can [be found here](https://github.com/w3c/vc-json-schema-test-suite). All implementers are encouraged to add to the test suite.


### Building

To build, we use [respec](https://respec.org/).
Expand All @@ -21,3 +25,6 @@ Next open up `out.html` in a web browser and review the document.

### Other useful links
* [Public group email archive](https://lists.w3.org/Archives/Public/public-credentials/)
* [VC Data Model](https://www.w3.org/TR/vc-data-model/)
* [JSON Schema](https://json-schema.org/)
* [Test Suite](https://github.com/w3c/vc-json-schema-test-suite)
74 changes: 62 additions & 12 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
github: "https://github.com/w3c/vc-json-schema/",
includePermalinks: false,
edDraftURI: "https://w3c.github.io/vc-json-schema/",
testSuiteURI: "https://w3c.github.io/vc-json-schema-test-suite/",
editors: [{
name: "Gabe Cohen",
url: "https://github.com/decentralgabe",
Expand Down Expand Up @@ -200,6 +201,11 @@ <h3>JsonSchema</h3>
</tbody>
</table>
</p>
<p class="note" title="Restriction on the usage of the jsonSchema property">
Usage of the <code><a href="#jsonschema-0">jsonSchema</a></code> property is restricted to
situations where the <code>JsonSchema</code> class instance is the object of the <code>credentialSubject</code>
property within a <code><a href="#jsonschemacredential">JsonSchemaCredential</a></code> instance.
</p>
<p>
An example of utilizing the VC Data Model's <code>credentialSchema</code>
is provided below:
Expand Down Expand Up @@ -273,7 +279,7 @@ <h3>JsonSchemaCredential</h3>
The <code>credentialSubject</code> property MUST contain two properties:
<ul>
<li><code>type</code> – the value of which MUST be <code>JsonSchema</code></li>
<li><code>jsonSchema</code> – an object which contains a valid JSON Schema</li>
<li><a href="jsonschema-0"><code>jsonSchema</code></a> – an object which contains a valid JSON Schema</li>
</ul>
</li>
<li>
Expand All @@ -291,12 +297,6 @@ <h3>JsonSchemaCredential</h3>
</p>
</li>
</ul>

<p>
The <a href="https://www.w3.org/TR/json-ld/#dfn-term-definition">term definition</a>
for using the <code>jsonSchema</code> property within the <code>credentialSubject</code>
of a verifiable credential is <code>https://www.w3.org/ns/credentials#jsonSchema</code>.
</p>
<p>
Any version of [[JSON-SCHEMA]] in the section on
<a href="#json-schema-specifications">JSON Schema Specifications</a>
Expand Down Expand Up @@ -410,10 +410,60 @@ <h3>JsonSchemaCredential</h3>
}
</pre>
</p>
<p class="issue" data-number="159">
Add language about JsonSchemaCredential credentials having a credentialSchema property
and the risks of nesting.
</p>
<section class="normative">
<h4>jsonSchema</h4>
<p>
This term is part of the
<a href="https://www.w3.org/2018/credentials/#jsonSchema">Verifiable Credentials Vocabulary v2.0</a>.
</p>
<p><b>jsonSchema</b> enables the use of the <code>jsonSchema</code> property
within the <code>credentialSubject</code> of a verifiable credential. The term is
intended to be used with the <a href="#jsonschemacredential"></a> type. The value of
decentralgabe marked this conversation as resolved.
Show resolved Hide resolved
the <code>jsonSchema</code> property MUST be a valid [[JSON-SCHEMA]].
Copy link
Member

Choose a reason for hiding this comment

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

There are two related statements:

  • §2.1 JsonSchema says that, w.r.t. the JsonSchema class, "When dereferencing the id property associated with the JsonSchema type value the result is a valid JSON Schema document according to its specification version.".
  • the statement above that I have just highlighted

There are two alternative interpretations of these two statements when put together.

  1. The jsonSchema property could be seen as an alternative to the dereferencing process for a JsonSchema class instance to get to a real Json Schema. In other words, the usage of the jsonSchema property is not related to the notion of JsonSchemaCredential, and it would be perfectly fine to use a jsonSchema property in the example 1, by simply "folding in" Example 2 into the credentialSchema construct.

  2. The usage of jsonSchema is restricted to the situation where the JsonSchema class instance is the object of the credentialSubject property within a JsonSchemaCredential instance.

I suspect that the intention of the spec is alternative (2). If so, this statement should be very explicitly added to the definition of the property in §2.1 (I know that it is between the lines in §2.2, but not really explicitly). Unfortunately, expressing that in the RDFS ontology is not really possible (or would require some complex OWL ontology construct that I do not think we should use), which means one more reason for this restrictions to appear very explicitly.

Note that, personally, I would not have any problems with alternative (1), which is simpler. But it is not my decision.

Copy link
Member

Choose a reason for hiding this comment

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

Unfortunately, expressing that in the RDFS ontology is not really possible (or would require some complex OWL ontology construct that I do not think we should use), which means one more reason for this restrictions to appear very explicitly.

Actually, there would be one way of introducing this restriction into the vocabulary: define a subclass of JsonSchema class, something like EmbeddedJsonSchema, define jsonSchema's domain as being EmbeddedJsonSchema, and requiring that the object of a credentialSchema property, when used in conjunction with JsonSchemaCredential, would be of type EmbeddedJsonSchema. A bit more complex, but it works. Not sure it is worth it, though...

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I intended for (2) and will firm up the language.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@iherman please review the latest change, I've added a note with the text you've suggested in section 2.1

</p>
<p>
<pre class="example jsonschemacredential-jsonschema nohighlight" title="Example JsonSchema Credential with jsonSchema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3734",
"type": ["VerifiableCredential", "JsonSchemaCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSchema": {
"id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
"type": "JsonSchema",
},
"credentialSubject": {
"id": "https://example.com/schemas/favorite-color-schema.json",
"type": "JsonSchema",
<span class="highlight"> "jsonSchema": {
"$id": "https://example.com/schemas/favorite-color-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "Favorite Color Schema",
"description": "Favorite Color using JsonSchemaCredential",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"favoriteColor": {
"type": "string"
"enum": ["red", "orange", "green", "blue", "yellow", "purple"]
}
},
"required": ["favoriteColor"]
}
}
}
</span>
}
}
</pre>
</p>
</section>
</section>
</section>
<section class="normative">
Expand Down Expand Up @@ -461,7 +511,7 @@ <h2>JSON Schema Specifications</h2>
<p class="note" title="A stable JSON Schema specification is coming">
<a href="https://json-schema.org/blog/posts/future-of-json-schema">A stable JSON Schema specification</a>
is in the works. When it's released, we intend to update this table to require the stable version.
</p>
</p>

<section class="normative">
<h3>Reserved Keywords</h3>
Expand Down