Explain JSON-LD further. #1270
Explain JSON-LD further. #1270
Conversation
BigBlueHat
requested review from
msporny,
OR13,
selfissued,
decentralgabe and
awoie
as code owners
BigBlueHat
force-pushed
the
issue-1227
branch
from
1090e2e
to
b64affe
Compare
Addresses w3c#1227.
BigBlueHat
force-pushed
the
issue-1227
branch
from
b64affe
to
3932fb4
Compare
Looks like I forgot the "non-normative" intro text. I'll add it. I agree it can use paring down, but given the group continues to attempt to span to ecosystems of parsing approaches--in which there are multiple "normative" ways to do most things--the connection this makes to the JSON-LD ecosystem and the benefits available within it is rather the point and focus of the text. Happy to entertain specific reduction/simplification requests! |
The text is now marked as "informative". I'll continue to work to pare it down as more reviews come in--but given that "pare down" is not a defined target, if you could re-review or un-minus-one until there's a substantive thing I can address, I'd greatly appreciate it! |
| mechanisms without altering or damaging the underlying data structure. This | ||
| creates economies of scale which reduces development time, decreases | ||
| retooling cost, decreases time to market, and provides long term stability for | ||
| Issuers, Verifiers, and Wallets. |
There was a problem hiding this comment.
| mechanisms without altering or damaging the underlying data structure. This | |
| creates economies of scale which reduces development time, decreases | |
| retooling cost, decreases time to market, and provides long term stability for | |
| Issuers, Verifiers, and Wallets. | |
| mechanisms without altering or damaging the underlying data structure. |
There was a problem hiding this comment.
Shared foundational data models and consistent data processing pipelines do quantifiably reduce development time, decrease retooling cost, etc. Could you expand on why you'd like this statement removed?
There was a problem hiding this comment.
@Sakurann this paragraph remains unchanged in the most recent revision, so please let me know if there are specific complaints with the above claims. Thanks!
|
not in favor of this PR, suggest that this PR not be merged |
It is impossible to consider modifying my position to match yours without more words from you about why you hold it. |
|
The issue was discussed in a meeting on 2023-09-14
View the transcript1.4. Explain JSON-LD further. (pr vc-data-model#1270)See github pull request vc-data-model#1270. Brent Zundel: Explain json-ld further. A section that was widely asked for. Has had comments back and forth, no approvals. More work to be done. We'll time box to 10 minutes what changes are needed from folks. Michael Jones: This PR is a lot of philosophy and not a lot that helps implementers. Manu Sporny: The group asked us to write this. They asked for "we want to see a section that explains json-ld". We have other places in the spec that explain why some choices were made. Sebastian Crane: It looks good on a first impression. I would prefer for it to be cut back. Not because it is incorrect, but it includes some things that sounds like opinions. This makes folks uncomfortable. I would suggest som word smithing. I would object to merging now, but ok in the future. Brent Zundel: Suggestion is to make concrete suggestions. Michael Jones: There are 14 new paragraphs. Please cut it down accordingly. Ted Thibodeau Jr.: The entire section is informative. It might be better as an appendix.
Brent Zundel: Happy to hear thought about the appendix suggestion. Manu Sporny: +1 what TallTed said. It's really difficult to understand the changes requested without suggested changes. Please either write a PR, or make concrete github suggestions. Kristina Yasuda: Re: moving to appendix. I do believe we need a few short and sweet paragraphs in the main text. More details can go in the appendix. Doesn't need to be pre-cr. Bottom line, the goal is to give folks some background on JSON-ld before sections that work off of it.
Brent Zundel: Since this PR is non-normative, it's not urgent to merge this PR. |
Could you provide something more concrete to review, discuss, or respond to? |
|
The intro is significantly reduced--with special thanks to @dlongley for his collaboration! |
There was a problem hiding this comment.
This PR adds a lot of informative text that isn't actionable by implementers. It's more philosophy than specification.
It was the job of the JSON-LD spec to explain JSON-LD. Please simply cite it, possibly with a section reference, along the lines of "For more about JSON-LD, see [ref]" and stop there. The current contents of this PR doesn't belong in our specification.
There was a problem hiding this comment.
I've like to see specific text providing guidance on processing the core data model as RDF.
JSON-LD is a concrete RDF syntax as described in [RDF11-CONCEPTS]. Hence, a JSON-LD document is both an RDF document and a JSON document and correspondingly represents an instance of an RDF data model.
Some ideas to help frame what I would like to see:
- https://www.w3.org/TR/json-ld11/#advanced-context-usage
- https://www.w3.org/TR/json-ld11-framing/
- https://www.w3.org/TR/sparql11-overview/
Basically, we have a lot of text that says "you don't need to process the core data model as JSON-LD".... but we have yet to show any value for processing the core data model as something other than JSON (as JSON-LD, which by definition is also RDF).
I think it would be best to address this directly in the context of related work at W3C, for example:
https://github.com/WICG/identity-credential/blob/main/identity-credential-proposal.md#mdocs
Notice the way the above specification does not use RDF predicates... Why would it be better to use RDF predicates and JSON-LD frames?
If there is no benefit to processing the data model as RDF, we should state that explicitly, and warn implementers that RDF predicates and RDF types are not stable extension or interoperability points.
Co-authored-by: Ted Thibodeau Jr <[email protected]>
We've had this backwards. Developers always process the core data model as JSON-LD, they may just be using the more limited approach defined in the JSON Processing section. JSON-LD is a syntax and you can access it directly. You can do things like pre-process a context once (or have a trusted party do this for you) and then write your code against supported contexts or context hash values. This is still doing JSON-LD processing…just a more limited form of it which attempts to optimize it based on accepting only specific inputs. The content we have in the spec today that explains how to do these optimizations in JSON parsing land is unnecessary when you use a JSON-LD library to convert from one context to another or to RDF, but not doing that does not mean you're not doing JSON-LD processing. We should probably rename that section to "Optimizing JSON-LD processing (for specific use)" instead of "JSON Processing". Again, JSON-LD is a syntax and developers should read it as long as it is being provided with a context you accept. JSON-LD tells you the context of the data as currently expressed. This is true even if one chooses to process JSON-LD in a more limited way. It’s still JSON-LD. Additionally, these more limited JSON parsers do not do the following (at least not without nearly recreating JSON-LD processing...):
All of this is expressed in what I've written.
This happens everywhere there's a belief that English words mean the same thing within all the communities that use them. You can read through the various specifications which they are trying to combine to find that's not the case. Each of those specs have different type systems, value definitions, etc. All of those facts could coexist more easily when mapped to non-conflicting identifiers, value definitions, etc. The reconciliation example becomes far simpler (perhaps using JSON-LD Framing) when JSON-LD is used. |
This is great, I think the "JSON Processing" section is confusing and should be removed.
I'd say its not necessary regardless of which libraries you use.... and the fact that you can be "doing JSON-LD processing" when "not realizing it" is a security and readability issue in the current spec, that needs to be addressed.
^ maybe it would be better to define "JSON-LD Processing first", and then define "limited / unsafe JSON processing second". |
|
@BigBlueHat I suggest you pull anything useful that is removed in #1298 into this PR, and say in plain english essentially what you said in #1270 (comment) |
|
The issue was discussed in a meeting on 2023-10-04
View the transcript1.1. Explain JSON-LD further. (pr vc-data-model#1270)See github pull request vc-data-model#1270. Manu Sporny: so, 1270 has multiple requests for changes. Orie Steele: we have this section about JSON processing...which I don't really like.
Orie Steele: and doesn't help people use RDF or JSON-LD.
Michael Jones: this PR kind of runs at the mouth.
Dave Longley: trying to figure out where to start.
Dave Longley: new comers are often confused by the ability to process JSON-LD further with libraries.
Dave Longley: the JSON processing model section basically says that if you know it's using these
Dave Longley: but now we have the counter request to remove all of this--both JSON-LD values that were requested and the JSON processing section.
Dave Longley: it's valuable to explain this value and how it helps and has helped this community since the beginning. Kristina Yasuda: I don't think we don't want to have this section. Ted Thibodeau Jr.: I started off being extremely frustrated by two voices in this conversation.
Ted Thibodeau Jr.: I kinda want to lock Orie and selfissued in a room and let you hash it out.
Ted Thibodeau Jr.: he hasn't put the concrete suggestion forth. Kristina Yasuda: this is an inclusive environment. Ted Thibodeau Jr.: you're spending more time on this than anyone. Kristina Yasuda: please leave the call TallTed. Brent Zundel: ivan please remove TallTed from the call.
Michael Jones: strangely related to what TallTed was saying. Ivan Herman: clarification. you mean a separate WG note document, correct? Michael Jones: yes. Kristina Yasuda: there is a separate JSON-LD spec...so I'm not sure a separate note gets us much.
|
|
This comment is generally on the text, regardless of where it ends up (whether in a separate note or in the VCDM spec). The text uses the analogy/reference to object-oriented modeling as a paradigm "familiar to developers". This familiarity is what worries me, because, usually, object-oriented terminology refers to the "class" feature in languages like C++, Java, Python, TypeScript and, more recently, JavaScript. And this analogy is wrong and misleading when it comes to RDF. RDF uses the term "class", but that is in the sense of ontologies. In, say, Java one assigns the type of an "object" as a declaration, and that is bound to the object for life. Object declaration is (also) a constraint for the properties (attributes) that one can use in conjunction with that object. The type of an RDF resource can also be assigned at "declaration" (that is what As an example, if my dataset contains these two triples: then I can infer the following statement: The misunderstanding on the nature of domains and ranges has come up several times in this Working Group as well, and this is mostly because people often believe that RDF's classes are analogous to classes in object-oriented languages. We should not reinforce this misunderstanding. I would therefore propose to remove all references to object-oriented modeling from the text in the PR. cc @pchampin |
|
In case you missed this, w3ctag/design-principles#239 (comment) Very relevant to the guidance we are attempting on this PR, and on #1302 |
|
The object-oriented references in the text above pertain to how statements about subjects are expressed in JSON (as JSON-LD). They are not about the RDF as much as your comment suggests, but the modeling does enable consistent processing to enable mapping to / from RDF much more simply. What is trying to be said here, is that, in JSON, there are "objects", which have "keys" (aka "properties") and "values" associated with those keys. Someone designing a JSON document, could, if they wanted (and clearly some often do!), decouple their data model from these primitives, using them any which way. For example, if we wanted to model a "car", which has a color, an engine, and a number of wheels, we could express this information in JSON any number of ways. For example: {
"thing": "car1",
"engine": true,
"wheels": true,
"car1Props": [["color", "red"]],
"car1Wheels": 4,
"car1Engine": ["electric"]
}There's a lot of JSON in the wild that evolves organically and ends up looking like that. Applications that consume it might have bespoke rules that have also evolved over time... "if you see 'thing' and it's value starts with 'car', then it's a car, and its properties will be in the rest of that value + 'Wheels' or + 'Engine', and you'll know if those are there if 'engine' or 'wheels' are true, and if the car has other properties it will be under + 'Props' as nested arrays, etc.". An alternative expression might be: {
"id": "car1",
"type": "Car",
"color": "red",
"wheels": 4,
"engine": {
"type": "ElectricEngine"
}
}And the rules for processing this data can be more consistent. In fact, you can write consistent processing rules for most things modeled this way because the data model concepts are more tightly coupled to the primitives provided by JSON. It also adds compositional capabilities to your data. JSON-LD requires JSON to be interpreted in this way, such that authors must model their data accordingly as consumers can and will presume this basic modeling is built-in. This is an important concept to express as an advantage of using JSON-LD (over "vanilla JSON" where anything goes) as it eliminates (or greatly reduces) situations like the first example, where complex bespoke processing rules must be written into applications to even figure out a basic interpretation of the information one is expressing. Requiring "JSON objects" to actually express "objects" in the information model and JSON keys/properties to actually express the properties of those objects is "object oriented" and should be highlighted as a benefit. |
|
@dlongley I do not question those advantages of JSON or of JSON-LD. But "object-oriented", to me, resonates primarily to the programming concepts in object-oriented programming languages. That, plus the obvious relationship to RDF, does bother me. I won't lie down the road over this, obviously; if this works for everyone else, be it. I just wanted to express my discomfort. Maybe the reason that I never look at JSON-LD in isolation but only through the goggles of RDF... (And no, I do not have a good alternative term in my mind right now.) |
|
Proposal from the WG call: We should move this text to the VC Implementation Guide in order to "move it forward"... no objections on the call. |
|
The issue was discussed in a meeting on 2023-10-17
View the transcript2.1. Explain JSON-LD further. (pr vc-data-model#1270)See github pull request vc-data-model#1270. Brent Zundel: The chairs feel that this is prime example of a PR that is unlikely to achieve consensus. Manu Sporny: +1 to this one not making it in. It has text that some in the group feel strongly about, moving it to the VC implementation guide and linking it is something Mike Jones did not object to. Brent Zundel: Anyone want to object to that proposal? |
|
I have raised w3c/vc-imp-guide#71 to track adding this text to the implementation guide. |
|
Pending close has been marked on this PR for 2 weeks, the issue is being tracked in the vc-imp-guide repo. Closing. |
Addresses #1227.
That issue accumulated many references with many requests for it to address all maner of things. I'm confident I did not address them all. However, I hope this further explains the value of JSON-LD to the VCDM.
Preview | Diff