ALPS Registry Guidelines

One role of ALPS registries is to make it easy to locate and refer to shared ALPS profiles. A robust ecosystem of registries is important to increasing the re-use of ALPS profiles. By creating common locations where ALPS documents can be found and referenced makes it more likely those profiles and extensions will be re-used.

An ALPS profile is most useful when is describes a service in a way that supports multiple use. In other words, a description that more than one server can implment without making any changes to the ALPS profile. The more often a single ALPS profile is used in an implementation on the Web, the more valuable that singlie profile becomes.

While profile re-use is important, the ALPS registry model is not meant to enforce a single source for all shared ALPS profiles. These guidelines exist to help anyone who wishes to establish and maintain their own ALPS reigstry for whatever reason (See Guidelines for Establishing an ALPS Registry below).

There are a number of possible reasons for establishing an ALPS registry:

For whatever the reason, individuals or organizations are free to establish and maintain there own ALPS registries and are strongly encouraged follow the guidelines spelled out in this document.

The 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 RFC2119[1].

An ALPS registry is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements is said to be "conditionally compliant." All ALPS Registries SHOULD strive to be "unconditionally compliant" implementations (See Compliance Review below).

The aim of ALPS Profile Registries (APRs) is to provide a collaborative repository for sharing profile and extension documents. Since a key goal for the ALPS specification[0] is to increase "shared understanding" between client and service implementors, an open place where ALPS documents can be shared and referenced is important.

It is also important that the spirit of APRs is one of mutual support. APRs should not become barriers to those who wish to contribute profiles. Those who lead and maintain APR communities should not act as ‘gatekeepers’ or as blocking factors for those who want to contribute profiles. To quote David Clark[6]:

It is also important to remember that registering profiles and extensions in APRs is RECOMMENDED, but NOT REQUIRED. There may base cases where profiles will be used, but not shared. While this is not within the spirit of ALPS in general, that’s OK.

It is also important that APRs are stable, reliable. Those hosting and maintaining profiles and extensions take on the responsibilty to maintain a service that is both available and responsive. APR maintainers should take all necessary steps to keep their service up and running.

They should also work to reduce the chance of "breakage" for existing profiles and extensions. That means APRs should make it ‘hard’ for authors to modify registered profiles and extensions in ways that will introduce backware incompatibilities. It is RECOMMENDED that maintainers institute review processes that reduce breakage and encourage profile and extension authors to keep this uppermost in mind when creating and updating their ALPS documents.

This document is a a charter to create at least one ‘primary’ APR to hold as many avaialble profile and extension documents as possible. A link to this primary registry SHOULD appear on the ALPS website (http://alps.io). The role of this primary registry is to act as a place where the spirit of ALPS and the guidelines listed here are promoted and protected. It can also act as a place where those interested in learning more about ALPS and find helpful material and an opportunity to participate in the maintenance of the APR.

This document is also meant to be a guide to those who with to start their own ALPS Profile Repositories. There is not limit to the number of APRs that may exist. There are no special qualifications needed for those willing to host a repository and there are not permissions needed in order to do so.

However, once an APR is created, those hosting it have a responsbility to continue to maintain it in a responsible and reliable manner. Since it is possible that developers will rely in the APR to serve up ALPS documents in order to keep their applications running properly, APR maintainers have a duty to continue to respond to ALPS document requests well into the future. See Guidelines for Establishing An ALPS Registry for details on the proper creation and maintenance of APRs.

[TK describe typical process for adding including data to collect, data to reflect, and support for both XML and JSON representations]

[TK describe typical process for adding including data to collect, data to reflect, and support for both XML and JSON representations]

[TK encourage use of tagging to categorize profiles. not hierarchy, folksonomies references here.]

[TK describe ways to search for profiles (tags, titles, doc contents, etc.]

[TK describe possible support for crawlers that might be created to gather ALPS info and publish it in a searchable form. (does this really go here?)]

[TK announce on the primary list: https://groups.google.com/forum/?fromgroups=#!forum/alps-io]

[TK describe process of requesting review on the primary list, what the review should entail, that reviews are *optional*]

[TK the primary newgroup and the website are sources of general contact and support. Each registry SHOULD also create their own modes of support and post on the registry web site.]