[proposal] URI Syntax - v0.1

[Tim Anderson <tm...@netspace.net.au>]

Overview
--------

The key aims of this proposal are:
. language and artifact neutrality.
  It should be possible to support multiple languages and
  their artifacts, not just java.

. it be useful to end-users and tools

  . it should be possible for users to easily navigate
    the repository and locate artifacts, including
    jars and release distributions.
    Compare this with the existing approach of separating
    release distributions (http://www.apache.org/dist/) and jars
    (http://www.ibiblio.org/maven).

  . it should be possible for tools to resolve dependencies
    on other artifacts

Artifacts
---------

All files in the repository are artifacts. There is no distinction
between artifacts and meta-data. Any relationships between artifacts
is determined by supporting tools.


Repository URI Components
-------------------------

An absolute repository URI is written as follows:

  repository-uri = access-specifier "/" product-specifier "/"
                   artifact-specifier

The access specifier determines the scheme, authority, and optional
repository directory prefix. There is currently no requirement for
ftp, scp or file based access - only http is supported:

  access-specifier = http-access-specifier
  http-access-specifier = "http://" authority "/" [directory "/"]

<directory> is used when the repository cannot be located at
the root of an absolute URI:

  directory = path_segments
  (path_segments is per http://www.ietf.org/rfc/rfc2396.txt)

The product specifier specifies the organisation, project
and version:

  product-specifier = organisation "/" project "/" version
  organisation = *pchar
  project = *pchar
  version = *pchar
  (pchar is per http://www.ietf.org/rfc/rfc2396.txt)

<organisation> is the organisation name. It is arbitrary,
but should be globally unique. It could be the domain name,
e.g "sun.com", the reverse domain name e.g "org.apache", or
simply the name of the organisation, e.g "oracle".

<project> is the project name. It is unique within an organisation.
E.g, "ldap", "jndi", "maven", "commons-logging".

<version> is the version of the project, and is arbitrary.
e.g: "v0.9-beta", "1.5.4"


The artifact specifier uniquely identifies an artifact within a
product:
  artifact-specifier = [type "/"][platform "/"]<artifact>
  type = *pchar
  platform = *pchar

<type> is optional and arbitrary, determined by the repository
deployment tool. E.g: "jars", "binaries", "docs" etc.

<platform> is optional and arbitrary, determined by the
deployment tool. E.g, "linux", "solaris", "win32"

<artifact> is determined by the deployment tool, and includes
the artifact name. It may also include:
. version            - should be identical to that in <product>
. platform           - arbitrary e.g "-s390-ibm-linux", "-win32"
. artifact type      - arbitrary e.g. "-src", "-bin"
. extension          - file extension e.g. ".tar.gz", ".xml"


Rationale
---------

Of the URI components, <access-specifier> and <product-specifier>
are common accross all languages. <artifact-specifier> is language,
artifact, or even project specific.

It is envisioned that there will be different repository deployment
and query tools developed for each language. A generic tool cannot
be written without providing supporting meta-data, which is outside
the scope of this proposal.

Projects should be able to deploy arbitrary artifacts to the
repository, whether they be for end-users, or meta-data (e.g, maven's
project.xml). Tools should ignore any artifact they don't understand.

To ensure interoperability between language-based tools, best-practice
guidelines need to be drawn up for each supported language.

Alternatives
------------

Alternative for <organisation>:
  Jason van Zyl has proposed replacing <organisation> with <groupId>

http://nagoya.apache.org/eyebrowse/ReadMsg?listName=repository@apache.org&ms
gNo=268

  "What we've discussed in Maven-land is using something like a groupId
  which might look like: org.apache.maven and actually split on the dot to
  make a directory. So basically organization by FQDN. Something which
  would also make indexing easier in filesystems and I think makes it
  easier to navigate by a person."

  Comments against this proposal:

http://nagoya.apache.org/eyebrowse/ReadMsg?listName=repository@apache.org&ms
gNo=276

http://nagoya.apache.org/eyebrowse/ReadMsg?listName=repository@apache.org&ms
gNo=278

Alternatives for <version>:
  Some comments have indicated that <version> should be dropped from
  <product-specifier>, requiring instead its inclusion in the artifact
  name.
  While <version> may be included in the artifact name, this:
  . makes the repository harder to navigate by users, as all
    artifacts from all versions of a project will appear in the
    one directory.
  . makes it harder for tools to parse version information from
    an artifact specifier.

  Other comments have indicated that <version> should be included
  within <artifact-specifier>, e.g:

http://nagoya.apache.org/eyebrowse/ReadMsg?listName=repository@apache.org&ms
gNo=279

  Inclusion of the version should be seen as language and artifact
  specific, i.e, dependent on the deployment tool. It may not make
  sense for all artifacts, e.g:

http://nagoya.apache.org/eyebrowse/ReadMsg?listName=repository@apache.org&ms
gNo=303