diff --git a/example/.htaccess b/example/.htaccess index 17b1c8b62..4b3141131 100644 --- a/example/.htaccess +++ b/example/.htaccess @@ -1,74 +1,13 @@ -# Turn off MultiViews -Options -MultiViews - -# Directive to ensure *.rdf files served as appropriate content type, -# if not present in main apache config -AddType application/rdf+xml .rdf -AddType application/rdf+xml .owl -AddType text/turtle .ttl -AddType application/n-triples .n3 -AddType application/ld+json .json +# Example +# +# https://w3id.org/example redirects to https://example.com/ +# +# ## Contact +# This space is administered by: +# +# David I. Lehn +# dil@lehn.org +# GitHub username: davidlehn RewriteEngine on - -# Rewrite rule for latest version. -RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+xml) -RewriteCond %{HTTP_ACCEPT} text/html [OR] -RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR] -RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.* -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/index-en.html [R=303,L] - -# Rewrite rule to serve JSON-LD content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} application/ld\+json -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.json [R=303,L] - -# Rewrite rule to serve RDF/XML content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} \*/\* [OR] -RewriteCond %{HTTP_ACCEPT} application/rdf\+xml -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.owl [R=303,L] - -# Rewrite rule to serve N-Triples content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} application/n-triples -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.nt [R=303,L] - -# Rewrite rule to serve TTL content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} text/turtle [OR] -RewriteCond %{HTTP_ACCEPT} text/\* [OR] -RewriteCond %{HTTP_ACCEPT} \*/turtle -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.ttl [R=303,L] - - -# Rewrite rules for any other version. -RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+xml) -RewriteCond %{HTTP_ACCEPT} text/html [OR] -RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR] -RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.* -RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/index-en.html [R=303,L] - -# Rewrite rule to serve JSON-LD content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} application/ld\+json -RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.json [R=303,L] - -# Rewrite rule to serve RDF/XML content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} \*/\* [OR] -RewriteCond %{HTTP_ACCEPT} application/rdf\+xml -RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.owl [R=303,L] - -# Rewrite rule to serve N-Triples content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} application/n-triples -RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.nt [R=303,L] - -# Rewrite rule to serve TTL content from the vocabulary URI if requested -RewriteCond %{HTTP_ACCEPT} text/turtle [OR] -RewriteCond %{HTTP_ACCEPT} text/\* [OR] -RewriteCond %{HTTP_ACCEPT} \*/turtle -RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.ttl [R=303,L] - - - -RewriteCond %{HTTP_ACCEPT} .+ -RewriteRule ^(.*)$ https://dgarijo.github.io/example/release/1.0.1/406.html [R=406,L] -# Default response -# --------------------------- -# Rewrite rule to serve the RDF/XML content from the vocabulary URI by default -RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.owl [R=303,L] +RewriteRule ^ https://example.com/ [R=302,L] diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..dd6bcb29a --- /dev/null +++ b/examples/README.md @@ -0,0 +1,190 @@ +# Examples + +This permanent w3id is meant to be a place to host examples for publishing things on w3id.org. + +* [.htaccess](#htaccess) + * [What is .htaccess?](#what-is-htaccess) + * [Put ID info and maintainer info inside .htaccess](#put-id-info-and-maintainer-info-inside-htaccess) + * [Quick intro to URL writing rules](#quick-intro-to-url-rewriting-rules) + * [Example 1: Minimalist (grouping)](#example-1-minimalist-grouping) + * [Example 2: Supporting multiple media types (MIME types)](#example-2-supporting-multiple-media-types-mime-types) + * [Example 3: Dealing with query string](#example-3-dealing-with-query-string) +* [README.md](#readmemd) +* [Publish vocabularies with W3ID](#publish-vocabularies-with-w3id) + +## .htaccess + +`.htaccess` file is the key for the working of URL redirection service of W3ID. Without it, redirection cannot be done. + +### What is `.htaccess?` + +From [Wikipedia](https://en.wikipedia.org/wiki/.htaccess): +> An .htaccess (hypertext access) file is a directory-level configuration file +supported by several web servers, used for configuration of website-access +issues, such as URL redirection, URL shortening, access control (for different +web pages and files), and more. The 'dot' (period or full stop) before the +file name makes it a hidden file in Unix-based environments. + +In W3ID context, it is used primarily for URL redirection. The `.htaccess` file is where you can put URL rewriting rules in. A set of URL rewriting rules will work together and effectively made URL +redirection happen. + +### Put ID info and maintainer info inside .htaccess + +You are encouraged to put a breif ID info and a maintainer info in the comment +(lines staring with `#` character) of a `.htaccess` file. + +```ApacheConf +# Example +# +# https://w3id.org/example redirects to https://example.com/ +# +# ## Contact +# This space is administered by: +# +# Firstname Secondname +# email@example.com +# GitHub username: xxx + +RewriteEngine on +RewriteRule ^ https://example.com/ [R=302,L] +``` + +### Quick intro to URL rewriting rules + +A simple `.htaccess` file for URL redirection can look like this: +```ApacheConf +RewriteEngine on +RewriteRule ^ https://example.com/ [R=302,L] +``` + +`RewriteEngine on` in the first line tells the web server to turn URL rewriting engine on. + +While the second line, starting with `RewriteRule`, is the actual rewriting rule. + +This is the syntax of the *RewriteRule* directive: +```ApacheConf +RewriteRule Pattern Substitution [Flag1,Flag2,Flag3] +``` + +* *Pattern* is a Perl compatible regular expression, which means you can specify a sequence of characters to match pattern in the URL. + * For example, `^` matches the beginning of the text, `$` matches the end of the text, `.` matches any single character ("a", "7", or any character, one time), and `*` repeats the previous match zero or more times (so `.*` matches "a", "7", "xyz42", and an empty string). + * What this Pattern is compared against varies depending on where the RewriteRule directive is defined. In W3ID context, where a per-directory `.htaccess` is used, if the full requested URL is `https://w3id.org/example/subdir/file.html`, the text to be compared against will be `subdir/file.html`. +* *Substitution* is the string that replaces the text that was matched by Pattern. It can be part of the URL (URL-path) to be combined with the hostname later or it can be a full URL (absolute URL). + * In W3ID context, the Substitution tends to be an absolute URL to an external (non w3id.org) resource. +* *Flags* set [special actions](https://httpd.apache.org/docs/current/rewrite/flags.html) to be performed. Flags is a comma-separated list, surround by square brackets. They are optional. Common flags include `R` (redirect), `L` (last, stop processing the rule set), and `NE` (no character escape). + +So in our first example: +```ApacheConf +RewriteRule ^ https://example.com/ [R=302,L] +``` +It means: +* *Pattern:* `^` -- if a beginning of a string is found in the requested URL (it will always find, as every string must have a beginning): +* *Substitution:* `https://example.com/` -- replace the whole URL with https://example.com/ +* *Flag1:* `R=302` -- issue a HTTP redirect, with [status code 302](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes), to the client +* *Flag2:* `L` -- stop processing the rule set + +You can have more than one *RewriteRule* in a single `.htaccess` file. + +See [Apache HTTP Server documentation](https://httpd.apache.org/docs/current/rewrite/intro.html) for more details about *RewriteRule*, regular expressions, and other directives. + +### Example 1: Minimalist (grouping) + +This 3 lines of code from [/mircat/.htaccess](https://github.com/perma-id/w3id.org/blob/master/mircat/.htaccess) redirects `https://w3id.org/mircat/` to `https://fairsharing.github.io/mircat/`. + +The URL rewriting rule for that is: +```ApacheConf +RewriteRule ^(.*)$ https://fairsharing.github.io/mircat/$1 [R=302,L] +``` + +A sequence of characters matches inside a pair of parentheses, or "grouping", will be put in a computer memory and can be recalled by using a special character `$` followed with a group number (`$1`, `$2`, `$15`). A group number is starting from one. + +So in the example above, every characters between the beginning of the string (`^`) and the end of the string (`$`) will be stored in group one and can be recalled by a character sequence `$1`. + +If the request URL is `https://w3id.org/mircat/subdir/`, the *Pattern* `^(.*)$` will matched with the whole `subdir/`. As `.*` is inside parentheses, `subdir/` will be stored in group one. + +When the *Substitution* `https://fairsharing.github.io/mircat/$1` is evaluated, `$1` will be replaced by `subdir/`, resulting a string `https://fairsharing.github.io/mircat/subdir`. This final string will be used for the redirection. + + +### Example 2: Supporting multiple media types (MIME types) + +A web server can be configured to return different media type or file format depends on the client's request or capability. + +[/ppop/.htaccess](https://github.com/perma-id/w3id.org/blob/master/ppop/.htaccess) demonstrates the use of `RewriteCond %{HTTP_ACCEPT}` to check which [media types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_Types) the client accepts or expects to be returned by the server. + +A simplified version of the URL rewriting rules in that file will look like this: +```ApacheConf +AddType text/turtle .ttl + +RewriteEngine on + +# Rewrite rule to serve HTML content +RewriteCond %{HTTP_ACCEPT} text/html +RewriteRule ^$ https://protect.oeg.fi.upm.es/ppop/ppop.html [R=303,L] + +# Rewrite rule to serve TTL content +RewriteCond %{HTTP_ACCEPT} text/turtle +RewriteRule ^$ https://protect.oeg.fi.upm.es/ppop/ppop.ttl [R=303,L] +``` + +The rule set utilizes the *RewriteCond* directive, which "defines a rule condition. One or more RewriteCond can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met" ([Apache HTTP Server documentation](https://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewritecond)). + +The above example will have this behavior: +* If `%{HTTP_ACCEPT}` matches `text/html`, the server will return an HTML document (`ppop.html`) +* If `%{HTTP_ACCEPT}` matches `text/turtle`, the server will return a Turtle document (`ppop.ttl`) + +The syntax of `RewriteCond` directive is: +```ApacheConf +RewriteCond TestString CondPattern [Flags] +``` + +Where *CondPattern* is a regular expresssion to match pattern in *TestString*. + +In this case, *TestString* is `%{HTTP_ACCEPT}` which its value is taken from an `Accept` field in the HTTP request header. The `Accept` field can be a string like this: + +```HTTP +Accept: text/html, application/xhtml+xml, application/xml, image/webp +``` + +Each media type will be presented, separated by a comma. With that, we can use *CondPattern* to matches media types in this string. + + +#### Example 3: Dealing with query string + +Everything after the question mark (`?`) in the URL, but not that `?` itself, is a query string. + +For example, for the URL `https://en.wikipedia.org/w/index.php?title=Web`, the query string is `title=Web`. + +As the query string is not included in the string that the *Pattern* of *RewriteRule* will compared against, you cannot use *Pattern* to match them. + +To find pattern in the query string, use `%{QUERY_STRING}` as a *TestString* in *RewriteCond*. + +As an example, if you like to redirect the URL `https://w3id.org/example?a=1&b=2` to `https://example.com/path/file.php?a=1&b=2`, you can use this set of rules: + +```ApacheConf +RewriteCond %{QUERY_STRING} (.*) +RewriteRule ^ https://example.com/path/file.php?%1? [R=302,L] +``` + +In this example, the *CondPattern* `(.*)` in *RewriteCond* will match every characters in the query string (`a=1&b=2`) and put it in group one. This group one (`%1`) is later used in the *Substitution* of *RewriteRule*. + + + +Note that the special character to recall groups from *CondPattern* of *RewriteCond* is `%` (unlike the special character to recall groups from *Pattern* of *RewriteRule*, which is `$`). + +The character `?` at the end of the *Substitution* of *RewriteRule* tells the server not to pass the query string to the final URL after rewrite. + + +## README.md + +Each ID hosted on W3ID is expected to have a file named `README.md` containing an information about the ID itself and an information about the maintainer(s). This can be more elaborate than the information inside `.htaccess`. + +The `.md` file extension at the end of the file name indicates that the file uses Markdown markup language for text formatting. You can have tables and images as well, if needed. + +GitHub will automatically display the content of a `README.md` to repository visitors. + +An example of a good README file: [w3id.org/dggs/README.md](https://github.com/perma-id/w3id.org/blob/master/dggs/README.md) + +## Publish vocabularies with W3ID + +If you plan to publish a vocabulary/ontology with W3ID, +see https://w3id.org/examples/ontology. diff --git a/examples/ontology/.htaccess b/examples/ontology/.htaccess new file mode 100644 index 000000000..31ff29d62 --- /dev/null +++ b/examples/ontology/.htaccess @@ -0,0 +1,88 @@ +# Example repository +# +# This permanent w3id is meant to showcase an example on +# how to publish vocabularies with W3ID. +# +# https://w3id.org/examples/ontology redirects to +# https://dgarijo.github.io/example/release/1.0.1/index-en.html +# +# ## Contact +# This space is administered by: +# +# Daniel Garijo +# GitHub username: dgarijo + + +# Turn off MultiViews +Options -MultiViews + +# Directive to ensure *.rdf files served as appropriate content type, +# if not present in main apache config +AddType application/rdf+xml .rdf +AddType application/rdf+xml .owl +AddType text/turtle .ttl +AddType application/n-triples .n3 +AddType application/ld+json .json + +RewriteEngine on + +# Rewrite rule for latest version. +RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+xml) +RewriteCond %{HTTP_ACCEPT} text/html [OR] +RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR] +RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.* +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/index-en.html [R=303,L] + +# Rewrite rule to serve JSON-LD content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} application/ld\+json +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.json [R=303,L] + +# Rewrite rule to serve RDF/XML content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} \*/\* [OR] +RewriteCond %{HTTP_ACCEPT} application/rdf\+xml +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.owl [R=303,L] + +# Rewrite rule to serve N-Triples content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} application/n-triples +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.nt [R=303,L] + +# Rewrite rule to serve TTL content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} text/turtle [OR] +RewriteCond %{HTTP_ACCEPT} text/\* [OR] +RewriteCond %{HTTP_ACCEPT} \*/turtle +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.ttl [R=303,L] + + +# Rewrite rules for any other version. +RewriteCond %{HTTP_ACCEPT} !application/rdf\+xml.*(text/html|application/xhtml\+xml) +RewriteCond %{HTTP_ACCEPT} text/html [OR] +RewriteCond %{HTTP_ACCEPT} application/xhtml\+xml [OR] +RewriteCond %{HTTP_USER_AGENT} ^Mozilla/.* +RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/index-en.html [R=303,L] + +# Rewrite rule to serve JSON-LD content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} application/ld\+json +RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.json [R=303,L] + +# Rewrite rule to serve RDF/XML content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} \*/\* [OR] +RewriteCond %{HTTP_ACCEPT} application/rdf\+xml +RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.owl [R=303,L] + +# Rewrite rule to serve N-Triples content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} application/n-triples +RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.nt [R=303,L] + +# Rewrite rule to serve TTL content from the vocabulary URI if requested +RewriteCond %{HTTP_ACCEPT} text/turtle [OR] +RewriteCond %{HTTP_ACCEPT} text/\* [OR] +RewriteCond %{HTTP_ACCEPT} \*/turtle +RewriteRule ^(.+)$ https://dgarijo.github.io/example/release/$1/ontology.ttl [R=303,L] + +RewriteCond %{HTTP_ACCEPT} .+ +RewriteRule ^(.*)$ https://dgarijo.github.io/example/release/1.0.1/406.html [R=406,L] + +# Default response +# --------------------------- +# Rewrite rule to serve the RDF/XML content from the vocabulary URI by default +RewriteRule ^$ https://dgarijo.github.io/example/release/1.0.1/ontology.owl [R=303,L] diff --git a/example/readme.md b/examples/ontology/README.md similarity index 58% rename from example/readme.md rename to examples/ontology/README.md index 9b3a17376..5ca791e54 100644 --- a/example/readme.md +++ b/examples/ontology/README.md @@ -2,9 +2,7 @@ This permanent w3id is meant to showcase an example on how to publish vocabularies with w3id. -https://w3id.org/example redirects to https://dgarijo.github.io/example/release/1.0.1/index-en.html +https://w3id.org/examples/ontology redirects to https://dgarijo.github.io/example/release/1.0.1/index-en.html Maintainer: Daniel Garijo (@dgarijo) - -