   The Libosinfo Database Layout
   =============================

This document specifies the layout of the libosinfo database and
details the process by which data files must be loaded by any
compliant applications consuming the database.


Entities
========

The purpose of the database is to store information related to
a number of entity types that are relevant when provisioning
virtual machines.

 - OS - a guest operating system
 - Platform - a host virtualization platform
 - Device - a hardware device
 - Install Script - script for automated installation of an OS
 - Data map - a mapping between two datasets
 - Deployment - an association of an OS on a Platform

Each of these entities has a variety of pieces of information
associated with it. There are also relationships between many
of the entities.

The path component of the entity ID URI will be used to form
the filename of the XML document on disk.


Database locations
==================

There are a number of standard directory locations which
together form the database.


  - System location

    This is determined by the env variable

      $OSINFO_SYSTEM_DIR

    If not set, then defaults to /usr/share/osinfo

    This location is intended for use by operating system
    distributors to install the initial data set via a
    package management system like RPM or Deb


  - Local location

    This is determined by the env variable

      $OSINFO_LOCAL_DIR

    If not set, then defaults to /etc/osinfo

    This location is intended for use by local system
    administrators to install custom local data that
    should be available to all users on a host


  - User location

    This is determined by the env variable

      $OSINFO_USER_DIR

    If not set, then defaults to $XDG_CONFIG_HOME/osinfo

    If that is not set, then defaults to $HOME/.config/osinfo

    This location is intended for use by unprivileged users
    wishing to install local data for use by their applications

A compliant implementation MUST load data from all the standard
locations declared in this document. An implementation MAY wish
to load data from additional non-standard locations depending
on application requirements.

When loading entities from these locations, if the same
entity is present in multiple locations, the entity found
in the later location MUST take priority over the entity
found in the earlier locations. The next section details how
entities are named.


File naming
===========

Within each of the database locations mentioned above, there are
a number of file naming requirements that must be followed.

First level directory
---------------------

The first (top) level directory within the database location
MUST only contain the following entries

 - os
 - platform
 - install-script
 - datamap
 - device
 - deployment

Each of these entries MUST be a directory, any other type of
file MUST NOT be loaded and a warning SHOULD be reported.
An entry MAY be omitted if there are no files to be stored
within it.

These directory entries correspond to the types of entity
that are stored in the osinfo database.


Second level directory
----------------------

The second level directories within the database location are
used to group entities based on domain names from the entity
ID URI.

For example, if an entity has a URI

   http://fedoraproject.org/fedora/22

Then there will be a second level directory named
"fedoraproject.org"

All entries in the second level MUST be directories, any
other type of file MUST NOT be loaded an a warning SHOULD
be reported.


Third level directory
---------------------

Within the thread level directories there may be further files
or directories with the following naming

 - ENTITY-NAME.xml
 - ENTITY-NAME.d

The ENTITY-NAME string MUST only contain characters from the
following set

 - Letters: a-z, A-Z
 - Numbers: 0-9
 - Punctuation: _ - .

Any file or directory names not matching these rules MUST be
ignored when loading the database, and a warning SHOULD be
reported.

If both ENTITY-NAME.xml and ENTITY-NAME.d are present for a
common value of ENTITY-NAME, then ENTITY-NAME.xml MUST be
loaded before the contents of ENTITY-NAME.d are loaded.

The ENTITY-NAME value is formed from the path component
of the entity ID URI. Any characters in the path component
which are not in the permitted set MUST be replaced by a
'-' character.

For example, an entity ID of http://fedoraproject.org/fedora/22
will result in an ENTITY-NAME of "fedora-22", since '/' is to
be substituted with '-'.


ENTITY-NAME.xml
---------------

This entry should either be a regular file, or a symbolic link
to /dev/null. If another file type is found, the file MUST NOT
be loaded and a warning SHOULD be reported.

If the file is zero-length or points to /dev/null, then this
represents a black-out override. This indicates that the
ENTITY-NAME.xml file from a lower priority directory MUST NOT
be loaded.

If the file is non-zero-length then its contents MUST be a
single entity with a URI that matches the file path of the
XML file relative to the location root.

For example, if the file path is

  /etc/osinfo/os/fedoraproject.org/fedora-22.xml

the, the file MUST contain a operating system entity definition
for the operating system with id http://fedoraproject.org/fedora-22.xml.
If the entity type does not match the directory in which the
file was located, the file MUST NOT be loaded and a warning
SHOULD be reported


ENTITY-NAME.d
-------------

This entry MUST be a directory, if another file type is found
this entry MUST NOT be loaded and a warning SHOULD be reported

Within this second level directories there may be further files
with the following naming

 - FILE-NAME.xml

The FILE-NAME string MUST only contain characters from the
following set

 - Letters: a-z, A-Z
 - Numbers: 0-9
 - Punctuation: _ - .

Any file or directory names not matching these rules MUST be
ignored when loading the database, and a warning SHOULD be
reported.

The FILE-NAME.xml must be a regular file, any other type
of file MUST NOT be loaded and a warning SHOULD be reported

The contents of each FILE-NAME.xml found are used to augment
information associated with the entity identified by
ENTITY-NAME.d
