Model parent/children relationship.

[tisto]

There are different ways to model the parent/child relationship for our JSON objects. Possible attribute names:

• parent / children (pro: parent is already used in Zope/Plone, con: possible name collisions with existing attributes)
• __parent__ / __children__ (pro: parent is already used in Zope/Plone, no name collisions, con: ugly?)
• container / items (cons: too generic? not used in Zope/Plone)
• container / contents (cons: not used in Zope/Plone)
• collection / member (from hydra) (pro: hydra is somehow a standard, cons: collection has another meaning in Plone, member is very generic)

[tisto]

Right now we use "member" from hydra:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld", 
  "@id": "http://localhost:55001/plone", 
  "@type": "Collection", 
  "member": [
    {
      "@id": "http://localhost:55001/plone/robot-test-folder", 
      "description": "", 
      "title": "Test Folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "description": "Congratulations! You have successfully installed Plone.", 
      "title": "Welcome to Plone"
    }
  ], 
  "parent": {}, 
  "portal_type": "SiteRoot"
}```

[lukasgraf]

@tisto is this decision still current?

I'm seeing some different approaches being used in the various docs, for example in searching.rst it's @items, and there's some collection+json examples as well.

I don't have any strong feelings towards either style, but it's something that probably needs to be agreed upon quite soon. Also, it's not like we can't ever change it again. For now, I'd like to resolve some contradictions in style in the current docs, and then start implementing things using whatever style is documented.

[tisto]

This issue is more meant to be a documentation of the current state than a final decision. @lrowe @bloodbare and me discussed this issue during PLOG, we did not reach a final conclusion though.

I tend to keep the hydra "member" and add a "parent" attribute, just because I don't see strong arguments for a certain option. I'm more than open for suggetions or a discussion...

[lukasgraf]

The only issue I see with member and parent is the name collisions you already pointed out in your first comment. We simply can't control what people name their fields, or what fields are named in an addon product they might be using. And the choices available to us in case of a collision aren't pretty:

• Fail hard, and have certain objects not be retrievable via API
• Overwrite the existing attribute in the output and introduce a rather subtle bug
• Have the attribute override our member attribute and omit collection members

Maybe we could handle collisions using one of these strategies:

• Automatically resolve name conflicts using a conflict resolution algorithm that makes the attribute name unique, and rename that attribute
• Or: Put a mechanism in place that allows integrators / developers to rename particular fields for serialization by providing a name mapping. Then fail hard in case of a conflict, and display a helpful message indicating that the conflict needs to be resolved by providing such a mapping for field x.

Either of these mechanisms would need to be applied on output as well as input though.

[ida]

+2 for __parent__ and __children__ The terms are my favorite because the words distinct the relation better than 'items' or 'container' e.g. do, and the underscores should be a pretty safe bet, concerning possible collisions.