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

Remove document conformance checking algorithm section #1381

Merged
merged 6 commits into from
Dec 17, 2023
Merged

Remove document conformance checking algorithm section #1381

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1added2
Clarify definition of "conforming document".
msporny Dec 10, 2023
8f2c158
Refer to Ecosystem Compatability from conforming doc definition.
msporny Dec 10, 2023
3112e46
Remove data model conformance checking algorithm.
msporny Dec 10, 2023
80bf0fa
Switch from "compact" to "compacted" language for JSON-LD docs.
msporny Dec 17, 2023
7edc347
Move media type conformance to document conformance definition.
msporny Dec 17, 2023
a515e6f
Remove "obviously true" statement about other serialization formats.
msporny Dec 17, 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
159 changes: 15 additions & 144 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -585,15 +585,15 @@ <h3>Use Cases and Requirements</h3>

<section id="conformance" class="normative">
<p>
A <dfn>conforming document</dfn> is any concrete expression of the data model
that complies with the normative statements in this specification.
Specifically, all relevant normative statements in Sections
A <dfn>conforming document</dfn> is a compact JSON-LD document that
Copy link
Member

Choose a reason for hiding this comment

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

Is there an algorithm somewhere that verifiers can use to check that something is a compact JSON-LD document? I see https://w3c.github.io/json-ld-api/#compaction-algorithms defines how to compact a JSON-LD document: is the "is a compact JSON-LD document" predicate something like "https://w3c.github.io/json-ld-api/#compaction-algorithms returns a document that's identical to the original"?

Copy link
Member

Choose a reason for hiding this comment

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

@jyasskin

The best reference is the Compacted Document Form section of the JSON-LD spec (even if that section is marked as non-normative, the reason being that what is really normative is the algorithm itself, reference from that section).

But this is only a partial answer to your question because that is not a reference to a checking algorithm, rather a reference to the concept itself. I do not think there is a better explicit algorithmic definition than yours.

This raises to editorial issues, though:

  • there is a slight terminology mismatch, and we may want to use the term 'Compacted' rather than 'Compact'.
  • it may be useful to add an explicit entry to our terminology section, quoting your definition for checking

(From a point of view of issue handling it may be better to raise this mismatch as a separate issue + PR, though.)

CC @msporny

Copy link
Member Author

Choose a reason for hiding this comment

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

@jyasskin wrote:

is the "is a compact JSON-LD document" predicate something like "https://w3c.github.io/json-ld-api/#compaction-algorithms returns a document that's identical to the original"?

Yes, exactly.

@iherman wrote:

there is a slight terminology mismatch, and we may want to use the term 'Compacted' rather than 'Compact'.

Fixed in 80bf0fa

complies with all of the relevant "MUST" statements in this specification.
Specifically, the relevant normative "MUST" statements in Sections
<a href="#basic-concepts"></a>, <a href="#advanced-concepts"></a>, and
<a href="#syntaxes"></a> of this document MUST be enforced. A serialization
format for the conforming document MUST be deterministic, bi-directional,
and lossless as described in Section <a href="#syntaxes"></a>.
The <a>conforming document</a> MAY be transmitted or stored in any such
serialization format.
<a href="#syntaxes"></a> of this document MUST be enforced. Other serialization
formats for the conforming document MAY be used, and if they are, further
guidance in Section <a href="#ecosystem-compatibility"></a> MUST be
Copy link
Member

Choose a reason for hiding this comment

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

I noticed that https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/pull/1381.html#ecosystem-compatibility includes "A conforming document is either a verifiable credential serialized as the application/vc+ld+json media type or a verifiable presentation serialized as the application/vp+ld+json media type." That piece of the definition should move here.

Copy link
Member Author

Choose a reason for hiding this comment

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

Good catch, fixed in: 7edc347

followed. The <a>conforming document</a> MAY be transmitted
or stored in any such serialization format.
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure what this means for the result type of the verification algorithm. Does that need to be a compact JSON-LD document, or can it be one of the other serialization formats?

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 WG didn't like that language, as of the last meeting. It's been removed in a515e6f.

Copy link
Member

Choose a reason for hiding this comment

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

"Other serialization formats for the conforming document MAY be used" except that it's just said that "A conforming document is a compact JSON-LD document" which implies rather strongly that "A conforming document is" not in any "Other serialization formats".

