[Libosinfo] [PATCH v2 01/52] docs: describe entity URI ID scheme

[Daniel P. Berrange]

Add a doc describing the best practice guidelines around
the format of URIs for various entities.

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

diff --git a/docs/entity-id-scheme.txt b/docs/entity-id-scheme.txt
new file mode 100644
index 0000000..3121810
--- /dev/null
+++ b/docs/entity-id-scheme.txt
@@ -0,0 +1,117 @@
+   Osinfo Entity ID Scheme
+   =======================
+
+This document describes how to create URIs for entities in the osinfo
+database.
+
+The ID URIs are used to determine what filename the XML document
+for the entity will have, so care should be taken to follow
+existing naming practices as closely as possible.
+
+Operating systems
+=================
+
+The ID URI scheme SHOULD follow one of these patterns
+
+   http://vendor-domain/distro-name/version
+   http://vendor-domain/short/id
+
+The "vendor-domain" component should refer to the domain name associated
+with the vendor who originally shipped the operating system. For example,
+with Solaris 8, the "vendor-domain" would be "sun.com", even though the
+Solaris product line is now owned by Oracle.
+
+For legacy operating systems which were shipped before the arrival of the
+world wide web, some guidelines should be followed to come with with a
+suitable domain name. If the company that shipped the operating system
+had a domain name at any time after the product was shipped, that should
+be used. If the company never had any kind of domain name, a plausible
+domain name should be invented.
+
+In general the scheme based on the distro name and version is preferred,
+but some operating systems (eg Windows) don't have sensible unique
+version numbers. In such cases, the alternative scheme based on the
+short-id is acceptable.
+
+The "distro-name" component should match the value of the <distro>
+attribute in the entity.
+
+The "version" component should match the value of the <version> attribute
+in the entity.
+
+The "short/id" component should be based on the value of the first
+<short-id> attribute in the entity.
+
+Some examples
+
+   http://redhat.com/rhel/5.3        (distro==rhel, version=5.3)
+   http://microsoft.com/win/2k12r2   (short-id==win2k12r2)
+
+
+Platforms
+=========
+
+The ID URI scheme SHOULD follow this pattern
+
+   http://vendor-domain/product-name/version
+
+The "vendor-domain" component should refer to the domain name associated
+with the vendor who originally shipped the platform. For example, with
+VirtualBox, for early releases the "vendor-domain" would be "sun.com",
+while for latter releases it would be "oracle.com".
+
+The "product-name" component should match the value of the <product>
+attribute in the entity.
+
+The "version" component should match the value of the <version> attribute
+in the entity.
+
+Some examples
+
+   http://xen.org/xen/3.0.2          (product==xen, version=3.0.2)
+   http://qemu.org/qemu/1.0          (product=qemu, version=1.0)
+
+
+Devices
+=======
+
+The ID URI scheme SHOULD follow one of these patterns
+
+   http://pcisig.com/pci/vendor-id/product-id
+   http://usb.org/usb/vendor-id/product-id
+   http://xen.org/xen/name
+   http://ibm.com/ps2/name
+   http://vendor-domain/isa/name
+
+
+Datamaps
+========
+
+The ID URI scheme SHOULD follow this pattern
+
+   http://vendor-domain/map-name
+
+The choice of the "map-name" data format is not defined.
+
+
+Install scripts
+===============
+
+The ID URI scheme SHOULD follow one of these patterns
+
+  http://vendor-domain/distro/scheme/profile
+  http://vendor-domain/distro/version/scheme/profile
+
+"disto" is the name of the operating system distro that uses
+the install script.
+
+"version" is an optional version number of the distro. This
+is rarely used, as it is usually possible to create an
+install script that works across multiple versions by using
+XSL conditionals.
+
+"scheme" is the install script software format, eg "kickstart"
+for Anaconda, or "preseed" for the Debian installer.
+
+"profile" is the declared install script profile "jeos" or
+"desktop".
-- 
2.4.3