Remove document conformance checking algorithm section

[msporny]

This PR attempts to address issue #1375 by removing the document conformance checking algorithm section, clarifying the definition of "document conformance", and then using the updated definition to reduce the (arguably) repeated conformance language.

/cc @jyasskin

---

Preview | Diff

[jyasskin]

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?

[msporny]

The WG didn't like that language, as of the last meeting. It's been removed in a515e6f.

[jyasskin]

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.

[msporny]

Good catch, fixed in: 7edc347

[jyasskin]

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"?

[iherman]

@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

[msporny]

@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

[TallTed]

"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.

[dlongley]

@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.

[TallTed]

@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?

[msporny]

The problematic text has been removed in commit (based on consensus reached in the last WG meeting): a515e6f

[iherman]

The issue was discussed in a meeting on 2023-12-12

• no resolutions were taken

View the transcript

2.5. Remove document conformance checking algorithm section (pr vc-data-model#1381)

See github pull request vc-data-model#1381.

Brent Zundel: now to 1381.
… remove document checking section.

Manu Sporny: Orie requested changes on the verification algorithm, specifically that part that checked document conformance.
… It did it in a way to call out every single property to check.
… That's what Jeffrey asked for.
… Orie disagreed and wants it to be restored.
… So, basically "read the doc, do the MUSTs".
… Jeffrey was ok with that. This PR does that by becoming much more concise, accurate, about what a conforming document is or is not.
… document: must be compact JSON-LD that follows all of the MUST statements in the specification, pointing to the sections with those MUST sections.
… and it does a few more things TallTed is worried about.
… it also aligns the discussion about "Big Tent" into the credential type specific processing section.
… Also, "you may, transmit and store a conforming document in a variety of serialization formats" as long you can bring that back.
… that invites others to profile VCs.

Ivan Herman: Manu, look at #1381 (comment) for possible bike shedding on terminology.

Ted Thibodeau Jr.: I don't see the path to resolving my concerns. My comments said the definition change is substantial.
… The degree of substantialness...
… yes you can wrap it, but since you have to bring it back, what's the point.
… I'm not understanding the motivations.

Brent Zundel: would it be fair to say since a conforming document is well described why talk about other serializations?

Manu Sporny: one path is to remove the language about serializations. because it should be obvious.
… but we spent a long time discussing that, so maybe we should put it in there, even though it's blindingly obvious.

Dave Longley: i think we need to assuage the concerns of people who want to transform/envelope/whatever as long as you can come back again (even if it's obvious you can do that).

Dave Longley: +1 to Manu, it's been a concern from others.

Ted Thibodeau Jr.: "Deterministic and 100% reversible transformation to or encapsulation in other media types is permissible.".

Joe Andrieu: I share TallTed's concerns, I appreciate we want to have roadmarkers for conversations we've had before, we should have language that says "other serializations" are not VCs. I think we need to make it clear that those other things aren't VCs. I don't want people to think that they can call those other things VCs.

Brent Zundel: note we do say that "serialization must be ..." we already say that.
… what we can say, we have already agreed on and said.
… So I'm leaning towards just keeping what we have.

Manu Sporny: that language is being deleted in this PR.

Brent Zundel: can we not delete it?

Manu Sporny: yes. that's an option.
… people are saying reasonable things.

Brent Zundel: looks like we have a path forward for 1381.

Dave Longley: "another serialization that transforms a conforming document is not a conforming document itself... and it must be (bi-directional, yada-yada)" maybe.

[iherman]

The issue was discussed in a meeting on 2023-12-13

• no resolutions were taken

View the transcript

2.8. Remove repetition of normative statements in verification algorithm (issue vc-data-model#1375)

See github issue vc-data-model#1375.

Brent Zundel: labeled with PR exists, manu can you give an update?

See github pull request vc-data-model#1381.

Manu Sporny: lots of approvals, some unaddressed changes and questions, does not seem to have anything blocking.
… it would remove a large chunk of duplicated normative statements.
… seems this will merge over the weekend.

[iherman]

The issue was discussed in a meeting on 2023-12-13

• no resolutions were taken

View the transcript

2.10. Separate verification from validation in verification algorithm (issue vc-data-model#1376)

See github issue vc-data-model#1376.

See github pull request vc-data-model#1381.

Brent Zundel: separate verification and validation, PRs exist.
… we have discussed, seems it is on a good trajectory.
… comments?

[msporny]

Normative, multiple reviews, changes requested and made, no objections, merging.