Spec refining: Properties in links

[nicola]

The current spec defines that links are represented using the keyword property /. However, it doesn't specify what are the constraints for the link object.

// Valid IPLD
hash1
{
  hereIsALink: {'/': HASH},
  size: 500
}

// IPLD with property in a link
hash2
{
  hereIsALink: {
    '/': HASH,
    'size': 500
  }
}

Should we support properties in links or should we not support that?

If we decide to support this, the property size cannot be addressed with an IPLD pointer, however, this property can still be accessed by loading the object hash2 and manually/programmatically traverse the object to get the size value.

Reason to support

• the difference between ipld data model and json is just reserving the keyword /
• developers can hide whatever they want

Reason not to support it

• hidden elements make IPLD a little bit more complex (hidden properties cannot be addressed)
• makes IPLD not transparent

Idea
A great idea would be to properties that are not specified by our spec, so that we can reuse this space for future reserved keywords

---

cc @jbenet, @mildred, @dignifiedquire

[dignifiedquire]

I prefer the simplest viable solution which in my opinion is disallowing any other siblings to / in the link object.

[nicola]

Yes, that is my opinion too. In this way we can reserve that space for links specific things (say one day we want to specify some new keywords, we can use this space for that)

[nicola]

Also, what we have to define is if this is a MUST NOT, or a SHOULD NOT

[jbenet]

We already bikeshedded this a ton over the last months, it was the source of months of disagreement and arguments. In the end the decision NOT to allow this was critical in cleaning up pathing.

The way to treat it in the spec is (rewording it for clarity) one of two options:

1. Completely disallow it, treat it as an error. (MUST NOT)

• Link objects MUST NOT contain other properties.
• If they do, the object is not treated as a link and resolution through it is disallowed. Addressing its data is disallowed. Attempts to resolve or address properties MUST return an error.

2. Remove it from the model, but work with objects that happen to have it. (SHOULD NOT)

• Link objects SHOULD NOT contain any other properties. But if there is an object with other things, the formal IPLD model does not recognize the other properties, and addressing / resolution ignore them.
• In case an object "has extra data" tools MUST NOT expose this other data items to pathing or addressing.

Notes

• This is really only a problem because JSON does not let us define "types" and we hacked it with {/: <link> }. this is entirely a JSON side-effect and DOES NOT really show up in CBOR, YML, and other more expressive formats.
• Allowing (2) will complicate implementations of IPLD in various formats. Forcing (1) lets us define special types in CBOR and other serialized formats that are very compact, and DO NOT allow properties.
• Allowing (2) will be the source of much confusion in users and tools that decide to go against the spec (or fail to realize it) and let users address those properties.
• Forcing (1) is "simple" and (2) is "complex" in the Rich Hickey sense of the word.
• I think we should do (1). It's going to be a bit annoying at first (forcing us to throw errors) but much more valuable long term by increasing simplicity.

[dignifiedquire]

👍 for (1) for the reasons you mentioned and from the perspective of implementation. It's straightforward to enforce this and throw appropriate errors instead of trying to figure out how to handle additional props.

[nicola]

🎉 Perfect, we are all aligned.
(as I mentioned this can also be great in case we want to reserve new link object features)

[rvagg]

Closing due to staleness as per team agreement to clean up the issue tracker a bit (ipld/team-mgmt#28). This doesn't mean this issue is off the table entirely, it's just not on the current active stack but may be revisited in the near future. If you feel there is something pertinent here, please speak up, reopen, or open a new issue. [/boilerplate]