Suggestion: add authoritative documentation for borrowed vocabulary to each of those terms

[sannegovaert]

The recent fix (see #275) added a working link to the authoritative documents in the "2 Burrowed Vocabulary" section — thank you @baskaufs — but that link is hard to find. Most readers search for specific terms (CTRL‑F) and may miss the section-level reference.

Problem

• Some terms still use Adobe links as identifiers that no longer work as clickable references.
• The authoritative sources are only linked at the section level, not per term, so readers who jump to a term may not see the source or identifier.

Proposal for each burrowed term:

Add a direct, working external link to the authoritative definition/document immediately adjacent to the term (for example, make the term itself linkable or add a small inline external link).

[baskaufs]

@sannegovaert Thanks for this very helpful feedback.

The complication is that the metadata about each term is built by script, using data from CSV tables stored in GitHub. So individual term metadata records can't just be edited manually. The code where the term IRI value is generated is here:

ac/code/build-webpages.py

Line 303 in 97107f5

text += '\t\t\t<td><a href="%s">%s</a></td>\n' % (uri, uri)

. What may be a good solution would be to put in an IF clause when the HTML is generated that would not hyperlink the term IRI if it fell into one of the namespaces that do not dereference to individual term definitions. That would prevent people from thinking that something should happen when they click on the link; there would be no link. One could then add the link to where the source definition could be found to the notes in the term metadata.

I think it may be that all of the source definitions are buried inside PDF documents. So it may not be possible to link directly to the individual definition -- only to the entire document. Someone will need to investigate this further. Unfortunately that is outside the control of TDWG and is up to Adobe.

I am going to tag this for maintenance so it can be fixed the next time somebody is working on the code that generates the list of terms. I believe that adding the clarifying information to the notes would not require any official public comment or executive approval, so I think the AC Maintenance Group could just decide to do it in the next release. So I've also tagged it as a term proposal. I will ping @edwbaker here so that the MG can attend to this at an upcoming meeting.

[edwbaker]

This was discussed at the MG meeting on 21/01/2026.

While these URLs do not dereference, we can add the following to the term definitions (being mindful of the RDF build):
"URLs in this namespace do not dereference, but authoritative documentation is at <link.pdf>" and remove the hypertext links.

[baskaufs]

For reference, here's the code that generates the hyperlinks from URLs:

ac/code/build-webpages.py

Line 127 in 97107f5

def convert_link(text_with_urls):

So it's basically as you suggested, @edwbaker . It uses regex to find the HTTP(S) strings, and generates the HTML for a link around the string. So that's why linking can only be done on URLs and not on hyperlinked plain text.

[baskaufs]

For the Iptc4xmpExt: namespace, <link.pdf> is https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata-201007_1.pdf There are internal hyperlinks to terms, but I can't see how to access them via the URL

For the exif: namespace, <link.pdf> is https://www.cipa.jp/std/documents/e/DC-008-2012_E.pdf Also has internal hyperlinks but can't access via URL.

For the xmp: namespace, I found the raw file link. It's https://raw.githubusercontent.com/adobe/XMP-Toolkit-SDK/main/docs/XMPSpecificationPart1.pdf . In my browser, the Acrobat extension opened it with a side navigation menu, so there appears to be internal anchors, but I don't know how to access them with a URL.

The xmpRights: namespace terms are also defined in the same document.

The photoshop: namespace term is defined in https://raw.githubusercontent.com/adobe/XMP-Toolkit-SDK/main/docs/XMPSpecificationPart2.pdf same issue with internal hyperlinks

The mo: Music Ontology terms used to dereference but didn't for me today. We should look into this.

The dc: and dcterms: terms dereference OK, as do the dwc: ones, so we are OK there.

[baskaufs]

Implementation note: @edwbaker's suggestion was to add the statement to the definition. Given that both term definitions and usage directives are normative. I'm adding the statement to the notes, which are non-normative.

[baskaufs]

The links to defining PDFs have been added to the notes for all terms with non-dereferenceable IRIs. However, the build script has not yet been modified to remove hyperlinking of those IRIs.