\chapter{Knowledge graph}

  Djehuty processes its information using the Resource Description
  Framework \citep{lassila-99-rdf}.  This chapter describes the parts that
  make up the data model of \t{djehuty}.

  This chapter dives into the structure of the data model, but does not
  describe every property.  When running an instance of \code{djehuty},
  the ``Exploratory'' available in the ``Admin panel'' can be used to explore
  every property.

\section{Use of vocabularies}

  Throughout this chapter, abbreviated references to ontologies are used.
  Table \ref{table:vocabularies} lists these abbreviations.

  \hypersetup{urlcolor=black}
  \begin{table}[H]
    \begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
      \headrow
      \b{Abbreviation} & \b{Ontology URI}\\
      \t{djht}         & Internal and unpublished ontology.\\
      \t{rdf}          & \dhref{http://www.w3.org/1999/02/22-rdf-syntax-ns\#}\\
      \t{rdfs}         & \dhref{http://www.w3.org/2000/01/rdf-schema\#}\\
      \t{xsd}          & \dhref{http://www.w3.org/2001/XMLSchema\#}
    \end{tabularx}
    \caption{\small Lookup table for vocabulary URIs and their abbreviations.}
    \label{table:vocabularies}
  \end{table}
  \hypersetup{urlcolor=LinkGray}

\section{Notational shortcuts}

  In addition to abbreviating ontologies with their prefix we use another
  notational shortcut.  To effectively communicate the structure of the RDF
  graph used by \t{djehuty} we introduce a couple of shorthand notations.

\subsection{Notation for typed triples}

  When the \code{object} in a triple is \i{typed}, we introduce the shorthand
  to only show the type, rather than the actual value of the \code{object}.
  Figure \ref{fig:typed-notation} displays this for URIs, and figure
  \ref{fig:typed-literals-notation} displays this for literals.

  \includefigure{typed-notation}{Shorthand notation for triples with an
    \code{rdf:type} which features a hollow predicate arrow and a colored
    type specifier with rounded corners.}

  Literals are depicted by rectangles (with sharp edges) in contrast to URIs
  which are depicted as rectangles with rounded edges.

  \includefigure{typed-literals-notation}{Shorthand notation for triples with
    a literal, which features a hollow predicate arrow and a colored
    rectangular type specifier.}

  When the subject of a triple is the shorthand type, assume the subject is not
  the type itself but the subject which has that type.

\subsection{Notation for \texttt{rdf:List}}

  To preserve the order in which lists were formed, the data model makes use
  of \code{rdf:List} with numeric indexes.  This pattern will be abbreviated
  in the remainder of the figures as displayed in figure
  \ref{fig:rdf-list-abbrev}.

  \includefigure{rdf-list-abbrev}{Shorthand notation for \code{rdf:List}
    with numeric indexes, which features a hollow double-arrow.  Lists have
    arbitrary lengths, and the numeric indexes use 1-based indexing.}

  The hollow double-arrow depicts the use of an \code{rdf:List} with numeric
  indexes.

\section{Datasets}

  Datasets play a central role in the repository system because every
  other type links in one way or another to it.  The user submits
  files along with data about those bytes as a single record which we
  call a \code{djht:Dataset}.  Figure \ref{fig:dataset} shows how the
  remainder of types in this chapter relate to a \code{djht:Dataset}.

  \includefigure{dataset}{The RDF pattern for a \code{djht:Dataset}.
    For a full overview of \code{djht:Dataset} properties, use the exploratory
    from the administration panel.}

  Datasets are versioned records.  The data and metadata between versions
  can differ, except all versions of a dataset share an identifier.  We use
  \code{djht:DatasetContainer} to describe the version-unspecific properties
  of a set of versioned datasets.

  \includefigure{dataset-container}{The RDF pattern for a
    \code{djht:DatasetContainer}.  All versions of a dataset share a
    \code{djht:dataset\_id} and a UUID in the container URI.}

  The data model follows a natural expression of published versions as a
  linked list.  Figure \ref{fig:dataset-container} further reveals that
  the \i{view}, \i{download}, \i{share} and \i{citation} counts are stored
  in a version-unspecific way.

\section{Collections}

  Collections provide a way to group \code{djht:Dataset} objects.

  \includefigure{collection}{The RDF pattern for a \code{djht:Collection}.
    For a full overview of \code{djht:Collection} properties, use the
    exploratory from the administration panel.}

  Collections are (just like Datasets) versioned records.  The metadata between
  versions can differ, except all versions of a collection share an identifier.
  We use \code{djht:CollectionContainer} to describe the version-unspecific
  properties of a set of versioned collections.

  \includefigure{collection-container}{The RDF pattern for a
    \code{djht:CollectionContainer}.  All versions of a collection share a
    \code{djht:collection\_id} and a UUID in the container URI.}

  The data model follows a natural expression of published versions as a
  linked list.  Figure \ref{fig:collection-container} further reveals that
  the \i{view}, \i{download}, \i{share} and \i{citation} counts are stored
  in a version-unspecific way.

\section{Authors}

  \t{djehuty} keeps records of authors including their full name, ORCID,
  and e-mail address.  Furthermore, each \code{djht:Account} has a linked
  \code{djht:Author} record.

  \includefigure{author}{The RDF pattern for an \code{djht:Author}.}

\section{Accounts}

  \t{djehuty} uses an external identity provider, but stores an e-mail address,
  full name, and preferences for categories.

  \includefigure{account}{The RDF pattern for an \code{djht:Account}.}

\section{Funding}

  When the \code{djht:Dataset} originated out of a funded project, the funders
  can be listed using \code{djht:Funding}.  Figure \ref{fig:funding} displays
  the details for this structure.

  \includefigure{funding}{The RDF pattern for a \code{djht:Funding}.}

\section{Categories}

  Categories in \t{djehuty} are a controlled vocabulary based on the
  \href{https://www.abs.gov.au/Ausstats/abs@.nsf/Latestproducts/4AE1B46AE2048A28CA25741800044242}%
  {Australian and New Zealand Standard Research Classification (ANZSRC)}.  The
  hierarchical structure is captured by using \code{id} and \code{parent\_id}
  properties.

  \includefigure{category}{The RDF pattern for an \code{djht:Category}.}

\section{Institutions/groups}

  An \code{djht:Account} has an affiliation with an institute or research group.
  The \code{djht:InstitutionGroup} is stored per \code{djht:Dataset} and
  \code{djht:Collection}.  The groups can be structured hierarchically by
  using the \code{id} and \code{parent\_id} properties.

  \includefigure{institutiongroup}{The RDF pattern for an \code{djht:InstitutionGroup}.}

\section{Files}

  A \code{djht:Dataset} keeps a list of \code{djht:File} records.  The file
  metadata is stored in the knowledge graph while the file contents are
  stored on a filesystem.  The location of the file data is tracked via the
  \code{djht:filesystem\_location} property.

  \includefigure{file}{The RDF pattern for a \code{djht:File}.}

\section{Private links}

  Before a \code{djht:Dataset} or a \code{djht:Collection} is made publically
  available, it can be shared using a private link.

  \includefigure{privatelink}{The RDF pattern for a \code{djht:PrivateLink}.}

  The figure \ref{fig:privatelink} displays how private links are stored for
  a \code{djht:Dataset}, and it works the same for a \code{djht:Collection}.

\section{Collaborators}

  To enable multiple accounts collaborating on a dataset before it's published,
  each \code{djht:Dataset} can have a list of \code{djht:Collaborator} objects.

  \includefigure{collaborators}{The RDF pattern for a \code{djht:Collaborator}.}

  As shown in figure \ref{fig:collaborators}, a \code{djht:Collaborator} can be
  given read, edit, and/or remove rights independently for both metadata (the
  form fields) and data (the files).
