Remove JSON section in lieu of application/vc+ld+json.

[msporny]

Based on the resolution of the WG to use one base media type (application/vc+ld+json), this PR removes the old "JSON" section in the spec, which was always of very questionable value. The prose has been updated to specify that the base media type is application/vc+ld+json, and other syntaxes can be used as long as they can map to the base media type.

---

Preview | Diff

[OR13]

what does the word "base" do for us here? feels a bit confusing.

[brentzundel]

I think it reads the same without the word 'base'
I'd support removing.

[msporny]

'base' has been removed in 654b694

[OR13]

Do we want to comment on compact JSON-LD here?

[TallTed]

Probably.

[msporny]

Fixed in 3ef0175.

[OR13]

Feels like we might make some minor wording changes, but overall this is great.

[TallTed]

Please translate for those of us who aren't as hip to the modern meme-lingo... (Really, please don't post things like this in technical discussions. They don't tend to advance the conversation, and they are often needlessly offensive.)

[TallTed]

Probably.

[brentzundel]

I think it reads the same without the word 'base'
I'd support removing.

[dlongley]

Thanks! LGTM and +1 to @TallTed's comments.

[msporny]

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

[alenhorvat]

@msporny @OR13 this means VCDM v2 discards JWT-VC in a form
{
jwt claims here
vc: vc claims here
}
?

[OR13]

See the w3c/vc-jwt spec.

[OR13]

https://github.com/w3c/vc-jwt

[alenhorvat]

Answer is: Yes, VCDM v2 supports JWT-VC?

[Sakurann]

W3C JWT-VC spec describes how to sign using JWS a payload that is expressed using W3C VCDM.

[msporny]

@msporny @OR13 this means VCDM v2 discards JWT-VC in a form

In the case that @alenhorvat is asking a more specific question, that is: "Are v1.0 and v1.1 style VC-JWTs, which place the VC in a field named vc in he payload, supported in v2.0?", I believe the answer to that question is: No, VC-JWTs of the form you mention above are no longer supported by the new VC-JWT specification. Instead, the new VC-JWT specification places the VC in the payload directly with no transformations.

[alenhorvat]

Thank you. Clear.
To rephrase:
q1: VCDM v2.0 recognises https://github.com/w3c/vc-jwt as a valid VC?

"The data model as described in Sections 3. Core Data Model, 4. Basic Concepts, and 5. Advanced Concepts is the canonical structural representation of a verifiable credential or verifiable presentation. All serializations are representations of that data model in a specific format. This section specifies how the data model is realized in JSON-LD for application/vc+ld+json, the base media type for Verifiable Credentials. Although syntactic mappings are only provided for JSON-LD, applications and services can use any other data representation syntax (such as XML, YAML, or CBOR) that is capable of being mapped back to application/vc+ld+json. As the verification and validation requirements are defined in terms of the data model, all serialization syntaxes have to be deterministically translated to the data model for processing, validation, or comparison."

q2: Is my understanding, that VCs can be treated also as JSON (when -LD is not required by the use case) correct? Or one could define a VC in an XML format, for example, and it would be a valid VC according to the VCDM v2.0?

q3: If additional JWT claims are required (because of the signature), are those claims added on the top level?
e.g., iat, exp along with validFrom, validUntil?

[msporny]

q1: VCDM v2.0 recognises https://github.com/w3c/vc-jwt as a valid VC?

The WG is trying to be very careful with the language used around the question "What is a VC?". At the moment, the way to think of the VC-JWT specification is: "A mechanism for securing the Verifiable Credentials Core Data Model using JWTs as described in the VC-JWT specification."

q2: Is my understanding, that VCs can be treated also as JSON (when -LD is not required by the use case) correct?

This is a point of contention in the WG. The original design of VCs allowed for VCs to be treated as JSON as long as you checked/did certain things. The WG has since said that, no, there is only one media type for VCs and that is application/vc+ld+json <-- that is the core data model serialization and it can be secured using a variety of mechanisms (VC-JWT, Data Integrity, etc.). It is that finding that led to the removal of the JSON section from the specification.

In reality, many systems process the VC Data Model as JSON and don't invoke JSON-LD processing until later in the process. For example, an incoming VC might be checked using JSON Schema (JSON processing) before a Data Integrity proof is checked (and in some cases, JCS still counts as JSON processing). It is possible to hard code a JSON-only processing of incoming VCs if the application is specific enough. That said, that is up to implementers to decide when/how to do JSON vs. JSON-LD processing.

