Meeting № 33 Summary

[devhelpr]

Meeting № 33 Summary

full transcription
recording

• Page Node Extension
  The group discussed the addition of a page node extension in the spec, which includes optional properties like page number (starting at one following ISO standards) and a page label (distinct from a title). This extension allows pages to function as nodes in the canvas, supporting positioning and grouping relationships. Clarifications were made regarding the use of labels versus titles in UI contexts.

• Transclusion Motivation and Concept
  Transclusion was introduced as a way to allow a node (B) to be used as a resource in another node (A), effectively supporting multiple appearances of complex node hierarchies on the canvas. The concept is motivated by real-world use cases (e.g., knowledge management apps like Notion) where duplicated content needs to stay synchronized across different locations.

• Transclusion Semantics and Implementation Details
  The discussion covered how transclusion merges node properties, with node A’s properties overriding node B’s on a resulting "merged" node A'. They also discussed the necessity to replicate child nodes of transcluded nodes to maintain unique identities and positions on the canvas, making transclusion more complex than simple parent-child merging.

• Resource and ID Naming Conventions
  They evaluated resource addressing within the spec, where nodes are implicitly available as resources using their IDs prefixed with a pound sign (#). The participants recommended explicitly disallowing certain characters in IDs, especially prohibiting IDs that start with a hash mark to avoid conflicts and ambiguity.

• MIME Type for Nodes
  The group discussed that a standalone node (as a fragment) is not a valid OKF file and debated introducing a new MIME type such as application/okf-node+json to distinguish node data from full OKF files to support tooling and validation.

• Comparison Between Transclusion and File Inclusion
  They compared transclusion (node-based inclusion) with the alternative of importing separate OKF files. It was noted that while both are similar in semantics, transclusion might be preferred for simplifying authoring in single files, whereas file inclusion allows sharing across multiple OKF files. The discussion also included whether both approaches are necessary or if one should be preferred.

• Handling of Relations in Transclusion
  The group acknowledged the open question of how to handle relations tied to transcluded nodes, especially when nodes get duplicated. They considered implications of sets and relations when nodes are replicated through transclusion.

• Groups and Transclusion
  They debated whether groups (which are relations rather than nodes) can or should be transcluded. The consensus was currently to restrict transclusion to nodes and their parent-child hierarchies, excluding groups, to avoid complexity.

• Potential Export and Fallback Mechanisms
  The working group highlighted that if canvases or applications do not support transclusion, then converting transcluded nodes into duplicates upon export is an acceptable fallback, allowing graceful degradation of features.

---

Action Items

• Create or update the PR to finalize the page node extension in the spec.
• Add explicit notes to the spec clarifying that the implicit resource for a node does not appear in the resources array.
• Define and document naming restrictions for node IDs, explicitly banning leading # characters.
• Introduce a new MIME type for standalone nodes, such as application/okf-node+json.
• Expand the transclusion section with clear semantics for node merging and child node replication.
• Clarify how relations of transcluded nodes should be handled or document this as an open issue.
• Schedule next working group meeting in approximately two weeks to continue discussions and finalize 0.5.1 version release including transclusion.
• Consider adding a motivation section or link to design decisions explaining transclusion’s purpose in the spec or related documentation.

---

Takeaways

• The page node extension is mostly straightforward and aligns well with existing conventions.
• Transclusion is a powerful and complex feature that can potentially enable node reuse and synchronized editing across the canvas.
• There is a strong parallel between transclusion and importing separate OKF files, implying a convergence in semantics that should be leveraged.
• Parent-child relations are currently the preferred way to represent "belonging together" in transclusion rather than groups.
• The specification must balance conceptual simplicity with expressive power and support fallback mechanisms for broader compatibility.
• Careful syntax and structural restrictions (IDs, MIME types) are necessary to avoid ambiguity in references and tooling support.
• The working group values thorough design with an eye on implementation complexity and interoperability trade-offs.