[Libosinfo] [PATCH v3 01/60] docs: describe entity URI ID scheme

[Christophe Fergeau]

On Mon, Oct 12, 2015 at 06:10:22PM +0100, Daniel P. Berrange wrote:
> 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.

Did not read everything very carefully, but I spotted a "disto" typo
here.

Christophe
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libosinfo/attachments/20151016/e3a938b5/attachment.sig>