Policies/URI & XML Namespaces Policy: Difference between revisions

From KDE Community Wiki
m (add to category 'Policies')
m (7 revisions imported: Move Policies from techbase)
 
(4 intermediate revisions by 2 users not shown)
Line 4: Line 4:


== URIs ==
== URIs ==
Some applications needs custom URIs schemes in their implementation. Regardless of if the URI scheme is used internally or publically, it is always an unfortunate design choice to simply make up a scheme name (such as <code>my-scheme://my-data</code>) for the simple reason that anyone can do that, and thus potentially cause interoperability issues and confusion.
Some applications needs custom URIs schemes in their implementation. Regardless of if the URI scheme is used internally or publically, it is always an unfortunate design choice to simply make up a scheme name (such as <tt>my-scheme://my-data</tt>) for the simple reason that anyone can do that, and thus potentially cause interoperability issues and confusion.
The approach for creating a custom URI scheme without also getting into trouble<ref name="1">However, due to the usability requirements KDE in some cases have, there can be circumstances where a ''rogue'' scheme(such as <code>media://</code>) makes sense. Carefully consider(discuss, seek peer review) before going for an invalid URI scheme, and if so, ensure technical measures are done to lower the risks of complication.</ref>
The approach for creating a custom URI scheme without also getting into trouble<ref>However, due to the usability requirements KDE in some cases have, there can be circumstances where a ''rogue'' scheme(such as <tt>media://</tt>) makes sense. Carefully consider(discuss, seek peer review) before going for an invalid URI scheme, and if so, ensure technical measures are done to lower the risks of complication.</ref>
is to either ensure the scheme is generic to the extent it can be specified in an RFC (similar to [http://www.ietf.org/rfc/rfc2141.txt urn] or [http://www.ietf.org/rfc/rfc2616.txt http]), or to use an existing scheme which was designed for this purpose: the [http://www.taguri.org/ tag] scheme.
is to either ensure the scheme is generic to the extent it can be specified in an RFC (similar to [http://www.ietf.org/rfc/rfc2141.txt urn] or [http://www.ietf.org/rfc/rfc2616.txt http]), or to use an existing scheme which was designed for this purpose: the [http://www.taguri.org/ tag] scheme.


The tag scheme combines a host name with a date to create a unique URI scheme (the date makes the URI immune to change in ownership of the domain name). KDE applications can use the tag scheme with the ''kde.org'' domain by following a slightly constrained syntax of the tag scheme:
The tag scheme combines a host name with a date to create a unique URI scheme (the date makes the URI immune to change in ownership of the domain name). KDE applications can use the tag scheme with the ''kde.org'' domain by following a slightly constrained syntax of the tag scheme:
  tag:kde.org,2004:[application name]:[application specific string]<ref>Formally speaking, the ABNF product specific in RFC 4151 is augmented into <code>applicationName ":" applicationSpecific</code>, where both <classname>applicationName</classname> and applicationSpecific is <code>*( pchar / "/" / "?" )</code>.</ref>
  tag:kde.org,2004:[application name]:[application specific string]<ref>Formally speaking, the ABNF product specific in RFC 4151 is augmented into <tt>applicationName ":" applicationSpecific</tt>, where both <classname>applicationName</classname> and applicationSpecific is <tt>*( pchar / "/" / "?" )</tt>.</ref>


Example:
Example:
Line 28: Line 28:
|}
|}


Thus, as example, any URI starting with <code>tag:kde.org,2004:KMyMoney:</code> is reserved for KMyMoney.
Thus, as example, any URI starting with <tt>tag:kde.org,2004:KMyMoney:</tt> is reserved for KMyMoney.


; Tip
; Tip
Line 37: Line 37:
== Using http://www.kde.org/ ==
== Using http://www.kde.org/ ==


For KDE's public library technologies it might be of interest to use the <code>kde.org</code> domain. In particular, for XML namespaces. In
For KDE's public library technologies it might be of interest to use the <tt>kde.org</tt> domain. In particular, for XML namespaces. In
those cases, the following practices should be followed:
those cases, the following practices should be followed:


Line 53: Line 53:
: Ensure that the XML format the namespace represents is well defined. As with an API, an XML format is an interface which different parties communicates through. Specify the format in W3C XML Schema or [http://www.relaxng.org/ RELAX NG] (preferrably not DTD since it is less exact), such that it is consciously designed, and not by how a certain application currently happens to read/write files.
: Ensure that the XML format the namespace represents is well defined. As with an API, an XML format is an interface which different parties communicates through. Specify the format in W3C XML Schema or [http://www.relaxng.org/ RELAX NG] (preferrably not DTD since it is less exact), such that it is consciously designed, and not by how a certain application currently happens to read/write files.


== References ==
== Footnotes ==
<references/>
<references/>


[[Category:Policies]]
[[Category:Policies]]

Latest revision as of 15:47, 8 March 2016

Maintainer of this document: Frans Englich

In order to ensure that URI schemes and XML namespaces within the KDE project are consistent and avoids collisions, this document exists to settle best practices, and document the currently used namespaces and URI schemes.

URIs

Some applications needs custom URIs schemes in their implementation. Regardless of if the URI scheme is used internally or publically, it is always an unfortunate design choice to simply make up a scheme name (such as my-scheme://my-data) for the simple reason that anyone can do that, and thus potentially cause interoperability issues and confusion. The approach for creating a custom URI scheme without also getting into trouble[1] is to either ensure the scheme is generic to the extent it can be specified in an RFC (similar to urn or http), or to use an existing scheme which was designed for this purpose: the tag scheme.

The tag scheme combines a host name with a date to create a unique URI scheme (the date makes the URI immune to change in ownership of the domain name). KDE applications can use the tag scheme with the kde.org domain by following a slightly constrained syntax of the tag scheme:

tag:kde.org,2004:[application name]:[application specific string][2]

Example:

tag:kde.org,2004:KMyApplication:MyKApplicationString

The application name ensures that a URI does not clash with a KDE application.

Before using the tag scheme with the KDE domain, the usage should first be suggested on the [email protected] mailinglist. If agreed to be a sensible URI scheme, the table below should be updated to list the application name.

Applications Using the tag Scheme
Application Name Contact Description
KMyMoney [email protected] Not available
KXQTS [email protected] An XML Namespace used in KXQTS' custom test suite format (KDOM).

Thus, as example, any URI starting with tag:kde.org,2004:KMyMoney: is reserved for KMyMoney.

Tip
A URI's design typically stays for a long time -- it can be thought as to be a type of API. Tim Berners-Lee's Cool URIs don't change can perhaps be an inspiration for designing a URI scheme which not only suits the application right now but also years into the future.
One only wants to invent a URI scheme when it is strictly necessary. A reason to that one thinks a new URI scheme needs to be invented, could be that one is unaware of the many existing URI schemes. The article New URI Schemes: 99% Harmful might be worth the reading.
Also, an article by Elliotte Rusty Harold entitled Managing XML data: Tag URIs may turn out useful.

Using http://www.kde.org/

For KDE's public library technologies it might be of interest to use the kde.org domain. In particular, for XML namespaces. In those cases, the following practices should be followed:

  • Be valid URIs, as per RFC 3986.
  • Start with http://www.kde.org/standards/, followed by a name which distinguishes the namespace. After that the resulting string may be extended in anyway (while staying within the constraints of the URI syntax). For example, the namespace http://www.kde.org/standards/kcfg/2.0 as well as http://www.kde.org/standards/KTechnology/ are valid.
URI        : http://www.kde.org/standards/kcfg/1.0
Description: KConfigXT's *.kcfg files.
Schema     : http://www.kde.org/standards/kcfg/1.0/kcfg.xsd
Contact    : Frans Englich <[email protected]>

Addition of a new namespace should be suggested on [email protected] mailinglist. If the namespace is decided to be included, this document should be updated to list the new namespace.

Tip
Ensure that the XML format the namespace represents is well defined. As with an API, an XML format is an interface which different parties communicates through. Specify the format in W3C XML Schema or RELAX NG (preferrably not DTD since it is less exact), such that it is consciously designed, and not by how a certain application currently happens to read/write files.

Footnotes

  1. However, due to the usability requirements KDE in some cases have, there can be circumstances where a rogue scheme(such as media://) makes sense. Carefully consider(discuss, seek peer review) before going for an invalid URI scheme, and if so, ensure technical measures are done to lower the risks of complication.
  2. Formally speaking, the ABNF product specific in RFC 4151 is augmented into applicationName ":" applicationSpecific, where both <classname>applicationName</classname> and applicationSpecific is *( pchar / "/" / "?" ).