Repository URI Syntax

Version 0.3

Overview

The key aims of this proposal are:

Open Issues

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 "/"

Access 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

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

URI examples: {{{ http://repo.apache.org/

Product specifier

The product specifier specifies the organisation and project:

{{{ product-specifier = organisation "/" project

<organisation> is the organisation name. It is arbitrary, but should be globally unique. It could be the domain name, reverse domain name, or simply the name of the organisation. Individuals MAY choose to create a unique name based upon, for instance, their website or email address. E.g: {{{ "apache.org", "org.apache", "apache"

<project> is the project name. It is unique within an organisation. If the artifact is a sub-project of a larger project, or is unique in some way, include that information in the name. For example, if an artifact is part of the "bar" project, which is a sub-project of "foo", then the project would be named "foo-bar". E.g:

 "ldap", "jndi", "maven", "commons-net". 

URI examples: {{{ http://repo.apache.org/apache.org/ant

Version specifier

The version specifier specifies the version of the project:

   version-specifier = path_segments 

For the purposes of this proposal, version-specifier is opaque - its format is determined by language and deployment best practices.

Some possible examples include:  "1.0", "v0.9-beta", "nightly/20031113", "latest", "release/1.5.4", "chicago" 

URI examples: {{{ http://repo.apache.org/apache/commons-logging/1.0

Artifact specifier

The artifact specifier uniquely identifies an artifact within a project version:   artifact-specifier = path_segments 

For the purposes of this proposal, artifact-specifier is opaque - its format is determined by language and deployment best practices.

Some possible examples include: {{{ jars/commons-logging-1.1.jar

URI examples: {{{ http://repo.apache.org/apache/common-logging/1.1/jars/commons-logging-1.1.jar

Rationale

URI Components

Of the URI components:

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.

Single segment for <organisation> and <project>

The <organisation> and <project> parts of product-specifier MUST each be a single path segment. i.e neither may contain embedded "/". This restriction enables tools to differentiate between product-specifier and version-specifier.

Artifacts

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 MUST 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 and deployment scenario.

Mandatory version

All repository URIs MUST include a version in the path. This:

See Also

Language

The uppercase key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Appendix

Changes from 0.2

Changes from 0.1

ASFRepository/URISyntax (last edited 2009-09-20 23:32:14 by localhost)