Or one could define a VC in an XML format, for example, and it would be a valid VC according to the VCDM v2.0?

At this point in time, there is only ONE serialization format for the VC data model and that is application/vc+ld+json. That said, there are mechanisms that can cleanly round-trip from the VCDM -> some other format -> VCDM. For example, CBOR-LD is capable of taking application/vc+ld+json, converting it to CBOR, transmitting it, and the other end of the connection transforming the compressed binary encoding, losslessly, back into application/vc+ld+json. This is how the TruAge system transmits digitally signed Verifiable Credentials in QR Codes (as CBOR-LD).

q3: If additional JWT claims are required (because of the signature), are those claims added on the top level? e.g., iat, exp along with validFrom, validUntil?

I don't know where the Editors are on this particular item. Perhaps @OR13, @mprorock, and @selfissued can weigh in on this one.

[alenhorvat]

It is possible to hard code a JSON-only processing of incoming VCs if the application is specific enough. That said, that is up to implementers to decide when/how to do JSON vs. JSON-LD processing.

Then VC can be JSON only and essentially an application/vc+json could be completely valid?

In our case, some UC process only JSON, others use JSON-LD (signatures are always JWS/JAdES, where JSON is compared against the JSON schema and no JCS or any other additional processing). Some (most) UC don't define @context for various reasons.

[mtaimela]

The WG has since said that, no, there is only one media type for VCs and that is application/vc+ld+json

I think that the WG should bring the evidence and reasons of why this is beneficial for the ecosystem. I would also like to raise that LD is based on JSON, thus LD is the possible extension.

At this point in time, there is only ONE serialization format for the VC data model and that is application/vc+ld+json.

Requiring JSON-LD to be THE serialisation format will remove all adoption. This second quote will force JSON-LD context to exist, or the attribute will drop during the serialisation. This is not healthy for adoption of VC.

That said, that is up to implementers to decide when/how to do JSON vs. JSON-LD processing.

This spec should be reworded/fixed if the recommendation is to ignore it. Most implementors will not have JSON-LD definitions, and if everyone will just use bogus @JSON, it still adds zero value.

So my single question is, what is the value for the ecosystem to force JSON-LD in? this can be handled in the https://www.w3.org/TR/vc-data-integrity/.

[msporny]

@alenhorvat wrote:

It is possible to hard code a JSON-only processing of incoming VCs if the application is specific enough. That said, that is up to implementers to decide when/how to do JSON vs. JSON-LD processing.

Then VC can be JSON only and essentially an application/vc+json could be completely valid?

At this point in time, the answer is "No". There is no application/vc+json media type because the decentralized semantics of that media type is not defined, nor did the WG come to any sort of consensus of how we'd define that media type or the decentralized semantics around the media type.

The WG has debated this endlessly at this point: #947

This was the most contentious issue the WG has ever discussed and it took close to 9+ months to come to a resolution on just that point. The resolution was to trim the number of media types down to ONE media type, which is: application/vc+ld+json. You can use a single "@context": ["https://www.w3.org/ns/credentials/v2"] (though, that is frowned upon) and not have to define any other @context value. All properties become "issuer defined", which is to say that what you have at that point is a bespoke point-to-point integration that requires coordination between the verifier and issuer. Again, not recommended that you take that route because it leads to interop/market failures.

In our case, some UC process only JSON, others use JSON-LD (signatures are always JWS/JAdES, where JSON is compared against the JSON schema and no JCS or any other additional processing). Some (most) UC don't define @context for various reasons.

Like I mention above, you can do some variation of that, but it's not recommended by a subset of the WG. Other WG members will tell you that it's fine to not have any defined semantics, use JSON Schema to define the semantics, or do some other proprietary thing. The choice is yours, but you shouldn't expect broad interoperability with your solution if you take that path.

[msporny]

The WG has since said that, no, there is only one media type for VCs and that is application/vc+ld+json

I think that the WG should bring the evidence and reasons of why this is beneficial for the ecosystem. I would also like to raise that LD is based on JSON, thus LD is the possible extension.

The reasons are included in this mega-thread, that took 9+ months to resolve: #947

Requiring JSON-LD to be THE serialisation format will remove all adoption.

JSON-LD is now published by 45% of all websites on the Internet: https://w3techs.com/technologies/details/da-jsonld

