The finding
A plugin taking a graph, class or property IRI as a free-form string parameter
naturally validates it with validators.url(). That rejects every scheme which
is not a URL, including urn: - and urn:example:data or urn:uuid:... is an
ordinary way to name a knowledge graph. The parameter then refuses a graph the
store itself handles without complaint; importing into and querying a urn:
named graph works.
The trap is quiet. The check looks obviously right, the resulting message is a
generic "Invalid value for parameter ...", and nothing tells the user that the
scheme is what was rejected.
Why this generalises
Any plugin that accepts an IRI a user types rather than picks. GraphParameterType
covers the autocompleted case, but ignore lists, target graph names and
class/property filters are usually validated by hand, and validators.url is the
obvious import to reach for.
Which part of the template
src/{{ '.claude' }}/skills/{% if project_type == 'plugin' %}plugin-implementation{% endif %}/SKILL.md,
the parameters section.
Suggested change
A short note that a knowledge graph IRI is not necessarily a URL, and that a
plugin validating one itself should accept a URN as well - with a minimal
pattern for the RFC 8141 namespace identifier (alphanumeric first character, two
to thirty-two characters, non-empty namespace specific string).
Environment
Template version: v9.7.0
project_type: plugin
github_page answered: yes
pypi answered: yes
The finding
A plugin taking a graph, class or property IRI as a free-form string parameter
naturally validates it with
validators.url(). That rejects every scheme whichis not a URL, including
urn:- andurn:example:dataorurn:uuid:...is anordinary way to name a knowledge graph. The parameter then refuses a graph the
store itself handles without complaint; importing into and querying a
urn:named graph works.
The trap is quiet. The check looks obviously right, the resulting message is a
generic "Invalid value for parameter ...", and nothing tells the user that the
scheme is what was rejected.
Why this generalises
Any plugin that accepts an IRI a user types rather than picks.
GraphParameterTypecovers the autocompleted case, but ignore lists, target graph names and
class/property filters are usually validated by hand, and
validators.urlis theobvious import to reach for.
Which part of the template
src/{{ '.claude' }}/skills/{% if project_type == 'plugin' %}plugin-implementation{% endif %}/SKILL.md,the parameters section.
Suggested change
A short note that a knowledge graph IRI is not necessarily a URL, and that a
plugin validating one itself should accept a URN as well - with a minimal
pattern for the RFC 8141 namespace identifier (alphanumeric first character, two
to thirty-two characters, non-empty namespace specific string).
Environment
Template version: v9.7.0
project_type: plugin
github_page answered: yes
pypi answered: yes