Feature Request: Link Metadata

[NeonReactionary]

Is Your Feature Request Related To A Problem? Please Describe.

With notes often having many branches to other notes in many different contexts, it can be difficult to relate data in a meaningful way, understand what relevance certain links may have had, or simply be lost in a glut of links.

Describe The Solution You'd Like

Some additional fields for link metadata. This could be useful if one wanted to expand the depth of a network, but filter for certain conceptual links across wider regions of the networks. In other words, this can be used to capture wider bodies of knowledge or research themes.

for example:
[[<link id>][<link title>][:tags <tag> :context <short description>]]

Describe Alternatives You've Considered

A link-note that contains all the information as a separate entity. This could be viewed as a pop-up by hovering over the link and provide additional context.

Additional Context

Links between notes are almost as important as the notes themselves. There should be some kind of additional features that reflect this.

[tefkah]

I think this is a great idea and one which I've also considered myself, and luckily react-force-graph has built in support for this kind of thing. The problem lies more in collecting that data, which org-roam does for us. If someone were to write a plugin for org-roam which adds this kind of information to the database we'd happily support this, but I don't see us doing this ourselves anytime soon. I'll convert this issue to a discussion as I'd be interested to hear what other think of this!

[tefkah]

Hmmm if this is compatible with how org-roam registers links I don't see why not!
By that I mean that it would register both id:12345 and customlink:12345 as links pointing to 12345, but I think that's the case.
Atm we only look for id and cite links, but it would be trivial to support all other types of links. At the moment we don't have a good system for changing the appearance for a certain type of link/node (it's all hardcoded) so that would first need to change.

[odomanov]

In Org-roam v2 I do something like

