Define the paths an IPLD format implementation should support

[olizilla]

@Mr0grog makes a good point in https://github.com/ipld/ipld/issues/44#issuecomment-411853095

I think that, because path definition is a really important part of IPLD, it’s important for each codec to specify the set of paths it supports. We haven’t done a good job of that. For example, ipld/js-ipld-ethereum#25 is in part caused by not having a clear definition of what fields/paths an Ethereum resolver must present/resolve (regardless of implementation language, since we want the same path to work in JS and in Go and in Rust and in… etc.).

It would be useful to have a resource that defines the transformations that an IPLD format provider performs to make things path-able, and to know what the available paths are. Should such a resource be an extension of https://github.com/ipld/interface-ipld-format/ ?

[Mr0grog]

I think this would be a great idea. I don’t know whether it fits best, but three options seem obvious to me:

1. ipld/specs
2. ipld/interface-ipld-format
3. A separate repo for each data type, so we’d have ipld-ethereum (info about what an Ethereum resolver should expose), js-ipld-ethereum (JS resolver), and go-ipld-eth (Go resolver)

I lean towards (1), but (2) seems reasonable as well. I feel like (3) might get unwieldy and hard to manage.

In the mean time, it might be helpful to make sure every resolver implementation’s README lists the set of paths it currently resolves for each codec it handles. Doing so would help us figure out if and where there are hidden differences between implementations.

[vmx]

Agreed that we need those definitions. I would put them into the ipld/interface-ipld-format repo as it's really about the formats.

[Mr0grog]

For what it’s worth: the reason I lean toward specs is that interface-ipld-format seems more focused on the API interface of a resolver, which a user of IPLD should usually not interact with at all and which is also language-specific, while the set of paths is about the higher-level, language-agnostic idea of how a user would address a particular piece of data. (To make a bad analogy, we need to define the how browsers should parse various kinds of URIs, while I read interface-ipld-format as being about how a browser’s rendering engine and HTML parser communicate.)

[Mr0grog]

That said, my opinion is not a strong one. Just getting this down somewhere is a win! 👍

It seems like we all agree this is a good idea, so what this really needs is someone to go ahead and write a PR in whichever repo they think makes sense with the spec for one codec (e.g. Ethereum objects). We can work through the format of the doc in that PR and then move on with documenting all the other codecs.