I just can't understand IRI, any expainations?

[IvanJobs]

Hi guys,

I've studied Readium SDK's code for a while, and I still don't quite understand what IRI used for. I know that IRI is something like URN + URL.

It seems IRI is used in many places across the src. For example, in metadata.h(https://github.com/readium/readium-sdk/blob/master/ePub3/ePub/metadata.h), line 231 is as following:

@param owner The Package to which the metadata belongs; used for property IRI
resolution.
/
void AddExtension(xmlNodePtr node, const Package owner);

why should metadata contain its package's reference? what does it mean here by "used for property IRI resoluation"?

Thx in advance :)

[AlanQuatermain]

An IRI is an International Resource Identifier. It's basically a URI which is composed of Unicode characters (rather than sticking to URI's strict ASCII charset).

Each metadata item is identified by a name and a prefix. The prefix may be empty, meaning that it's part of the base vocabulary. Now, for matching purposes, each prefix maps to an IRI. This is similar to the way XML namespaces operate: you assign a prefix to a URI, and then you use the prefix to qualify stuff. The parser then uses the prefix to expand to the full URI for matching purposes. This way if one document fragment defines xmlns:xmldsig='http://www.w3.org/2000/09/xmldsig#' and another defines xmlns:ds='http://www.w3.org/2000/09/xmldsig#', the parser sees all the content as belonging to the same namespace— different prefixes, same URI, and the URI is the actual identifier.

It's the same for properties (all properties, not just metadata) in EPUB 3. Some prefixes are implicitly mapped by the standard, and you can define your own (as the EPUB FXL standard does, in fact). For matching purposes, the prefix is resolved to an IRI and the name is appended to that IRI to create the identifier for that particular property. Any new prefixes must be declared in the root <package> tag of the OPF document, so we implement the prefix-to-IRI mapping table there: each package has its own list of known prefix-to-IRI mappings.

So, if your package contains:

<package ... prefix="rendition: http://www.idpf.org/vocab/rendition/#">
    ...
    <spine toc="ncx">
        <item idref="cover" properties="rendition:page-spread-center"/>
        ...
    </spine>
    ...
</package>

…the parser will take the rendition:page-spread-center value and transform it into the canonical IRI http://www.idpf.org/vocab/rendition/#page-spread-center. This means that you could, for brevity, write your document like so:

<package ... prefix="r: http://www.idpf.org/vocab/rendition/#">
    ...
    <spine toc="ncx">
        <item idref="cover" properties="r:page-spread-center"/>
        ...
    </spine>
    ...
</package>

…and the parser would still map the property to the same IRI: http://www.idpf.org/vocab/rendition/#page-spread-center

Also note that all this has been overhauled to be much more flexible and obvious in the develop branch, which should be hitting master quite soon.