Add a doc describing the best practice guidelines around the format of URIs for various entities. Signed-off-by: Daniel P. Berrange <berrange@xxxxxxxxxx> --- 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 _______________________________________________ Libosinfo mailing list Libosinfo@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libosinfo
