[ncc-services-wg] Organisation Object Proposal, version 3

Dear Colleagues,

[apologies for duplicate messages]

After the discussions we had in the RIPE 46 Meeting and in the
WG mailing lists, we have incorporated agreed modifications
into organisation object proposal, which you can find below.
This is the Version 3 of the proposal.

You can find the first version at
 http://www.ripe.net/ripe/mail-archives/db-wg/2003/msg00013.html

the second version at
 http://www.ripe.net/ripe/mail-archives/db-wg/2003/msg00159.html

and a summary of discussions on the second version at
 http://www.ripe.net/ripe/mail-archives/db-wg/2003/msg00213.html

Thank you very much for your input on the issue.

Best regards,
--
Engin Gunduz
RIPE NCC Database Group




============================================================

An organisation object in the RIPE Database
--------------------------------------------


1. Motivation
-------------------

Currently the RIPE Database stores two main types of contact
information: person and role objects.

The person and role objects provide a way to contact people responsible 
for operations or usage of the resources represented in the RIPE Database
(IP blocks, autonomous systems, and domain names).

However, none of these provide an easy way of mapping resources to a
particular organisation. A user must first find an object containing 
contact information for that organisation. Then, assuming all of the 
organisation's objects refer to this contact information, the user must 
perform an inverse query to obtain a list of objects referencing the 
specified person or role.

This indirect process can be somewhat obscure and therefore a request for a 
more direct way of attaching an object to an organisation is seen as a 
useful addition to the RIPE Database.

This document is a proposal for an organisation object in the RIPE Database 
and the necessary database functionality.

2. The organisation object
-----------------------

The organisation object provides information identifying an organisation
such as a company, charity or university, that is a holder of a network 
resource whose data is stored in the RIPE Database.

The organisation object is identified by a unique ID specified in the
"organisation:" attribute which is the primary key.

An organisation object can be referenced from other objects using
an "org:" attribute. 

All objects associated with a particular organisation ID can be retrieved by
performing an "inverse query" for this ID used in the "org:" attribute of
database objects.

Following is a template for the proposed organisation object and an
example.  All attributes except the "ref-nfy:", "mnt-ref:", "organisation:",
"org-name:", "org-type:" and "org:" have their usual meanings.

organisation:  [mandatory]  [single]     [primary/look-up key]
org-name:      [mandatory]  [single]     [look-up key]
org-type:      [mandatory]  [single]     [ ]
descr:         [optional]   [multiple]   [ ]
remarks:       [optional]   [multiple]   [ ]
address:       [mandatory]  [multiple]   [ ]
country:       [mandatory]  [single]     [ ]
phone:         [optional]   [multiple]   [ ]
fax-no:        [optional]   [multiple]   [ ]
e-mail:        [mandatory]  [multiple]   [look-up key]
org:           [optional]   [multiple]   [inverse key]
admin-c:       [mandatory]  [multiple]   [inverse key]
tech-c:        [mandatory]  [multiple]   [inverse key]
ref-nfy:       [optional]   [multiple]   [inverse key]
mnt-ref:       [mandatory]  [multiple]   [inverse key]
notify:        [optional]   [multiple]   [inverse key]
mnt-by:        [mandatory]  [multiple]   [inverse key]
changed:       [mandatory]  [multiple]   [ ]
source:        [mandatory]  [single]     [ ]

3. New attributes
----------------------

"organisation:"

Specifies the ID of an organisation object.  An organisation ID is
made up of 'ORG-' prefix, followed by 2 to 4 letters, digits, a dash and is
followed by the database source (in the RIPE Whois Database this is
'RIPE').  For example:

 ORG-RT34-RIPE

Note that all parts are mandatory, thus ORG-RT-RIPE would be an invalid ID
as it is missing the numeric part.

Organisation object IDs are auto-generated similar to the way person/role
"nic-hdl:" attributes are auto-generated.  The user has to specify the ID of
an organisation object as ORG-AUTO-<digit> during creation of the object,
then it will be assigned an appropriate ID.  The organisation ID is assigned
using the "org-name:" attribute of the object.  The user can specify the
letter combination he/she prefers.  For example if the user wants TTR as the
letter combination, in the organisation ID, then ORG-AUTO-1TTR should be 
put into "organisation:" attribute during the creation of the object.

The organisation ID cannot be reused.  If an organisation ID was used in the
past by an organisation object and then deleted, this ID cannot be used in
new organisation objects.

The auto-generation of organisation IDs and preventing reuse of them
simplifies the external references.  Note that when an organisation changes
name, the "org-name:" can be modified accordingly.  There is no need to
change the organisation ID.

"org-name:"

