Skip to content

spec: notify link placeholders - {recordUrl}, {inboxUrl}, {appUrl} - #22

Open
delchev wants to merge 1 commit into
mainfrom
spec/notify-deep-links
Open

spec: notify link placeholders - {recordUrl}, {inboxUrl}, {appUrl}#22
delchev wants to merge 1 commit into
mainfrom
spec/notify-deep-links

Conversation

@delchev

@delchev delchev commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Problem

A notification that cannot be acted on is a notification that gets ignored. The notify block interpolates fields into subject / body, but nothing in the specification lets a message carry the way back into the application — so "you have an approval waiting" arrives with no way to approve.

Nothing stops an author from pasting a route into the body, and that is the trap: the routes belong to whatever renders the application, so an intent that names one encodes a layout it does not own — correct only until that layout changes, and silently wrong afterwards.

Change

versions/1.2.md, a new subsection under The notify blockLinks back to the application: {recordUrl}, {inboxUrl}, {appUrl}:

Placeholder Resolves to
{recordUrl} the record the message is about, opened in the application
{inboxUrl} the recipient's task inbox
{appUrl} the application's external base URL — the origin only

Normative rules:

  • The three names are reserved at every notify call site; an entity field of the same name MUST NOT shadow them.
  • {recordUrl} and {inboxUrl} MUST be resolved by the implementation to a complete address. An intent MUST NOT be required to spell a route, and a conforming implementation MUST NOT require one. {appUrl} yields the origin alone — the escape hatch, with everything appended to it authored text.
  • Inside a forEach fan-out {recordUrl} links the ROW, like every other bare path in the block; the anchor record stays addressable for values only.

Appendix A gains the index row.

Reference implementation

eclipse-dirigible/dirigible#6744 — the resolver emits a bare identifier and reports the use, the model layer contributes only the entity and its key, and the code generator composes the address. That split is what the normative "an intent MUST NOT be required to spell a route" describes in practice.

Note the base {appUrl} origin token was never written up here (it shipped in the reference implementation as eclipse-dirigible/dirigible#6642), so this PR introduces the whole family rather than only the two new names.

A notification that cannot be acted on gets ignored, and the notify block had no
way to carry the way back into the application: an author could only paste a
route into the body - the layout the intent does not own, correct until whatever
renders the application changes it.

Add the three reserved link placeholders to the notify block: {recordUrl} (the
record the message is about), {inboxUrl} (the recipient's task inbox) and
{appUrl} (the origin alone). Normative: the names are reserved at every call
site and MUST NOT be shadowed by an entity field; the first two MUST be resolved
by the implementation to a complete address, and an intent MUST NOT be required
to spell a route. Inside a forEach fan-out {recordUrl} links the ROW, like every
other bare path in the block.

Appendix A gains its index row.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant