Add section on syntactic sugar. See #207 and #268.

[msporny]

Addresses #268 and #207.

---

Preview | Diff

[dlongley]

We might want to say more here about how a "claim" is really a separate graph of statements made by the issuer via a credential... and that JSON-LD uses sugar to keep the JSON syntax simple.

[David-Chadwick]

This is really the wrong way to go. I do not believe we should have claims in the RDF. see #207

[dlongley]

@David-Chadwick, I'm currently exploring if it's possible to drop the @graph container (to at least see if it's a viable option) by checking to see what kind of JSON-LD frame would properly separate the claim information from the proof information.

[msporny]

This was done, thus resolving @David-Chadwick's concern.

[msporny]

"are designed such that developers may easily copy and paste examples to add ..."

Fixed.

[msporny]

• It adds another JSON-LD concept (graph containers) thereby increasing the comprehension distance between a JSON user and the specification. We should not need this concept in VCs.

You need to be able to make statements about statements -- that's what graph containers enable. If you can't do this, the information model becomes non-deterministic and the whole ecosystem falls down. Graph containers (or a concept like it) are not optional.

Keep in mind that developers don't need to know any of this. They just slot the data in the right place. I added this PR because a number of people wanted to know the details... and now that the details have been added, it sounds like you're saying: The details are not necessary.

• Since a VC only contains one cryptographic proof, regardless of the number of claims, then the issue of graph separation is irrelevant. (The same applies for a presentation, which only has one signature.)

VCs don't always contain just one cryptographic proof. For example, VCs that are issued by a group (like a board of directors on a particular vote) may contain N signatures.

• It is not code implementors I am particularly concerned about as the SDK implementors are professionals who should know what they are doing. Application implementors should use SDKs with well defined APIs so this is not a particular concern either. It is the millions of users who will define their own VCs that are of concern. They need to be able to easily understand how the JSON of a VC is composed. What are the (simple) rules for this, and how can I define new VCs and new properties of existing VCs so that they conform to the (largely hidden) rules of JSON-LD. In other words, we should have a simple set of rules (a subset of JSON-LD rules) for how to create correct JSON for VCs, which conform to JSON-LD. This should necessarily remove many of the rules that JSON-LD supports (such as graphs). In other words, all VCs will be valid JSON and JSON-LD, but not all valid JSON-LD will create valid VCs.

While I agree with a subset of what you say above... I need concrete text that I can apply to this PR to make progress.

[msporny]

I believe I have addressed all of @David-Chadwick's concrete concerns. Merging. If a mistake was made, an issue or PR to fix would be appreciated.