In some cases, it can be useful to treat sub-structures of entities as entities in their own right (so called sub-entities). This allows them to use the editing APIs already present for entities, allows them to be referenced as entities, etc. This was identified as the preferred strategy to enable T159703: [Tracking] Support for Forms and Senses (2017-05-15, meeting notes).

This ticket acts as an overview of the tasks necessary to support such sub-entities.

• Structured IDs (we will use the hyphen as a separator, as in L768234-F7)
  • Introduce HierarchicalEntityId interface, defining a getParentId() method, maybe also a getSubId() method. Note that the parent ID is an EntityId, but the sub ID is not. The sub ID could be represented as a plain string, or we could introduce a new class. We may however not need it at all, see below.
• Transparent lookup of sub-entities
  • Introduce a SubEntityContainer interface, with methods getSubEntity and setSubEntity.
  • Introduce an EntityRevisionLookup wrapper implementation, implementing the following algorithm for resolving hierarchical IDs:
    • For a hierarchical ID, get the parent ID and load the parent Entity using that ID.
    • The parent entity must implement SubEntityContainer. Ask it for the sub-entity with the desiered (sub) ID, and return it.
  • TBD: Asking for a sub-entity may be done with the full EntityId of the sub-entity, or just the sub-part.
  • Note that parent entities and sub-entities share the same revision IDs!
• Transparent storage of sub-entities
  • Introduce an EntityStore wrapper implementation, implementing the following algorithm for resolving hierarchical IDs:
    • For a hierarchical ID, get the parent ID and load the parent Entity using that ID.
    • The parent entity must implement SubEntityContainer. Set the new sub-entity onm the parent entity.
    • Store the modified parent entity
  • TBD: can sub-entities be added to parent entities that do not yet have an ID?
  • TBD: can sub-entities have an ID set before they can be added?
  • TBD: the parent entity needs to maintain an ID counter for each kind of sub-entity
• Make parent entities implement SubEntityContainer
• Make IDs of sub-entities implement HierarchicalEntityId
• The parent entity's EntityHandler should extract and expose secondary data from the sub-entities, particularly entries in wb_terms.
  • Note: wb_terms only supports hierarchical IDs after T159851: Add a column for full entity ID to wb_terms table is one
  • TBD: how to tell Cirrus that from a single edit, information about multiple "documents" is updated.
• TBD: maybe introduce a ChangeOp for updating sub-entities. This is needed for full round-trip support for the EditEntity API, but no particular use case is known.
• Define sub-entities in wikibase.entitytypes.php. In particular:
  • define serializer/deserializer
  • define EntityRdfBuilder
  • define ChangeOp deserializers
  • however, do NOT defined a content model or EntityHandler
  • TBD: define the view factory here, or hard code it in the parent's view.