QCodes: Best Practices
<<< QCodes Specification | QCodes' Home | QCodes: used terminology >>>
1. Design of URIs
A major consideration for implementing a web server for delivering information about Concepts and their CVs is the design of the URIs used for the CV (the CV URI) and the Concept (the Concept URI).
A Concept URI consists of the following two parts, which are concatenated without any character in between them:
- a CV URI
- a Code Value
The challenge is to define URIs for the CVs to which a code for the Concept can be appended and thus both URIs can be resolved by the same web server software.
A general rule for the maintainer of CV URIs for a domain is: A CV URI must not be a leading substring of another CV URI.
Examples:
Code Value: excode1
CV URI 1: http://example.org/cvs/testcv1
Discussion of CV URI 1:The CV URI has no clear terminator. This URI does not work perfectly; it could be resolved for a CV, but appending the Code Value to the CV URI results in the following Concept URI which will not be easily resolved by standard web server software features: http://example.org/cvs/testcv1excode1
Code Value: excode1
CV URI 2: http://example.org/cvs/testcv1#
Discussion of CV URI 2:
In this case the CV URI is terminated by a fragment identifier (‘#’) as defined by RFC 3986.
This should work, as appending the Code Value to the CV URI results in the following Concept URI, which will be more easily resolved by standard web server software features:
http://example.org/cvs/testcv1#excode1
Using the hash as the fragment identifier should result in loading a full document and the Code Value points to a section of the document which is identified by this Code Value; in the example case, the section is identified as "excode1". This is quite easy to maintain for the body controlling the CV.
The major issue with this solution is that the XML Schema specifications for the data type ID requires that the ID-value conforms to the NCName syntax which defines that the first character is a letter and MUST NOT not be a digit. Thus a code like “1excode” would be invalid for this resolution mechanism; this could result in potential issues when transforming existing CVs into the QCodes.
Another consideration is where a CV has a very large number of Codes. Using the fragment identifier terminator will result in a single very long HTML page, with a very large number of section identifiers.
Code Value: excode1
CV URI 3: http://example.org/cvs/testcv1/
Discussion of CV URI 3:
In this case the CV URI is terminated by a slash (‘/’) as defined by RFC 3986.
This results in the following Concept URI which can be resolved by virtually all web server software variants: http://example.org/cvs/testcv1/excode1
The only issue to be considered is the implementation in detail:
For the associated CV URI http://example.org/cvs/testcv1/, a single document including information about all concepts should be delivered; for a specific Concept URI like the one above a document with only a single piece of information (relating to the Code Value ‘excode1’) should be delivered. This requires n+1 documents for a CV with n members; which could be challenging to maintain for often-changed CVs with many members.
An alternative solution is to tweak the web server in a way that all URLs under http://example.org/cvs/ are forwarded to a special handler which creates the documents on the fly from a database.
2. What information to deliver
The terminology for resolving a URI or dereferencing a URI from the HTTP URI scheme implies that an HTTP request is sent to a web server and the web server should return an HTTP response.
This raises an issue: What should the HTTP response contain?
The IPTC recommends an approach which has already been taken by the W3C for e.g. publishing RDF Vocabularies:
(This recommendation applies to both CV URIs and Concept URIs)
- the HTTP status code provides information about the validity of the URI
code 200 = the URI is valid
code 303 = the URI may be valid, check at another location
other codes indicate that the URI is not valid and may give reasons.
- the content of the HTTP response should provide a natural language name for the concept which is identified by this URI. The language and the data format used for the response may be controlled by corresponding headers of the HTTP request.
3. Using Content Negotiation to retrieve data in a specific format
As indicated in item 2 (above) the format of the returned response could be controlled by the "accept" header of the HTTP request. This header should include a registered MIME type and the web server should deliver the response content using this format; this procedure is called content negotiation.
The IPTC recommends supporting these MIME types:
- text/html or application/xhtml+xml for human readable content
- application/rdf+xml for RDF/XML
- text/turtle for RDF/Turtle
The MIME type application/vnd.iptc.g2.knowledgeitem+xml should be used for IPTC G2 Knowledge Items.
We welcome feedback on and questions about QCode. You may post to the public QCodes Forum.
<<< QCodes Specification | QCodes' Home | QCodes: used terminology >>>