<section id="nie-explanation">
<title>Overview</title>

<sect2 id="nie-introduction">
<title>Introduction</title>
<para>The core of the NEPOMUK Information Element Ontology and the entire
  Ontology Framework revolves around the concepts of <link linkend="nie-DataObject">DataObject</link> and
 <link linkend="nie-InformationElement">InformationElement</link>. They express  the representation
 and content of a piece of data. Their specialized subclasses (defined
 in the other ontologies) can be used to classify
 a wide array of desktop resources and express them in RDF.
</para>

<para>
 <link linkend="nie-DataObject">nie:DataObject</link> class represents a bunch of
 bytes somewhere (local or remote), the physical entity that contain
 data. The <emphasis>meaning</emphasis> (interpretation) of that entity, the
 information for the user contained in those bytes (e.g. a music file,
 a picture) is represented on the
<link linkend="nie-InformationElement">nie:InformationElement</link> side of the
ontology.
</para>

<para>
Both sides are linked using the
property <link linkend="nie-interpretedAs">nie:interpretedAs</link> (and its reverse
<link linkend="nie-isStoredAs">nie:isStoredAs</link>), indicating the correspondence
between the physical element and its interpretation. There is also a
property to
link <link linkend="nie-InformationElement">nie:InformationElement</link>s,
representing the logical containment between them (like a picture and
its album).
</para>

<sect3 id="nie-common-properties">
  <title>Common properties</title>
  <para>
    Given that the classes defined in this ontology are the superclasses for almost
    everything in the Nepomuk set of ontologies, the
    properties defined here will be inherited for a lot of classes. It is
    worth to comment few of them with special relevance:
  </para>
  <variablelist>
    <varlistentry>
      <term><link linkend="nie-title">nie:title</link></term>
      <listitem><para>Title or name or short text describing the item</para></listitem>
    </varlistentry>

    <varlistentry>
      <term><link linkend="nie-description">nie:description</link></term>
      <listitem><para>More verbose comment about the element</para></listitem>
    </varlistentry>

    <varlistentry>
      <term><link linkend="nie-language">nie:language</link></term>
      <listitem><para>To specify the language of the item.</para></listitem>
    </varlistentry>

    <varlistentry>
      <term><link linkend="nie-plainTextContent">nie:plainTextContent</link></term>
      <listitem><para>Just the raw content of the file, if it makes sense as text.</para></listitem>
    </varlistentry>

    <varlistentry>
      <term><link linkend="nie-generator">nie:generator</link></term>
      <listitem><para>Software/Agent that set/produced the information.</para></listitem>
    </varlistentry>

    <varlistentry>
      <term><link linkend="nie-usageCounter">nie:usageCounter</link></term>
      <listitem><para>Count number of accesses to the information. It can be an
      indicator of relevance for advanced searches</para></listitem>
    </varlistentry>
  </variablelist>
</sect3>

<sect3 id="nie-dates-timestamps">
<title>Dates and timestamps representations</title>
<para>There are few important dates for the life-cycle of a resource. These dates are properties of the nie:InformationElement class, and inherited for its subclasses:</para>
<variablelist>
  <varlistentry>
     <term><link linkend="nie-informationElementDate">nie:informationElementDate</link></term>
     <listitem>
       <para>This is an ''abstract'' property that act as superproperty of
       the other dates. Don't use it directly.</para>
     </listitem>
  </varlistentry>

  <varlistentry>
    <term><link linkend="nie-contentLastModified">nie:contentLastModified</link></term>
    <listitem>
      <para>Modification time of a resource. Usually the mtime of a local file, or information from the server for online resources.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><link linkend="nie-contentCreated">nie:contentCreated</link></term>
    <listitem>
      <para>Creation time of the content. If the contents is created by an application, the same application should set the value of this property. Note that this property can be undefined for resources in the filesystem because the creation time is not available in the most common filesystem formats.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><link linkend="nie-contentAccessed">nie:contentAccessed</link></term>
    <listitem>
      <para>For resources coming from the filesystem, this is the usual access time to the file. For other  kind of resources (online or virtual), the application accessing it should update its value.</para>
    </listitem>
    </varlistentry>
    <varlistentry>
      <term><link linkend="nie-lastRefreshed">nie:lastRefreshed</link></term>
      <listitem>
	<para>.</para>
      </listitem>
    </varlistentry>
</variablelist>
</sect3>
</sect2>

<refsect2 id="nie-uri-representation">
<title>URIs and full representation of a file</title>
<para>One of the most common resources in a desktop is a file. Given the split between Data Objects and Information Elements, some times it is not clear how a real file is represented into Nepomuk. Here are some indications:</para>
<orderedlist>
 <listitem>Every file (local or remote) should generate one DataObject instance and an InformationElement instance.</listitem>
 <listitem>Even when Data Objects and Information Elements are completely different things, for efficiency reasons in Tracker we use the same URI for both of them.</listitem>
 <listitem>The URI will be an autogenerated ID, and the real location of the item (e.g. ''file://path/to/file.mp3'') is a property of the Data Object</listitem>
 <listitem>Every DataObject must have the property <link linkend="nie-url">nie:url</link>, that points to the location of the resource, and should be used by any program that wants to access it.</listitem>
 <listitem>There is a deprecated property in the ontology: <link linkend="nie-isStoredAs">nie:isStoredAs</link> . We discourage its use in the code: in the best case it is a loopback to the nie:url value, but in general it can contain any value or not be set at all.</listitem>
</orderedlist>

<para>Here comes an example, for the image file /home/user/a.jpeg:</para>

<programlisting>
&lt;urn:uuid:10293801928301293&gt; a nmm:Photo, nfo:FileDataObject ;
	# Properties as nmm:Photo
	 nfo:width 49 ;
	 nfo:height 36 ;
	nmm:flash &lt;nmm:flash-off&gt;;
	nmm:whiteBalance &lt;nmm:white-balance-automatic&gt; ;
	nfo:equipment [ a nfo:Equipment ; nfo:make 'Nokia'; nfo:model 'N900'; nfo:equipmentSoftware 'Tracknon' ] ;

	# Properties from nfo:FileDataObject
	nfo:fileSize 12341234 ;

	# Mandatory for any nfo:DataObject
	nie:url &lt;file:///home/ivan/test/CC-test-big.png&gt; .

</programlisting>

</refsect2>

 <refsect2 id="nie-related-information">
  <title>Related information</title>

  <para>This explanation is just a brief extract from the
    original <ulink url="http://www.semanticdesktop.org/ontologies/nie">
      Nepomuk NIE Ontology</ulink> web page.</para>
  </refsect2>
</section>