We are aligning Verifiable Credentials such that they can be easily integrated into the already deployed landscape for JSON-LD on the Web.

This second quote will force JSON-LD context to exist, or the attribute will drop during the serialisation. This is not healthy for adoption of VC.

The WG has debated these points for many years and has decided to go in the direction stated above (for all the reasons that were discussed in that issue thread above).

We tried the alternate path that you are suggesting in the DID WG (multiple media types) and it resulted in a bad outcome as well. The vast majority of implementers implemented with the @context value specified.

So my single question is, what is the value for the ecosystem to force JSON-LD in? this can be handled in the https://www.w3.org/TR/vc-data-integrity/.

The value is that there is ONE media type. The WG came to consensus on the point that having a single base data model syntax was beneficial to the ecosystem because optionality, when it comes to global standards, tends to fragment the ecosystem. Therefore, this is one place where we could reduce optionality while meeting all of the use cases in front of the WG.

[alenhorvat]

VC semantics is great and is well defined. Assumption is that use cases agree to follow the semantics as defined in the specifications.

However, if VC is not processed as LD, application/vc+json is more a appropriate format. Media type is used by the use cases since they need to signal how the content should be processed.
Since many use cases do not have a need for the -ld capabilities, wouldn't it be easier to achieve global interoperability also for these use cases by defining the type correctly in one specification than leave it to the market to do whatever they want.

Question is about vc+json, not vc+jwt (where semantic interop issues appear)

[msporny]

@alenhorvat wrote:

Since many use cases do not have a need for the -ld capabilities, wouldn't it be easier to achieve global interoperability also for these use cases by defining the type correctly in one specification.

The WG tried and failed to define what VCs would look like without JSON-LD for years. While it sounds simple to say, you have to achieve all of the use cases that are defined in our use cases document. "Plain JSON documents, signed with JWS, and non-global semantics" failed to provide a solution that works at scale.

What you are describing is what JWTs are for, and those have largely failed to scale beyond their "security token" use cases. Take a look at the JWT claims registry at IANA and that will show you how far that "vc+json" approach went. VCs exist because JWTs failed to scale in the global market (beyond their limited use case).

The closest you will be able to get to what you want (which, again, is highly problematic and has been demonstrated to not scale in global markets) is to put "@context": ["https://www.w3.org/ns/credentials/v2"] at the top of your document and secure it using VC-JWT (really, just a JWS). You will then immediately hit the problem of semantics that are only defined by the issuer, which will then require the issuer and verifier to coordinate in some way to establish the semantics of the document being processed.

The specification tries to provide some guidance on this topic here:

https://w3c.github.io/vc-data-model/#getting-started

Question is about vc+json, not vc+jwt (where semantic interop issues appear)

There is no such thing as "vc+json" because the group failed to come to any sort of consensus on what that looks like over multiple years of effort in the space.

As an aside, I suggest that you join the WG if you'd like to engage on this topic more, or at least raise an issue and take the discussion there. I will note that there is a /very long history/ of this discussion in this group via #947 and it is unlikely that the WG is going to revisit this topic given how much time it has already eaten in the WG to date.

[alenhorvat]

I agree with you and everything you wrote. I fully understand the interop and scalability issues. Proposal/question is very simple:
If VC has the format and structure as defined in the standard for application/vc+json+ld (with all the claims, etc) but the context is not processed, would it make sense to use application/vc+json

If answer is no, this simply means we need to define a profile for it (definition of the profile would essentially be the statement above). I'm arguing that it is more beneficial to have it in the specification.

To clarify: the proposal is

• not to make the @context optional
• not to change any of the defined claims (e.g., replace them by JWT claims)
  and the goal is to NOT reopen any of the painful discussions.

People will use and process VCs as JSON for various reasons. Suggestion here is to take what's been defined and the WG agreed upon and just provide guidelines or show that if UC is not defining @context for the claims and types they introduce (e.g., the UC does not require global interoperability) and they are processing it as JSON, use application/vc+json

[dlongley]

@alenhorvat,

If VC has the format and structure as defined in the standard for application/vc+json+ld (with all the claims, etc) but the context is not processed, would it make sense to use application/vc+json

This is mixing semantics with mime types. The group had many long discussions about disentangling these -- mime types do not solve the semantics problem.

