QCodes: Specification

<<< QCodes in the Semantic Web context | QCodes' Home | QCodes: Best Practices >>>

ABNF for QCode:

QCode  =  alias “:” code
See details about the lexical spaces for the alias and the code below.

1. Lexical Space Specification and Processing Model for CV URIs, CV Aliases, Code Values, and QCodes

1.1.  Lexical Space

Lexical space for CV URIs: conforms with the Unreserved Characters of RFC 3986, section 2.3. Reserved Characters as per RFC 3986, section 2.2 must be considered depending on the selected URI scheme.
Lexical space for Aliases: all characters except colon (#u003A) and white space (#u0020 | #u0009 | #u000D | #u000A).
Lexical space for Codes:

  • All Unreserved Characters of RFC 3986, section 2.3.
  • Reserved Characters as per RFC 3986, section 2.2 must be considered depending on the selected URI scheme. See also section 2.1.2 (Creating Codes) below.
  • As an alternative to percent-encoding whitespace characters (#u0020 | #u0009 | #u000D | #u000A) as defined by RFC 3986 may be used, these characters may be replaced by a sequence of one or more unreserved characters - like e.g. underscore or hyphen - that is reused for this purpose according to the practices of the provider. It is defined that such a sequence MUST NOT be part of any of the codes used by the provider in that CV, else this will preclude being able to definitely re-create the orginal code from the QCode's Code Part.

 

2. Processing Model

2.1. Creating CV URIs

Define a URI complying with the rules defined in 1 (above).
Note: every CV URI must comply with the RFC defining URIs (3986) or IRIs (3987).

2.2 Creating Codes

A Concept URI is created by appending the code of a Concept to the CV URI for the CV that contains the Concept. Therefore, appending a Code Value to a valid CV URI must make a valid URI, in particular, the Code Value must only contain characters that are legal URI characters (RFC 3986). As defined in RFC 3986, the CV Authority MAY percent encode reserved characters as well as the percent ("%") character depending on the role of each character as defined by that specific publisher for this Concept URI. Any percent encoding which is applied to characters in the code of a concept URI MUST be used also by the corresponding QCode.
The CV Authority is fully responsible for ensuring that Concept URIs defined by that Authority are properly resolved by any resolution system provided by that Authority.

The examples below show how to deal with a string which should be used as Code Value and includes a reserved character:

Example without encoding a slash in the code:
String to be used as Code: ebc13/14
Code Value: ebc13/14
CV URI: http://cv.example.org/schemeA/
CV Alias: schA
QCode: schA:ebc13/14
Concept URI: http://cv.example.org/schemeA/ebc13/14
Note: The Scheme Authority has to take care that this URL is resolved properly by a resolution system provided by it.

Example with encoding a slash in the code:
String to be used as Code: ebc13/14
Code Value: ebc13%2F14 (with applied percent encoding)
CV URI: http://cv.example.org/schemeB/
CV Alias: schB
QCode: schB:ebc13%2F14
Concept URI: http://cv.example.org/schemeB/ebc13%2F14

2.2.1 QCodes

2.2.1.1 Creating QCodes
Concatenate the CV Alias, a colon and the Code to form a QCode.

2.2.1.2 Inserting a QCode as the value of an attribute in an XML document
1. Take a QCode as created in 2.2.1.1 and apply any required XML encoding to this string (Note: this is typically done by the XML processor software).
2. Insert the resulting string into an attribute as the QCode value.

2.2.1.3 Receiving/Parsing QCodes from an XML Document

  1. Retrieve the QCode value from the XML document
  2. Apply any required XML decoding (Note: this is typically done by the XML processor software).
  3. To split a QCode into a CV Alias and a Code Value, identify the first colon, searching from left to right. The string to the left of the colon is the CV Alias; the string to the right is the Code Value. If no colon is found, the QCode is invalid.
  4. Check whether the CV Alias is defined in the catalog declared for this XML document (see 3. below). If it is not, the QCode is invalid.

2.2.2 Concept URIs
QCode processors should be able to process Internationalized Resource Identifiers (IRIs) as per RFC 3987.

2.2.2.1 Creating a Concept URI/IRI
Concatenate the CV URI and the Code Value to obtain the Concept URI.

2.2.2.2 Comparing Concept URIs/IRIs
If provided Concept URIs are IRIs per RFC 3987 then they must be compared for equivalence as defined per RFC 3987, section 5.
If provided Concept URIs are URIs per RFC 3986 then they must be compared for equivalence as defined per RFC 3986, section 6.

 

3.    Processing Catalogs

Catalogs are XML structures existing in the IPTC G2-Standards' News Architecture (NAR) XML namespace http://iptc.org/std/nar/2006-10-01/;  assume a namespace prefix “nar” is assigned to it.

3.1.  Structure of a Catalog

A Catalog MUST have one or more nar:scheme elements.

Each scheme element within a Catalog MUST have an alias attribute and a corresponding uri attribute.

Alias declarations are local to the XML document in which they appear and cannot be overridden in another document.
Example:

<catalog xmlns="http://iptc.org/std/nar/2006-10-01/" additionalInfo="http://www.iptc.org/goto?G2cataloginfo">
   <scheme alias="medtop" uri="http://cv.iptc.org/newscodes/mediatopic/" />
</catalog>

3.1.1.    Processing Remote Catalogs

By activating the hyperlink of a nar:remoteCatalog element, a plain catalog structure is returned, and MUST be processed as if were locally defined.

3.1.2.    Caching a Catalog

It is recommended for a processor to cache a remote Catalog indefinitely, so that provider's servers are not overcharged with file requests.

When a processor opens an XML document, it MUST check the URL(s) of the remote Catalog(s) found in this document. If a Catalog has not been previously cached, the processor MUST fetch it, check it, and SHOULD store its content in a cache.

Different remote Catalogs MAY define different mappings for a given CV Alias. An entry in a remote Catalog cache should therefore be saved as a triple {remote Catalog URL, CV Alias, CV URI}.

3.1.3.    Checking a Catalog

It is OK for one CV URI to have two CV Aliases. It is an error if one CV Alias is mapped to more than one different CV URIs in the scope of a single XML document (an issue called alias collision). Note that this error may arise within a Catalog, as well as across a set of Catalogs (local or remote) declared in a given XML document.

Before processing an XML document, a processor MUST check its Catalogs. If an alias collision is found, the processor MUST reject the XML document as it can lead to misinterpretation of the information.

 

4.    Processing Controlled Vocabularies

4.1.  Evolution of CV URIs

CVs evolve: terms are added, names are changed, terms are retired. A CV Authority will release a new version after each CV update. But a provider may not want to adopt the latest version of a CV. Therefore the CV URI MUST NOT change as long as the evolution does not break backward compatibility rules.

4.2.  Retrieving All Terms of a CV

Here we are interested in CVs defined as an explicit list of terms. CVs defined via an algorithm are out of scope of this section. A CV definition is defined as the finite set of terms composing a CV. A CV definition MAY be a subset of an original CV, e.g. maintained by an external authority.

Note: An authority is not necessarily able to make CV definitions available for operational use, and a provider may choose to use only a subset of the CV defined by an authority.

An authority MAY provide different variants of a CV definition, e.g. a list of codes, a list of codes plus a name in a specific language, a list of codes plus names in all available languages.


We welcome feedback on and questions about QCode. You may post to the public QCodes Forum.

<<< QCodes in the Semantic Web context | QCodes' Home | QCodes: Best Practices >>>