Skip to content

Commit

Permalink
Move Data Schemas further up in Basic Concepts section.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed Aug 5, 2024
1 parent 28bfa31 commit 4b79e83
Showing 1 changed file with 152 additions and 152 deletions.
304 changes: 152 additions & 152 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2180,6 +2180,158 @@ <h3>Status</h3>

</section>

<section>
<h3>Data Schemas</h3>

<p>
Data schemas are useful when enforcing a specific structure on a given
collection of data. There are at least two types of data schemas that this
specification considers:
</p>

<ul>
<li>
Data verification schemas, which are used to establish that the structure
and contents of a [=credential=] or [=verifiable credential=] conform to a
published schema.
</li>
<li>
Data encoding schemas, which are used to map the contents of a
[=verifiable credential=] to an alternative representation format, such as a
format used in a zero-knowledge proof.
</li>
</ul>

<p>
It is important to understand that data schemas serve a different purpose from
the `@context` property, which neither enforces data structure or
data syntax, nor enables the definition of arbitrary encodings to alternate
representation formats.
</p>
<p>
This specification defines the following [=property=] for the expression of a
data schema, which can be included by an [=issuer=] in
the [=verifiable credentials=] that it issues:
</p>

<dl>
<dt><var id="defn-credentialSchema">credentialSchema</var></dt>
<dd>
<p>
The value of the `credentialSchema` [=property=] MUST be one or
more data schemas that provide [=verifiers=] with enough information to
determine whether the provided data conforms to the provided schema(s). Each
`credentialSchema` MUST specify its `type` (for example,
`JsonSchema`), and an `id` [=property=]
that MUST be a [=URL=] identifying the schema file. The precise contents of
each data schema is determined by the specific type definition.
</p>
<p>
If multiple schemas are present, validity is determined according to the
processing rules outlined by each associated `credentialSchema`
`type` property.
</p>
</dd>
</dl>

<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
vocabulary using `credentialSchema` that is locked to some content
integrity protection mechanism. The `credentialSchema`
[=property=] also makes it possible to perform syntactic checking on the
[=credential=] and to use [=verification=] mechanisms such as JSON Schema
[[?VC-JSON-SCHEMA]] validation.
</p>

<pre class="example nohighlight"
title="Usage of the credentialSchema property to perform JSON schema validation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential", "ExamplePersonCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
},
"alumniOf": {
"name": "Example University"
}
},
<span class="highlight">"credentialSchema": [{
"id": "https://example.org/examples/degree.json",
"type": "JsonSchema"
},
{
"id": "https://example.org/examples/alumni.json",
"type": "JsonSchema"
}]</span>
}
</pre>

<p>
In the example above, the [=issuer=] is specifying a
`credentialSchema`, which points to a [[?VC-JSON-SCHEMA]] file that
can be used by a [=verifier=] to determine whether the
[=verifiable credential=] is well-formed.
</p>

<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 [[[VC-IMP-GUIDE]]] document.
</p>

<p>
Data schemas can also be used to specify mappings to other formats, such as
those used to perform zero-knowledge proofs. For more information on using the
`credentialSchema` [=property=] with zero-knowledge proofs,
see Section [[[#zero-knowledge-proofs]]].
</p>

<pre class="example nohighlight" title="Usage of the credentialSchema property to perform zero-knowledge validation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
<span class="highlight">"credentialSchema": {
"id": "https://example.org/examples/degree",
"type": "ZkpExampleSchema2018"
}</span>
}
</pre>

<p>
In the example above, the [=issuer=] is specifying a
`credentialSchema` pointing to a means of transforming the input data
into a format which can then be used by a [=verifier=] to determine whether
the proof provided with the [=verifiable credential=] is well-formed.
</p>


</section>

<section>
<h3>Securing Mechanisms</h3>

Expand Down Expand Up @@ -2596,158 +2748,6 @@ <h4>Presentations Including Holder Claims</h4>
</section>
</section>

<section>
<h3>Data Schemas</h3>

<p>
Data schemas are useful when enforcing a specific structure on a given
collection of data. There are at least two types of data schemas that this
specification considers:
</p>

<ul>
<li>
Data verification schemas, which are used to establish that the structure
and contents of a [=credential=] or [=verifiable credential=] conform to a
published schema.
</li>
<li>
Data encoding schemas, which are used to map the contents of a
[=verifiable credential=] to an alternative representation format, such as a
format used in a zero-knowledge proof.
</li>
</ul>

<p>
It is important to understand that data schemas serve a different purpose from
the `@context` property, which neither enforces data structure or
data syntax, nor enables the definition of arbitrary encodings to alternate
representation formats.
</p>
<p>
This specification defines the following [=property=] for the expression of a
data schema, which can be included by an [=issuer=] in
the [=verifiable credentials=] that it issues:
</p>

<dl>
<dt><var id="defn-credentialSchema">credentialSchema</var></dt>
<dd>
<p>
The value of the `credentialSchema` [=property=] MUST be one or
more data schemas that provide [=verifiers=] with enough information to
determine whether the provided data conforms to the provided schema(s). Each
`credentialSchema` MUST specify its `type` (for example,
`JsonSchema`), and an `id` [=property=]
that MUST be a [=URL=] identifying the schema file. The precise contents of
each data schema is determined by the specific type definition.
</p>
<p>
If multiple schemas are present, validity is determined according to the
processing rules outlined by each associated `credentialSchema`
`type` property.
</p>
</dd>
</dl>

<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
vocabulary using `credentialSchema` that is locked to some content
integrity protection mechanism. The `credentialSchema`
[=property=] also makes it possible to perform syntactic checking on the
[=credential=] and to use [=verification=] mechanisms such as JSON Schema
[[?VC-JSON-SCHEMA]] validation.
</p>

<pre class="example nohighlight"
title="Usage of the credentialSchema property to perform JSON schema validation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential", "ExamplePersonCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
},
"alumniOf": {
"name": "Example University"
}
},
<span class="highlight">"credentialSchema": [{
"id": "https://example.org/examples/degree.json",
"type": "JsonSchema"
},
{
"id": "https://example.org/examples/alumni.json",
"type": "JsonSchema"
}]</span>
}
</pre>

<p>
In the example above, the [=issuer=] is specifying a
`credentialSchema`, which points to a [[?VC-JSON-SCHEMA]] file that
can be used by a [=verifier=] to determine whether the
[=verifiable credential=] is well-formed.
</p>

<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 [[[VC-IMP-GUIDE]]] document.
</p>

<p>
Data schemas can also be used to specify mappings to other formats, such as
those used to perform zero-knowledge proofs. For more information on using the
`credentialSchema` [=property=] with zero-knowledge proofs,
see Section [[[#zero-knowledge-proofs]]].
</p>

<pre class="example nohighlight" title="Usage of the credentialSchema property to perform zero-knowledge validation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
<span class="highlight">"credentialSchema": {
"id": "https://example.org/examples/degree",
"type": "ZkpExampleSchema2018"
}</span>
}
</pre>

<p>
In the example above, the [=issuer=] is specifying a
`credentialSchema` pointing to a means of transforming the input data
into a format which can then be used by a [=verifier=] to determine whether
the proof provided with the [=verifiable credential=] is well-formed.
</p>


</section>

</section>

<section>
Expand Down

0 comments on commit 4b79e83

Please sign in to comment.