Make official the syntax entityType:serializedEntity for EntityReferences

Development
#21

I was thinking about reusing $services.model.serialize($ref, "typedHint") if proposal 3 decisions allows to have an EntityReferenceSerializer with a dedicated hint for serializing with the type. If it does not, I guess we’d need a dedicated method for that, maybe $services.model.serializeWithType or something with a better name.

#22

Even if it passes maybe we should have something like serializeWithType and resolveWithType to makes easier for someone to know which serialize is for which resolve.

#23

I understand the idea better now. We’re talking about a new string syntax to define a full entity reference (vs a partial string syntax without the type). That’s fine and logical.

The problem I still have is the mix of both under the same terminology “string serialization of an EntityReference”. Wherever we ask the user to enter a String that represents an EntityReference, what happens if they don’t prefix with the type.

More precisely what do you do when the user is asked to enter an entity reference as a string (in a macro parameter for ex), and doesn’t provide the type as a prefix? In link syntax we consider it’s a doc type but that works only if there’s no subwiki named doc. We cannot consider that we cannot have suwbikis named after all the Entity Type that exist.

I also understand that this will allow MacroParameters class to use private EntityReference er whereas it wasn’t possible before (BTW are we already doing that in some macros?). For example it would allow the {{include}} macro to be modified and instead of type and reference to have only a single reference parameter. But how do you convert to the new syntax? I guess you’ll need to introduce a new parameter other than `reference, no? Otherwise you have backward compat issues.

To answer the proposals:

  • Proposal 1: +1 if we solve the backward compatibility issues and clearly explain in the doc the 2 string syntaxes and when to use one over another and also solve proposal 3.
  • Proposal 2: Sounds good but what about the other existing resolve APIs for partial entity references. Are they still needed? Should they be deprecated and legacified? Same question than Thomas for the serialize API.
  • Proposal 3: I can see 3 options.
    • Option 1: we deprecate the current string representation of an ER and deprecate and legacy EntityReference resolve(T entityReferenceRepresentation, EntityType type, Object... parameters) and add a new EntityReference resolve(T entityReferenceRepresentation, Object... parameters) signature.
    • Option 2: we introduce a new component interface. This why where I find it a problem to have the 2 representations competing. Feels like a bad design to me.
    • Option 3: Wouldn’t EntityReference resolve(T entityReferenceRepresentation, Object... parameters) be good for both use cases, and parameters[0] would be considered the EntityType when passing the entity type as the second parameter in the call? Would that beak backward compatibility in Java?
#24

All the others are actually returning typed EntityReferences (e.g. DocumentReference) and are about other use cases (where you don’t have the type as part of the reference) so there is no reason to deprecated anything for me.

#25

Answering myself: yes it would break backward compatibility ofc: just imagine some code implementing EntityReferenceResolver and using the second parameter; if that param is removed the code will fail.