(org-link-set-parameters "customlink"
                         :follow 'org-id-open
                         :export 'org-roam-export-link-customlink
                         :face 'org-roam-link-customlink)

In this way following the customlink: is the same as following id:. And I can adjust custom faces.

The problem is that although Org-roam stores link types, it doesn't use them. This means that 1) you need to insert them manually and 2) they are not shown as backlinks. This requires changes in Org-roam, which are minor, but I don't know if Jethro will make them. I actually use a fork.

[shunlog]

hey @odomanov, have you settled with this method for link metadata or the one you described below (with a new syntax)?

[odomanov]

At the moment I use the fork I mentioned below (https://github.com/odomanov/org-roam-ui). I'm open to a better solution, though -- preferably something in the vanilla org.

[shunlog]

@odomanov Sorry I'm not able to try out your fork, but it's really cool that you implemented filtering for link metadata. As for a native org solution, @jethrokuan proposed one here and made a point here that new syntax should not be added (especially if it's not at the org-mode level, i imagine). It would be great if you could adjust your implementation of filtering "LinkTags" so that it filters by link type and make a pull request.

[odomanov]

I looked at this and this seems to be not that difficult. We need 2 advices:

;;;  Link properties (for 'id' links only).
;;;  Adapted from https://linevi.ch/en/org-link-extra-attrs.html

(defun odm/org-link-extra-attrs (orig-fun &rest args)
  "Post processor for parsing links"
  (setq parser-result orig-fun)

  ;;; Retrieving inital values that should be replaced
  (setq raw-path (plist-get (nth 1 parser-result) :raw-link))

  ;; Checking if link match the regular expression
  (if (string-match-p "^id:.*|\s*:" raw-path)
      (progn
	;; Retrieving parameters after the vertical bar
	(setq results (s-split "|" raw-path))
	(setq raw-path (car results))
	(setq path (s-chop-prefix "id:" raw-path))

        ;; Cleaning, splitting and making symbols
        (setq results (s-split "\s" (s-trim (s-collapse-whitespace
                                             (car (-slice results 1))))))
        (setq results (--map (intern it) results))

	;; Updating the ouput with the new values
	(setq orig-fun-cleaned (plist-put (nth 1 orig-fun) :raw-link raw-path))
	(setq orig-fun-cleaned (plist-put orig-fun-cleaned :path path))

        ;; Check that the number is even
        (if (= 2 (length (-last-item (-partition-all 2 results))))
            (list 'link (-snoc orig-fun-cleaned :extra-attrs results))
          (progn
            (message "Links properties are incorrect.")
            (list 'link orig-fun-cleaned))))

    ;; Or returning original value of the function
    orig-fun))

(advice-add 'org-element-link-parser :filter-return #'odm/org-link-extra-attrs)

(defun odm/org-roam-db-extra-properties (link)
  "Append extra-attrs to the LINK's properties."
  (save-excursion
    (goto-char (org-element-property :begin link))
    (let ((path (org-element-property :path link))
          (source (org-roam-id-at-point))
          (extra-attrs (org-element-property :extra-attrs link)))
      (when extra-attrs
        (setq properties (caar (org-roam-db-query
                               [:select properties :from links
                                        :where (= source $s1) :and (= dest $s2)
                                        :limit 1]
                               source path)))
        (setq properties (append properties extra-attrs))
        (when (and source path)
          (org-roam-db-query
           [:update links :set (= properties $s3)
                    :where (= source $s1) :and (= dest $s2)]
           source path properties))))))

(advice-add 'org-roam-db-insert-link :after #'odm/org-roam-db-extra-properties)

This adds a new syntax for links (backward compatible) and allows us to add link properties which are stored in the database.

The syntax is:
[[<link id>|:tags <tag> :context <short description>][<link title>]]

Does this look promising?

[9s-l-s9]

Okay, I agree, that compatibility with the existing link format is important.
The org-transclusion solution looks really great and shows, that is a problem others are facing as well. If org-roam adapts the same syntax, it might become part of the official org syntax (?).

Next step would be to change the org-roam parser (and database schema) or write a plugin. Anything else we should consider?

[shunlog]

#+KEYWORD: [[file:path/to/file.org::*Headline][description]] :parameter value

the link above should be clickable in existing org parsers

It's not clickable though. Did you mean this, @lytex ?

#+KEYWORD: :parameter value
[[file:path/to/file.org::*Headline][description]] 

Also, is it possible to achieve inline links with this approach? As in, links inside text rather than on a new line.

[shunlog]

Lemme see if I understood correctly. This approach requires no intervention in the org format and is backwards compatible with existing parsers (the link metadata isn't parsed but at least the link remains readable) but only works for links that are on their own line. To implement this we only need to (1) modify org-roam so that it recognizes some keyword (e.g. #+KEYWORD) and treats its properties (e.g. :parameter value) as properties of links and (2) modify org-roam-ui so that you can filter and color links according to their properties and stuff like that, right?

[9s-l-s9]

Lemme see if I understood correctly. This approach requires no intervention in the org format and is backwards compatible with existing parsers (the link metadata isn't parsed but at least the link remains readable) but only works for links that are on their own line. To implement this we only need to (1) modify org-roam so that it recognizes some keyword (e.g. #+KEYWORD) and treats its properties (e.g. :parameter value) as properties of links and (2) modify org-roam-ui so that you can filter and color links according to their properties and stuff like that, right?

This is what understood as well... we should open an issue over at org-roam.

[lytex]

#+KEYWORD: [[file:path/to/file.org::*Headline][description]] :parameter value

the link above should be clickable in existing org parsers

It's not clickable though.

Well, it's clickable in orgzly but not in logseq, because the #+KEYWORD: VALUE is hidden in logseq. Hopefully it's only a matter of tweaking some visibility settings, since if you add some letter before (like this a#+KEYWORD: VALUE) the link is clickable again. I'm not an expert in logseq though, so I cannot say which specific setting would have to be tweaked.

However if it's not supported, a link following this syntax should be easier to implement than the [[<link id>|:tags <tag> :context <short description>][<link title>]] syntax, in principle

[lytex]

I was informed that my issue #132 is a duplicate of this discussion, however I'd like to compare the two proposed implementations as they are quite different and have their pros and cons.

Property Drawer links

I'm modifying my implementation proposal relative to when I opened the issue. In the meantime I discovered org-edna which allows to define tasks dependencies for tasks which are not direct descendants of each other, defining new property drawers such as :BLOCKER: and :TRIGGER:. If org-roam-ui follows this design then it would have task management "for free", and the user could as well define any type of property drawers as long as they don't clash with an existing org-mode or org-roam property drawer, for example :MANAGER: to define a corporate hierarchy.
They wouldn't show as org-roam backlinks as links in a property drawer aren't considered such by org-mode.

I think would be a pretty interesting addition to org-roam-ui, as one of the most important use cases of seeing a graph of new types of links are task dependencies.

The syntax would be:

:TRIGGER: ids("id:3d851f71-915c-465b-8936-67ec8cea63c0" "id:3d851f71-915c-465b-8936-67ec8cea63c0") todo!(TODO)

Several ids are allowed for a given link

One disadvantage though is that links are only allowed as part of a heading, and only in a property drawer. Using links with extra attributes allows you to add context between two or more links, and how they relate to each other.

Another disadvantage is that org-edna has more type of links than id-based and full compatibility would have to implement all these type of links, some being non-standard (for example olp("test.org" "path/to/heading"), next-sibling, ...). However since org-roam is moving from file links to id links I think focusing on id-links alone would provide a lot of value.

Maybe this is out of scope for a org-roam-ui (more appropiate perhaps for "org-edna-ui"), but it's a tempting opportunity nonetheless.

For further info on org-edna and graphs see Karl Voit's post