Skip to content

0014 Reference links prefer a configurable field over canonical

Status

Accepted

Context

AnswerService::entityUrl() always linked a reference to the retrieved entity's own canonical URL. That's correct when the entity is the content — but retrieved entities can just as easily be a local copy of content sourced from elsewhere (imported, or crawled from an external site). In that case the canonical URL is this site's copy, not the URL a citation should actually point a visitor at.

Nothing on the entity or the retrieval path distinguishes "this content lives here" from "this content was copied from there": that distinction only exists per-agent, as a choice an administrator makes when setting up a given retrieval source.

Decision

Add an optional per-agent setting, source_url_field (form label "Source URL field name", AiAnswersAgentForm). When non-empty, entityUrl() reads that field's value off the retrieved entity first, and only falls back to canonical when the field isn't configured, isn't present on that entity, or is empty. The field's own value is trusted as-is (whatever the agent's retrieval source already put there) — entityUrl() does not validate that it looks like a URL.

entityUrl() wraps the field read in a try/catch: the setting is freeform text with no validation against field type or entity type, so an administrator can point it at a field whose main property isn't value (an entity reference, for example). That falls through to canonical exactly as if the field were empty, logged as a warning rather than propagating.

Consequences

  • No behavior change for any agent that leaves the setting blank — every agent configured before this feature existed keeps linking to canonical.
  • The reference link and the rendered excerpt (reference.rendered, in the configured view mode) are independent: setting source_url_field changes where the [n] citation and the Sources-list heading link to, but the excerpt's own content — including any "read more" link inside it — is whatever the view mode renders, unaffected by this setting.
  • The client always opens reference links in a new tab (target="_blank" rel="noopener noreferrer") rather than only when the URL is off-site, since the JS layer has no reliable way to tell canonical and configured-field URLs apart once it receives reference.url.