The base media type for VCs is application/vc+ld+json; this mime type is used even if you don't add another context to define your terms, i.e., you rely on @vocab. Notably, I think you can already do what it sounds like you want to do without performing any JSON-LD transforms (i.e, "process JSON-LD context"). Just make sure the JSON value of @context is only the core context URL in your application, i.e., disallow any context extensions, and it should function as it seems you want it to. If you wanted, you could also incrementally allow specific context extensions that you decide to understand and check for those URLs as well -- all without your application ever having to perform any JSON-LD transformations. But this is up to you.

[alenhorvat]

We're not trying to solve the semantics problem. We're just trying to find a way how to express what it seems we agree: VC (as defined today) can be treated and processed as JSON.
Question is: how to express this in a machine readable way?

mime type? any other way?

We don't want to use custom way to express that in some cases VC should be processed as LD and in other cases as JSON. In our case JWS (compact or JSON serialised) is applied to both.

[mtaimela]

Thank you @msporny for the time and devotion, much appreciated.

I can see from the answers that JSON-LD as requirement is not really a requirement at all. All deterministic, bi-directional, and lossless serialisations and transformations can be done with default context of "https://www.w3.org/ns/credentials/v2". Without extending this, it will work exactly like JSON, and supports both, JSON-LD and JSON processors.

Media type of application/ld+vc+json in this way is also equal to application/vc+json, but the latter one should not be used to have just one media type for the VC. There's just the extra boilerplate of context with the default value.

[TallTed]

• @mtaimela (you appear to have previously been known as @isomasa, which no longer resolves, but is still associated with the comment which link follows?) — s/application/ld+vc+json/application/vc+ld+json/g in your comment. Yes, it matters.

• @alenhorvat — s/mime type/media type/g in your comment and s/application/vc+json+ld//application/vc+ld+json/g in your comment. Yes, these matter.

• @dlongley — s/application/ld+vc+json/application/vc+ld+json/g, and s/mime type/media type/g in your comment. I know you know these matter.

• @msporny — A little markdown error in your comment. s/single `"@context": ["https://www.w3.org/ns/credentials/v2"] (though, that is frowned upon) and not have to define any other `@context`/single `"@context": ["https://www.w3.org/ns/credentials/v2"]` (though, that is frowned upon) and not have to define any other `@context`/ will help clarity.

[mtaimela]

Thank you @TallTed.

I fully agree that having 100% semantic web, where all data and transactions are machine readable is where we want to be. But I also have to embrace the fact of legacy and allow the natural adoption of semantics. This is not an easy task and I do not want this to hinder other achievements like SSI and give the control of data to the owners of it.

I wrote a small summary, for everyone else in the world reading this thread. Could it be possible to respond if summary the below is how it was intended.

VCWG decided:

• @context is required (MUST) in the base media type, other media types MAY choose to include @context.
• Bi-directional transformation MUST preserve @context
• Transformation rules MUST be defined, but not necessarily by this WG.

Specification states:

• Although syntactic mappings are only provided for JSON-LD, applications and services can use any other data representation syntax (such as XML, YAML, or CBOR) that is capable of being mapped back to application/vc+ld+json
• default JSON-LD @context is https://www.w3.org/ns/credentials/v2, .... for the base media type of application/vc+ld+json.

Thread agrees:
JSON can be converted into "Issuer defined JSON-LD", by applying the default @context. This is frowned upon as it doesn't improve semantic web.

confirmation needed:
VCDM 2.0 compatible VCs are "any data representation syntax" when the serialisation towards JSON-LD is deterministic, bi-directional, and lossless, as long as it may be converted into JSON-LD with the original @context (custom or default). The serialisation must be documented.

[msporny]

@mtaimela wrote:

I fully agree that having 100% semantic web, where all data and transactions are machine readable is where we want to be. But I also have to embrace the fact of legacy and allow the natural adoption of semantics. This is not an easy task and I do not want this to hinder other achievements like SSI and give the control of data to the owners of it.

JSON-LD is designed to use as much of it as is useful to you. The VC Data Model attempts to follow the same approach, with a few important nuances.

I wrote a small summary, for everyone else in the world reading this thread. Could it be possible to respond if summary the below is how it was intended.

Yes, answers below:

• @context is required (MUST) in the base media type, other media types MAY choose to include @context.

Yes, with the warning that "other media types" is probably not going to be defined very clearly in this iteration of the VCWG (as we are running out of time in our charter and will enter complete and utter feature freeze in September). We are currently dealing with too many other things, and the "transformations" language has proven to be contentious (thus it is unlikely that we'll be able to achieve consensus on EXACTLY what that means... though I can try to provide insight into where the VCWG might be heading in future iterations).

• Bi-directional transformation MUST preserve @context

Yes (but I expect that we will not see that text appear in v2.0, possibly during v3.0 once the market has settled down a bit on the transformations stuff).

I will note that CBOR-LD is an example of something that exists today that transforms to a completely different binary data stream, but is able to round-trip and thus preserve @context. So, the VCWG is well aware that this is possible for organizations that act in good faith. It's the organizations that might not act in good faith that are the concern, which means we would have to be very careful about what language we write as writing the wrong language will have organizations claiming that they are "100% compliant W3C VCs", when they are not (or are doing the bare minimum, like using "issuer defined terms" without defining an @context which can lead to interop failures at scale).

• Transformation rules MUST be defined, but not necessarily by this WG.

Yes, but again, the VCWG will almost certainly not include this text in the current specification and wait for market feedback to drive the sort of language that will lead to a healthy, interoperable ecosystem.

• Although syntactic mappings are only provided for JSON-LD, applications and services can use any other data representation syntax (such as XML, YAML, or CBOR) that is capable of being mapped back to application/vc+ld+json
• default JSON-LD @context is https://www.w3.org/ns/credentials/v2, .... for the base media type of application/vc+ld+json.

Thread agrees: JSON can be converted into "Issuer defined JSON-LD", by applying the default @context. This is frowned upon as it doesn't improve semantic web.

Yes, though this isn't about the "semantic web". It's an information modelling problem that exists in any system with locally defined terms that were never meant to be used globally. Think of every proprietary JSON HTTP API out there now, the data objects that they publish largely only work at one domain.

If something is issuer-defined, then you have to have an out of band communication with the issuer to understand the proper usage of their terms, which will almost certainly conflict with other issuer-defined terms. If one issuer says "name" means "the name of your website", and another issuer says "name" means your full name, then the issuers mean very different things and you can't count on interoperability between those issuers. If you look at this problem at scale, it would require you to have to either 1) contact every issuer out of band to understand how they're using their terms, or 2) centralize the market to a very small set of issuers that have an agreement on which terms they are using (which would be a market competition failure).

confirmation needed: VCDM 2.0 compatible VCs are "any data representation syntax" when the serialisation towards JSON-LD is deterministic, bi-directional, and lossless, as long as it may be converted into JSON-LD with the original @context (custom or default). The serialisation must be documented.

Yes, close, and here's where you're not going to get much more guidance from the VCWG. The following is my interpretation of what's probably going to happen in time:

digital credentials that are compatible with the W3C Verifiable Credential Data Model are credentials where they can be transformed to the VCDM and where the interpretation of those transformed VCs remains the same as their original interpretation. That is, one could say that their digital credential is VCDM 2.0 compatible if:

The digital credential can be unidirectionally transformed to the VCDM and can be clearly interpreted in the way it was originally intended to be interpreted (before it was transformed).

Bonus points if the digital credential can be bidirectionally transformed to the VCDM and can be clearly interpreted in the way it was originally intended to be interpreted (before it was transformed AND after it is re-transformed back into the original digital credential).

This would enable people to say "mdocs are compatible with the W3C VCDM" if such a unidirectional or bidirectional transformation mechanism was documented /somewhere/. That's what the VCWG was going for, and again, this is my interpretation of what could be the best outcome given the various opinions in the WG. It's quite a large and active WG, so coming to consensus on topics such as these has started to increasingly take more time than it did in the early days (for better or worse).

Does that help explain the current state of play more @alenhorvat and @mtaimela?

[alenhorvat]

Thank you @msporny and others for these valuable responses.

Yes, it answers my questions and resolves my concerns. It is a nice evolution from the VCDM v1.1.

IMO the answers should/could be compiled into a blog post or FAQ or similar, since we see the question re-appearing over and over.

Thank you!

[mtaimela]

Thank you @msporny very much for your valuable time and efforts on the topic and for the work on the VC. This answered all the questions I had, it is great concept and looking forward for the evolution of future v3.

[msporny]

@mtaimela and @alenhorvat, two new PRs have been raised to clarify the questions that both of you had. I have tried to incorporate your feedback in both of them:

#1202 (Add section on JSON Processing)

#1203 (Add section on Ecosystem Compatibility)

Please let us know your thoughts and if both of those PRs address your concerns.