w3id.org

Appearance

htaccess/github-raw-target ​

Severity: warning · Status: enforced · Applies to: ids/**/.htaccess

What ​

When redirecting to a file hosted on GitHub:

  • use raw.githubusercontent.com, not github.com/.../blob/..., unless the target is documentation for people to read;
  • do not include a refs/heads/ path segment.

Why ​

/blob/ serves a web page, not a file.https://github.com/user/repo/blob/main/vocab.ttl returns an HTML document with syntax highlighting, navigation, and a comment box. A triple store fetching your ontology IRI gets that HTML and fails to parse it. The redirect looks right, the URL opens fine in a browser, and every machine client breaks. More than a hundred rules in this repository still do this.

The raw equivalent — https://raw.githubusercontent.com/user/repo/main/vocab.ttl — returns the file itself.

refs/heads/ is redundant. GitHub's web interface sometimes produces raw URLs containing refs/heads/main. These work today, but the extra segment is an implementation detail of GitHub's routing rather than a documented URL shape, and it makes the target harder to read.

Wrong ​

apache
RewriteRule ^vocab\.ttl$ https://github.com/user/repo/blob/main/vocab.ttl [R=303,L]
RewriteRule ^vocab\.ttl$ https://raw.githubusercontent.com/user/repo/refs/heads/main/vocab.ttl [R=303,L]
apache
# pinned to a release tag -- stable
RewriteRule ^vocab\.ttl$ https://raw.githubusercontent.com/user/repo/v1.2.0/vocab.ttl [R=303,L]

Or, if you deliberately want "whatever is current":

apache
RewriteRule ^vocab\.ttl$ https://raw.githubusercontent.com/user/repo/main/vocab.ttl [R=303,L]

How to fix ​

Convert a blob URL to a raw one:

https://github.com/user/repo/blob/main/path/vocab.ttl
https://raw.githubusercontent.com/user/repo/main/path/vocab.ttl

Then verify what actually comes back:

sh
curl -sIL https://raw.githubusercontent.com/user/repo/main/vocab.ttl \
  | grep -iE '^(HTTP|content-type)'

Three things this rule deliberately does not tell you to do.

Documentation is the exception. A /blob/ link to Markdown, or another format GitHub renders as a page, is not reported. That page is for people, and the raw file is text/plain markup. A common shape sends RDF clients to the raw vocabulary and everyone else to its rendered documentation:

apache
RewriteCond %{HTTP_ACCEPT} text/turtle
RewriteRule ^core$ https://raw.githubusercontent.com/user/repo/main/core.ttl [R=303,L]
RewriteRule ^core$ https://github.com/user/repo/blob/main/docs/core.md [R=303,L]

Branch names move, and a tag does not — but a branch target is the right answer when you want whatever is current, so preferring a tag is advice rather than a rule, and is not reported.

GitHub Pages is often a better target than raw files at all.raw.githubusercontent.com serves everything as text/plain, so a correctly negotiated request for text/turtle still arrives with the wrong content type and some clients reject it. With Pages you control the content type and get a real hostname you can move later without touching this repository.

How to check ​

Run w3id-check with --rule htaccess/github-raw-target to check this rule on its own; without it the tool runs every rule, as the pull request checks do.

sh
node tools/check/bin/w3id-check.js --rule htaccess/github-raw-target ids/my-project

Testing your changes covers installing the tool, and what else is worth checking by hand.

See also ​