[Libosinfo] [PATCH v2 02/52] docs: add document describing database organization

[Daniel P. Berrange]

Add a document that sets out the desired end goal for the
database organization that the following patches will move
towards.

Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
---
 docs/database-layout.txt | 225 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 225 insertions(+)
 create mode 100644 docs/database-layout.txt

diff --git a/docs/database-layout.txt b/docs/database-layout.txt
new file mode 100644
index 0000000..cb9557b
--- /dev/null
+++ b/docs/database-layout.txt
@@ -0,0 +1,225 @@
+   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 betweeen 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 exaxple, 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
+
-- 
2.4.3