Only DOCUMENT conformance matters

[burnburn]

TL;DR We need to ensure that only DOCUMENT conformance statements exist in the specification, rewriting or removing existing statements if necessary.

This is a specification for a data model and a few syntactic realizations of that data model.
We are not defining an API or a protocol, and thus there are no formal requirements on processors other than to state implementation of features of the data model / syntax as described.
It is appropriate to define what a 'conforming document' is. Any statements about what a 'conforming processor' must do beyond 'support a conforming document as described in this specification' are suspect.

Here are several examples of W3C specifications that define a document format, as we do, without an execution semantics (except for JSON-LD itself, for which various transformation processes are defined). For each, first take a look at the Implementation Report to see what ours might look like. Then you can look at the spec itself for the conformance language they adopted.

DCAT: IR (http://www.w3.org/2011/gld/wiki/DCAT_Implementations), Spec conformance (https://www.w3.org/TR/vocab-dcat/#conformance)
EMMA: IR (https://www.w3.org/TR/emma/#s5), Spec conformance (https://www.w3.org/TR/emma/#s5)
JSON-LD: IR (N/A), Spec conformance (https://www.w3.org/TR/2014/REC-json-ld-20140116/#conformance)

Note in the above examples that requirements are generally around support of the syntactic features of the language. Although some semantics can stray into the descriptions, they are typically co-occurrence or dependency statements, similar in principle to subject-verb agreement in English.

@stonematt and I believe this is the source of much of the scope confusion that has occurred in our discussions over the last few months, and in particular the concerns that Ted has (appropriately) raised. As chairs, we want to see all of the conformance language in the specification (MUST, MAY, SHOULD, etc.) be checked and, if needed, rewritten in the form of requirements on the specification itself and not on processors. If it is not possible to write it that way, it CANNOT be a normative requirement in our specification, although it could be informative text or moved to the Implementation Guide.

When evaluating whether the requirement is on the document itself, it may be helpful to try to phrase the requirement in the form "It is a property of a verifiable credential that XXXX", where XXXX is not allowed to refer to an Issuer, Holder, or Verifier (in short, a processor). If this is possible, then the requirement is most likely a data model/syntax requirement and can be written as such.
You can also think of document conformance statements as "things that are true no matter when checked", while processor conformance statements are "things whose truth depends on when they are checked".

Examples of appropriate conformance statements (not necessarily correct, but of the right form)

• the value of the id property MUST be a URI.
• the value of the age_plus_one property MUST be exactly one more than the value of the age property.
• the expirationDate property is OPTIONAL. If present, its value MUST be a string value of an [ISO8601] combined date and time string.

Examples of inappropriate conformance statements:

• an Issuer MUST set the id value to a URI
• a Verifier MUST ensure that the expirationDate has not passed the current date and time

Examples of informative (non-normative) statements that we (and PING) might still want:

• it is expected that dereferencing the (id property value) URI would result in a document containing machine-readable information about the identifier.
• the expirationDate property is used to represent the date and time the credential ceases to be valid.

Dan and Matt, VCWG Chairs

[jandrieu]

This feels like a solid framework for clarifying a bunch of text.

One question: how does this fit into the use-case driven "requirements"? It seems there is agreement that the use case document is a good place for illustrating the larger ecosystem, that is, how VCs will be used--not just how a document is conformant.

There is a section in the data-model that is a non-normative distillation of the use cases in terms of requirements. When the use case team reviewed this section, we updated it to meet our current understanding of the current consensus requirements. We slipped into "conformant" language, with "MUST" and "MAY". However, we are struggling to find the right voice.

Based on your comments above, maybe we were trying too hard to be normative. Rather, we should be clearer that this is what the use cases suggest as requirements for the spec, rather than requirements for conformant documents.

Thoughts?

[burnburn]

Use cases are clearly there to demonstrate the entire ecosystem.
Requirements can be written either for the entire ecosystem (data model + protocol + ?) or for just the data model (and syntaxes).
Assuming we do the latter, the requirements can use RFC 2119 language, but only of the form "The data model MUST provide a means to represent digital signatures over a verifiable credential" or "A JSON-LD representation of the data model MUST be defined." The former is a requirement on the data model, while the latter is a requirement on the specification. The only trick with requirements on the data model is that they should NOT specify how to represent something, merely what must be representable.

[burnburn]

@ashimura also gave another great example, the WoT spec.

IR: https://w3c.github.io/wot-thing-description/testing/report.html
Spec: https://www.w3.org/TR/wot-thing-description/

[msporny]

I have made a complete pass through the specification (commits 175f07e and 3059153) and ensured that all MUSTs, RECOMMENDED, SHOULDs, MAYs (and their respective NOTs), specifically talk about document conformance and do not talk about issuer, holder, or verifier conformance.

The next step is to ensure that the tests in the test suite are aligned w/ all MUST/SHOULD/MAYs in the document via w3c/vc-test-suite#6... but I think that for the purposes of this issue, we're done. Closing. Re-open if you disagree.