Node properties vs references confusion

[bwaidelich]

The difference of q(node).property("reference") vs node.properties.reference causes confusion.

In todays weekly we discussed some potential ways to improve the DX:

• Introduce Deprecation Log
  • This might be a good idea in general but in this specific case we could use it to log usages of q(node).property("<reference-name>").
    One alternative would be to throw an exception in this case – but that is rather flaky in Fusion land
• Throw exception when trying to access references via properties through PHP API
  • $node->getProperty("reference") currently returns null but we could also throw an exception that explains how to use FindReferences instead
• Deprecated/Remove reference(s) property type in NodeType schema (see below)
• NodeType::getProperties would need to split up in NodeType::getReferences

References are no properties with Neos 9.
This is easy to communicate, but it makes "reference properties" even weirder, so we should strive to replace:

'Some.Package:SomeNodeType':
  properties:
    'text':
      type: string
   'someReference':
      type: reference
          properties:
            'foo':
              type: string

with

'Some.Package:SomeNodeType':
  properties:
    'text':
      type: string
  references:
   'someReference':
        properties:
          'foo':
            type: string

[ahaeslich]

I just found a new issue: #4981
Can we regard it as follow up and close this one?

[mhsdesign]

Yes this can be considered closed via #4677 at least point 3 & 4 are solved.

About criteria 1 & 2 im not sure and i would like to reconsider them but for simplicity ill move them over to #4981