Specifies the name of the organisation that this organisation object
represents in the whois database.  This is an ASCII-only text attribute.  The
restriction is because this attribute is a look-up key and the whois
protocol does not allow specifying character sets in queries.  The user can
put the name of the organisation in non-ASCII character sets in the
"descr:" attribute if required.

"org-type:"

Specifies the type of the organisation.  The possible values are 'IANA' for
Internet Assigned Numbers Authority, 'RIR' for Regional Internet
Registries, 'NIR' for National Internet Registries, 'LIR' for Local
Internet Registries, and 'NON-REGISTRY' for all other organisations.

"ref-nfy:"

Specifies the e-mail address to be notified when a reference to the
organisation object is added or removed.  An e-mail address as defined
in RFC 2822.

"mnt-ref:"

Specifies the maintainer objects that are entitled to add references to
the organisation object from other objects.

"country:"

Specifies the two-letter ISO3166 country code of the country where this 
organisation resides.

"address:"

Specifies the address of the organisation.  This is a free-text attribute.

"org:"

May be included in any object type.  It points to an existing
organisation object representing the entity that holds the resource,
in the cases where the whois DB object represents an Internet resource. 
In other objects, it can be used to specify the business relations.  The
value of this attribute is the ID of the organisation object.  It is
mandatory in the inetnum and inet6num objects with "ALLOCATED-BY-IANA",
"ALLOCATED-BY-RIR", "ALLOCATED-BY-RIR NON-PORTABLE", "ALLOCATED-BY-RIR
PORTABLE" and "ALLOCATED-BY-RIR UNSPECIFIED" values.  It is optional
in all other objects. 

"org:" attribute is single-valued in the inetnum, inet6num and aut-num
objects, and it is multi-valued all other objects.  The "org:" attribute
is used to specify the holder of a resource in inetnum, inet6num and aut-num
objects, thus it must be single-valued in them.  In other objects, it
specifies business relations (like in a person object, where it can be
used to specify whom the person works for) it can be multiple (in the person
object example, a person might work for several companies).


4. Authorisation checks
----------------------------------

When modifying an organisation object the update must pass authorisation
checks specified by one of the mntners listed in the "mnt-by:"
attributes of the organisation object.

When adding an "org:" attribute to an object, the update of the object
should pass the following authorisation checks:

 - from one of the maintainers in the "mnt-ref:" attributes of 
     the organisation object
 - from one of the maintainers in the "mnt-by:" attributes of
     the object being updated


5. Query changes
----------------

If a whois query returns an object with an "org:" attribute, the
organisation object mentioned in this attribute is also appended to the
query results.  This behaviour can be disabled by using the '-r' flag in the
query.


6. Examples
------------

A basic organisation object:

organisation: ORG-RSIS54-RIPE
org-name:     Random Street Internet Services
org-type:     LIR
descr:        An example organisation
address:      Random St.
country:      NL
phone:        +31 123 4567
fax-no:       +31 123 4568
e-mail:       contact at example-org.net
admin-c:      EXAM1-RIPE
tech-c:       EXAM2-RIPE
notify:       ripe-mailbox at example-org.net
ref-nfy:      ripe-mailbox at example-org.net
mnt-ref:      EXAMPLE-MNT
mnt-by:       EXAMPLE-MNT
changed:      someguy at example-org.net 20030121
source:       RIPE

A network that references an organisation object:

inetnum:      192.168.86.0 - 192.168.86.255
netname:      EXAMPLE-NET-86
descr:        Sample network
org:          ORG-RSIS54-RIPE
country:      NL
admin-c:      JE1-RIPE
tech-c:       JE2-RIPE
status:       ALLOCATED-BY-RIR PORTABLE
mnt-by:       EXAMPLE-MNT
mnt-lower:    EXAMPLE-MNT
changed:      someguy at example-org.net 20030122
source:       RIPE

A query for this inetnum object:

% whois 192.168.86.251

inetnum:      192.168.86.0 - 192.168.86.255
netname:      EXAMPLE-NET-86
descr:        Sample network
org:          ORG-RSIS54-RIPE
country:      NL
admin-c:      JE1-RIPE
tech-c:       JE2-RIPE
[...]
source:       RIPE

organisation: ORG-RSIS54-RIPE
org-name:     Random Street Internet Services
org-type:     LIR
descr:        An example organisation
address:      Random St.
address:      The Netherlands
phone:        +31 123 4567
fax-no:       +31 123 4568
e-mail:       contact at example-org.net
admin-c:      EXAM1-RIPE
tech-c:       EXAM2-RIPE
[...]
source:       RIPE

person:       John Example
nic-hdl:      JE1-RIPE
[...]
source:       RIPE

person:       John Example Jr
nic-hdl:      JE2-RIPE
[...]
source:       RIPE