How a reader is to determine which statements (normative or otherwise) are relevant would be a challenge we're now laying out to them, rather than solving it ourselves, by making the relevance of such statements unquestionably obvious.

NOTE: The suggested revision cannot be applied automatically, because it includes both of the line ranges shown above as inserts 588-591 and 592-596 (and below as deletions 588-591 and 597-601), as well as the line range shown both above and below as deletions 592-596.

Suggested change
A <dfn>conforming document</dfn> is a compact JSON-LD document that
complies with all of the relevant "MUST" statements in this specification.
Specifically, the relevant normative "MUST" statements in Sections
<a href="#basic-concepts"></a>, <a href="#advanced-concepts"></a>, and
<a href="#syntaxes"></a> of this document MUST be enforced. A serialization
format for the conforming document MUST be deterministic, bi-directional,
and lossless as described in Section <a href="#syntaxes"></a>.
The <a>conforming document</a> MAY be transmitted or stored in any such
serialization format.
<a href="#syntaxes"></a> of this document MUST be enforced. Other serialization
formats for the conforming document MAY be used, and if they are, further
guidance in Section <a href="#ecosystem-compatibility"></a> MUST be
followed. The <a>conforming document</a> MAY be transmitted
or stored in any such serialization format.
A <dfn>conforming document</dfn> is, or can be deterministically transformed
into, a compact JSON-LD document that complies with all of the relevant
normative "MUST" statements in this specification. More specifically, the
document MUST comply with all relevant normative "MUST" statements in Sections
<a href="#basic-concepts"></a>, <a href="#advanced-concepts"></a>, and
<a href="#syntaxes"></a> of this document. If the document is serialized as
anything other than compact JSON-LD, further guidance in Section
<a href="#ecosystem-compatibility"></a> MUST be followed.

Copy link
Contributor

Choose a reason for hiding this comment

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

@TallTed, I don't think we want to change the definition of the conforming document -- but we may want to say that the conforming document can be stored / transported / enveloped using other formats provided that the conforming document can be deterministically reproduced. I think that's the aim here.

Copy link
Member

@TallTed TallTed Dec 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

@msporny @dlongley

The definition is here being changed from the previous text to the new, and in ways which seem (potentially) problematic to me. To start with, from --

any concrete expression of the data model
that complies with the normative statements in this specification.

-- to --

a compact JSON-LD document that
complies with all of the relevant "MUST" statements in this specification.

The first is VERY broad and open. The second is VERY narrow and closed.

As I said in my intro to the change suggested above, the new text starts by saying that only Compact (where I capitalize the C because it may easily be overlooked otherwise, suggesting that any form of JSON-LD is sufficient) JSON-LD might (if it complies with all the MUSTs) be a conforming document.

Only later does the new text suggest that other formats might be usable, but only (it appears to me) for storage or transmission (so evaluation, verification, etc., first requires transformation to Compact JSON-LD), making me question what value there could be in such storage or transmission and further wonder why not simply require that it always be kept in Compact JSON-LD?

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 problematic text has been removed in commit (based on consensus reached in the last WG meeting): a515e6f

</p>

<p>
Expand Down Expand Up @@ -4503,25 +4503,12 @@ <h3>Verification</h3>
</li>
<li>
Ensure that the <var>result</var>.<var>document</var> is a
<a>conforming document</a> by performing the following steps:
<ol class="algorithm">
<li>
Set <var>dataModelConformanceChecked</var> to the result of executing the
<a href="#data-model-conformance-checking">data model conformance checking
algorithm</a> with <var>document</var> passed as input to the algorithm.
</li>
<li>
Set <var>status</var>, <var>document</var>, <var>warnings</var>, and
<var>errors</var> in <var>result</var> to their respective properties in
<var>dataModelConformanceChecked</var>.
</li>
<li>
If <var>result</var>.<var>status</var> is `false`, the provided
<var>inputBytes</var> contains a non-conforming document. Return
<var>result</var>, which will contain warning and error information
related to the verification failure.
</li>
</ol>
<a>conforming document</a>. If it is not, set
<var>result</var>.<var>status</var> to `false`, remove the
<var>document</var> property from <var>result</var>, and add at least
one <a href="#MALFORMED_VALUE_ERROR">MALFORMED_VALUE_ERROR</a> to
<var>result</var>.<var>errors</var>. Other warnings and errors MAY be included
to aid any debugging process.
</li>
<li>
Return <var>result</var>.
Expand All @@ -4538,122 +4525,6 @@ <h3>Verification</h3>

