Organize v2 context.

[davidlehn]

The v2 context has been written and updated by hand over time and some of the ordering and formatting was not following a strict pattern. This attempts to clean it up to be easier to read. The format here is somewhat arbitrary, and other formats are possible, but this seems easy to work with. This organization was done by hand.

• Opinionated but consistent organization and sorting.
• Semantically equivalent to data in previous style.
• Order is recursive and roughly follows a pattern:
  • JSON-LD keywords
  • blank line
  • id/type terms
  • blank line
  • jose/jwt property terms
    • sorted
  • blank line
  • other property terms
    • sorted
  • blank line
  • type terms
    • sorted
    • for TypeCredential/Type pairs, put TypeCredential first
    • blank line between each
• Drop down and indent values to try and be under 80 chars per line.

(Note this includes commits from #1510 due to github limitations and will be rebased if/when that is merged.) (Branch was rebased.)

[decentralgabe]

thanks for taking the time to do this

[msporny]

Can we move the JWT properties to the bottom, it's confusing to hit a bunch of JOSE properties for a page and a half before you get to any of the VC v2 properties.

We will probably want to put imported securing mechanism properties, including proof and DataIntegrityProof, towards the bottom of the document.

[davidlehn]

Can we move the JWT properties to the bottom, it's confusing to hit a bunch of JOSE properties for a page and a half before you get to any of the VC v2 properties.

We will probably want to put imported securing mechanism properties, including proof and DataIntegrityProof, towards the bottom of the document.

Other orderings are certainly possible. This change is for humans since the machines will read it the same way. The aim of this first pass was primarily a few major groupings then alphabetical ordering. That matches how I've been trying to read the file in the past and the motivation for this change. While I understand the idea of further grouping, it starts to again make it difficult to find properties and types. I had thought about putting core properties/types first then other specialized ones. But at first glance it didn't seem that great. Open to other thoughts on this. I can adapt to whatever order is used. At least some ordering is an improvement.

And I'll note that "..." is confusing no matter where it is.

[msporny]

Editorial, multiple reviews, changes requested (and no made, but @msporny isn't going to object over them), no objections, merging.

[msporny]

@davidlehn wrote:

I had thought about putting core properties/types first then other specialized ones. But at first glance it didn't seem that great. Open to other thoughts on this.

I took what you did and regrouped with the following layout:

1. All properties are in alphabetical order.
2. Classes are next, which are grouped by "most likely to be used to less likely to be used" order -- e.g., among all of the classes, "VerifiableCredential" is most likely to be used, then "VerifiablePresentation", then "JsonSchemaCredential", and so on. This optimizes for developers trying to find stuff based on a visual scan from the top of the file... if they don't find what they're looking for, they can do a text search for their term (and frankly, the file is big enough that you're probably going to do a search if you don't just scan from the top to find what you want).
3. External classes follow that (e.g., BitstringStatusList)
4. Securing mechanisms are listed at the bottom.

[davidlehn]

@msporny Minor nit with your reordering commit (which wasn't in a PR I think?). Is dropping the trailing newline intentional? This is one of those things that tends to cause some churn due to editor settings and it's inconsistent between projects. In this case it matters since the file will be hashed. I'm on team trailing newline. A .editorconfig might help for this, for those that use that tooling.

[msporny]

@msporny Minor nit with your reordering commit (which wasn't in a PR I think?). Is dropping the trailing newline intentional? This is one of those things that tends to cause some churn due to editor settings and it's inconsistent between projects. In this case it matters since the file will be hashed. I'm on team trailing newline. A .editorconfig might help for this, for those that use that tooling.

Nope, the deletion of the trailing new line was inadvertent. We can add it back in.