search

ipld / docs

All you need to know about IPLD
31 stars 22 forks source link

Comments on "Thinking…" tutorial #1

Open vmx opened 4 years ago

vmx commented 4 years ago

@Mikeal If it would've been a PR, I could've commented there.

In the Addressing section your write:

We encode this data using JSON. Now it has been serialized to a binary representation we can store and/or send to someone else.

I find that confusing as I don't think of JSON as a binary representation. Either make this CBOR or remove the binary representation part. I lean towards CBOR, as doing JSON things within JS might confuse people as it's really similar to their original data.

Later you introduce DAG-CBOR, though even I find it confusing. Why can't you use json? Oh wait, is json not dag-json? If that's the case I would start directly with DAG-CBOR to avoid confusion. If you are new to all this Block.encoder({ name }, 'json') might read as "I want to encode JSON into a Block" and not as "I want this data to be encoded in a Block of JSON".

mikeal commented 4 years ago

I really want to avoid on-boarding people into CBOR and I really do want to leverage people’s existing understanding of how to use JSON for serializing everyday data structures.

However, I can see that the way this is laid out can be confusing. I could write a better explanation along the lines of “JSON can encode common data types into a string which is easily turned into binary and hashed.”

Later, when I introduce dag-cbor I need some more text regarding that transition that links to a much more in-depth explanation fo dag-cbor. For the purposes of this tutorial the reader can think of dag-cbor as “JSON + CID links.”

I do want to keep two codecs in the tutorial though. The fact that IPLD data structures are built as graphs of nodes and aren’t bound to a single codec, that they can in-fact interoperate between codecs, is an idea we should seed early even through all the implications of that won’t be clear until much later. If you recall, there was a time when a lot of the people that knew about IPLD thought it was a euphemism for dag-cbor and I’d like to avoid painting that picture again.

vmx commented 4 years ago

Though this is about DAG-JSON and not about plain JSON, isn't it?

I do want to keep two codecs in the tutorial though

Having two codecs makes sense.