</section>

<section class="normative">
<h3>Data Model Conformance Checking</h3>

<p>
The algorithm in this section can be used to determine if a provided document is
conformant with the data model provided in this specification. This algorithm
takes a document (object <var>inputDocument</var>) and produces an object
(<var>dataModelConformanceChecked</var>) that contains the following:
</p>

<ul>
<li>
a verification status (boolean <var>status</var>)
</li>
<li>
a verified document (object <var>document</var>)
</li>
<li>
zero or more warnings (array of <a>ProblemDetails</a> <var>warnings</var>)
</li>
<li>
zero or more errors (array of <a>ProblemDetails</a> <var>errors</var>)
</li>
</ul>

<p>
The data model verification algorithm is as follows:
</p>

<ol class="algorithm">
<li>
Set <var>dataModelConformanceChecked</var> to an empty object. Initialize the following
fields in <var>dataModelConformanceChecked</var>: <var>status</var> to `false`,
<var>warnings</var> to an empty array, and <var>errors</var> to an empty array.
</li>
<li>
Ensure that the `@context` property of <var>document</var> conforms to the
statements in <a href="#contexts"></a>. If not, return
<var>dataModelConformanceChecked</var>, which will contain a false verification status.
</li>
<li>
Starting at the top level, recursively process each object <var>obj</var> in
<var>document</var>, setting <a href="#MALFORMED_VALUE_ERROR">
MALFORMED_VALUE_ERROR</a> errors in
<var>dataModelConformanceChecked</var>.<var>errors</var> if errors are found, by
performing the following checks:
<ol class="algorithm">
<li>
If present, ensure that the `id` property conforms to the "MUST" statements in
Section <a href="#identifiers"></a>.
</li>
<li>
If present, ensure that the `type` property conforms to the "MUST" statements in
Section <a href="#types"></a>.
</li>
<li>
If present, ensure that the `name` and/or `description` properties conform to
the "MUST" statements in Section <a href="#names-and-descriptions"></a>.
</li>
<li>
If the `type` property is present and contains an object with the type
`VerifiablePresentation`, ensure that the object conforms to the
"MUST" statements in Section <a href="#presentations-0"></a>.
</li>
<li>
If the `type` property is present and contains an object with the type
`VerifiableCredential`, perform the following checks:
<ol class="algorithm">
<li>
Ensure that the `credentialSubject` property conforms to the
"MUST" statements in Section <a href="#credential-subject"></a>.
</li>
<li>
Ensure that the `issuer` property conforms to the
"MUST" statements in Section <a href="#issuer"></a>.
</li>
<li>
If present, ensure that the `validFrom` and/or `validUntil` properties conform
to the "MUST" statements in Section <a href="#validity-period"></a>.
</li>
<li>
If present, ensure that the `credentialStatus` property conforms to
the "MUST" statements in Section <a href="#status"></a>.
</li>
<li>
If present, ensure that the `credentialSchema` property conforms to
the "MUST" statements in Section <a href="#data-schemas"></a>.
</li>
<li>
If present, ensure that the `relatedResource` property conforms to
the "MUST" statements in Section <a href="#integrity-of-related-resources"></a>.
</li>
<li>
If present, ensure that the `refreshService` property conforms to
the "MUST" statements in Section <a href="#refreshing"></a>.
</li>
<li>
If present, ensure that the `evidence` property conforms to
the "MUST" statements in Section <a href="#evidence"></a>.
</li>
</ol>
</li>
</ol>
</li>
<li>
If no errors were detected to this point, set
<var>dataModelConformanceChecked</var>.<var>document</var> to <var>inputDocument</var>,
<var>dataModelConformanceChecked</var>.<var>status</var> to `true`.
</li>
<li>
Return <var>dataModelConformanceChecked</var>.
</li>
</ol>

</section>

<section class="normative">
<h3>Verify Securing Mechanism</h3>

Expand Down Expand Up @@ -4896,7 +4767,7 @@ <h3>Problem Details</h3>
The value associated with a particular <a>property</a> is malformed. The
name of the <a>property</a> and the path to the property SHOULD be provided
in the <a>ProblemDetails</a> object. See Section
<a href="#data-model-conformance-checking"></a>.
<a href="#verification"></a>.
</dd>
</dl>

Expand Down