2004/id/draft-ietf-uri-url-irp-05.txt

IETF URI Working Group                                        R. Denenberg
Internet-Draft                                                J. Kunze
draft-ietf-uri-url-irp-05.txt                                 D. Lynch
10 June 1996                                                  Editors


                  Uniform Resource Locators for Z39.50


1. Status of this Document

This document is an Internet-Draft.  Internet-Drafts are working documents
of the Internet Engineering Task Force (IETF), its Areas, and its Working
Groups.  Note that other groups may also distribute working documents as
Internet-Drafts.

Internet-Drafts are working documents valid for a maximum of six months.
Internet-Drafts may be updated, replaced, or obsoleted by other documents
at any time.  It is not appropriate to use Internet-Drafts as reference
material or to cite them other than as a ``working draft' or ``work in
progress.''

To learn the current status of any Internet-Draft, please check the
1id-abstracts.txt listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or
munnari.oz.au.

Distribution of this document is unlimited.  Please send comments to
jak@violet.berkeley.edu, or to the discussion lists uri@bunyip.com and
z3950iw@nervm.nerdc.ufl.edu.


2. Introduction

Z39.50 is an information retrieval protocol that does not fit neatly into
a retrieval model designed primarily around the stateless fetch of data.
Instead, it models a general user inquiry as a session-oriented, multi-
step task, any step of which may be suspended temporarily while the
server requests additional parameters from the client before continuing.
Some, none, or all of these client/server interactions may require
participation of the client user, depending only on the client software
(the protocol itself makes no such requirements).

On the other hand, retrieval of "well-known" data may be performed in
a single step, that is, with a degenerate Z39.50 session consisting of
exactly one protocol search request and response.  Besides the basic
search sub-service, there are several ancillary sub-services (e.g., Scan,
Result Set Delete).  Among the functions covered by combinations of the
sub-services, two core functions emerge as appropriately handled by two
separate URL schemes:  the Session URL and the Retrieval URL.

Using two schemes instead of one makes a critical distinction between a
Z39.50 Session URL, which opens a client session initialized for
interactive use by the user, and a Z39.50 Retrieval URL, which opens and
closes a client session to retrieve a specific information item.  Making
this distinction at the scheme level allows the user interface to reflect
it on to the user, without requiring the user interface to parse otherwise
opaque parts of the URL (consistent with current practice).   


3. Some Basic Concepts

This section briefly describes the usage of Z39.50-specific terminology
within the URL definitions below: specifically, the terms database,
elementset, recordsyntax, and docid.

The Z39.50 protocol specifies various information retrieval operations,
the two most basic of which are Search and Present. In a Search operation
a client provides search criteria and indicates a database (or several
databases) on the server to search.  The essential result of a Search
operation is that a result set is created at the server, consisting of
pointers to the selected database records.

Z39.50 models database records, abstract database records, and retrieval
records.  A database record is a unit of information in a database,
represented in a data structure local to the server.  An abstract database
record is an abstract representation of that information, where the client
and server share a common understanding of the representation.  This allows
logical elements to be addressed and selected for transfer, via an element
set specification, or, as used below, an "elementset".  A retrieval record
is the set of selected elements packaged in an exportable structure,
by the application of a "recordsyntax".

Thus a Search operation results in entries pointing to database records;
via a Present operation, a client requests a retrieval record, corresponding
to a database record, corresponding to an entry in the result set. The client
indicates the composition and format of the retrieval record by specifying
an elementset and recordsyntax, respectively.

A special case of a Z39.50 search is a "known-item" search, when a client
intends that a search identify a single, known database record, or "document"
(for purposes of illustration, assume that a database record corresponds
to a document), and further, the client knows an identifier for the document
that can be used to effect this known-item search.  In this case, this
identifier is often referred to as a document identifier, or "docid". 


4. The Z39.50 Session URL

The Z39.50 Session URL may be informally described as providing the 
mechanism to switch the user to a Z39.50 client application. 

   -  Host is required.
   -  Port is optional, and defaults to 210.
   -  All other parameters are optional.
   -  The Z39.50 client will start a session to the specified host/port
      (alternatively, it need not explicitly start a session, but may
      instead utilize an already open session to the same host/port).
   -  A database must be included if docid is included.
   -  If docid is included, the client will perform the specified search
      (in the same manner as for the retrieval URL, specified below).
   -  If docid is not included, and other parameters (besides host/port)
      are specified, the client may use those parameters as "hints".
      Various clients may choose to treat them as requirements, or as
      preferences, or ignore them.
   -  In any case (whether a search is performed or not), the client will
      leave the Z39.50 session open for the user, to do retrievals, new
      searches, etc.  (This is the main distinction from the Retrieval URL 
      which leaves it up to the client whether or not to keep the Z39.50 
      session open.)


5. The Z39.50 Retrieval URL

The Z39.50 Retrieval URL is intended to allow a Z39.50 session to be used as
a transparent transfer mechanism to retrieve a specific information object.
A Z39.50 client uses information in the URL to formulate a Search Request.
The server's Search Response indicates how many records match the Request.
If the number of matching records does not equal one, the retrieval is
considered unsuccessful, and the client application's behavior is not defined.
If the number of matching records equals one, the server may have included
the desired record in the Search Response.  If not, the client requests
transmission of the record with a Present Request.  After the client has
received the specified record it may close the Z39.50 session immediately,
or keep it open for subsequent retrievals.    

   -  Host is required.
   -  Port is optional, and defaults to 210.
   -  A database is required.
   -  The meaning of a retrieval URL with no docid is undefined.
   -  The docid is placed into a type-1 query, as the single term, in
      the general format (tag 45), using the Bib-1 attribute set, with
      a Use attribute value of docid, and a structure attribute of URx.
      The docid string is server-defined and completely opaque to the client.
   -  If element set name (esn) is not specified, it is the client's choice.
      If esn is specified, it should be used either in the Search
      request for the value of small- and/or medium- set-element-set-names
      or in a Present request following a Search.  These terms and their
      use are defined within the Z39.50 Standard [2].
   -  If record syntax (rs) is not specified, it is the client's choice.
      If one or more record syntaxes are specified, the client should select
      one (preferably the first in the list that it supports) and use it in
      a Search or Present request as the value of PreferredRecordSyntax.


6. BNF for Z39.50 URLs

The Z39.50 Session and Retrieval URLs follow the Common Internet Scheme
Syntax as defined in RFC 1738, "Uniform Resource Locators (URL)" [1].
In the definition, literals are quoted with "", optional elements
are enclosed in [brackets], "|" is used to designate alternatives,
and elements may be preceded with <n>* to designate n or more
repetitions of the following element; n defaults to 0.  

z39.50url      = zscheme "://" host [":" port]
                      ["/" [database *["+" database]
                             ["?" docid]]
                           [";esn=" elementset]
                           [";rs=" recordsyntax *[ "+" recordsyntax]]]

zscheme        = "z39.50r" | "z39.50s"
database       = uchar
docid          = uchar
elementset     = uchar
recordsyntax   = uchar

Future extensions to these URLs will be of the form of [;keyword=value].

The following definitions are from RFC 1738. Between the Internet Draft
version and RFC 1738 two relevant changes were made: '=' was moved from
the <extra> character class to <reserved>, and <national> was removed from
the alternatives in <unreserved>. Neither <national> nor <punctuation> is
referred to in this document nor in RFC 1738.

lowalpha       = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
                 "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
                 "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
                 "y" | "z"
hialpha        = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
                 "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
                 "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"

alpha          = lowalpha | hialpha
digit          = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
                 "8" | "9"
safe           = "$" | "-" | "_" | "." | "+"
extra          = "!" | "*" | "'" | "(" | ")" | ","
national       = "{" | "}" | "|" | "\" | "^" | "~" | "[" | "]" | "`"
punctuation    = "<" | ">" | "#" | "%" | <">

reserved       = ";" | "/" | "?" | ":" | "@" | "&" | "="
hex            = digit | "A" | "B" | "C" | "D" | "E" | "F" |
                 "a" | "b" | "c" | "d" | "e" | "f"
escape         = "%" hex hex
unreserved     = alpha | digit | safe | extra
uchar          = unreserved | escape
xchar          = unreserved | reserved | escape
digits         = 1*digit

7. Security Considerations

The two Z39.50 URL schemes are subject to the same security implications
as the general URL scheme [1], so the usual precautions apply.  This means,
for example, that a locator might no longer point to the object that was
originally intended.  It also means that it may be possible to construct
a URL so that an attempt to perform a harmless idempotent operation such
as the retrieval of an object will in fact cause a possibly damaging
remote operation to occur.


8. Acknowledgements

The Z39.50 Implementors Group contributed the substance of this document.


9. References

   [1] Berners-Lee, T., Masinter, L., McCahill, M. (editors), "Uniform
       Resource Locators (URL)", RFC 1738, December 1994.
       ftp://ds.internic.net/rfc/rfc1738.txt

   [2] ANSI/NISO Z39.50-1995, "ANSI Z39.50:  Information Retrieval Service
       and Protocol", 1995.  ftp://ftp.loc.gov/pub/z3950/

   [3] ANSI/NISO Z39.50-1992, "ANSI Z39.50:  Information Retrieval Service
       and Protocol", 1992.
       ftp://ftp.cni.org/pub/NISO/docs/Z39.50-1992/www/Z39.50.toc.html
       (also available in hard copy from Omnicom Information Service,
       115 Park St., SE, Vienna, VA  22180).


10. Editors' Addresses

Ray Denenberg
Library of Congress
Collections Services
Network Development/MSO
Washington DC 20540
ray@rden.loc.gov
Voice: (202) 707-5795
Fax:   (202) 707-0115

John A. Kunze
Center for Knowledge Management
University of California, San Francisco
530 Parnassus Ave, Box 0840
San Francisco, CA  94143-0840
jak@ckm.ucsf.edu
Voice: (415) 502-6660
Fax:   (415) 476-4653

SilverPlatter Information Ltd.
10 Barely Mow Passage
Chiswick, London W4 4PH
U.K.
DenisL@SilverPlatter.com
Voice: +44 (0)181-995-8242
FAX:   +44 (0)181-995-5159


Appendix. Examples of Z39.50 URLs

A basic Z39.50 session URL that a client might use to open a connection
to the MELVYL union catalog "cat" at the University of California is

        z39.50s://melvyl.ucop.edu/cat

A URL that would open the MELVYL magazine database just long enough
to fetch an article from volume 30, number 19 of a hypothetical
periodical might look like

        z39.50r://melvyl.ucop.edu/mags?elecworld.v30.n19

As a final example, here is another retrieval URL that a client could
use to request a full record (element set "f") in the MARC syntax from
a hypothetical database called TMF at CNIDR:

        z39.50r://cnidr.org:2100/tmf?bkirch_rules__a1;esn=f;rs=marc

As in the previous example, the part of the string after the `?' is
determined by the server.  In this example, the server is running on
non-standard port 2100.
1	IETF URI Working Group R. Denenberg
2	Internet-Draft J. Kunze
3	draft-ietf-uri-url-irp-05.txt D. Lynch
4	10 June 1996 Editors
5
6
7	Uniform Resource Locators for Z39.50
8
9
10	1. Status of this Document
11
12	This document is an Internet-Draft. Internet-Drafts are working documents
13	of the Internet Engineering Task Force (IETF), its Areas, and its Working
14	Groups. Note that other groups may also distribute working documents as
15	Internet-Drafts.
16
17	Internet-Drafts are working documents valid for a maximum of six months.
18	Internet-Drafts may be updated, replaced, or obsoleted by other documents
19	at any time. It is not appropriate to use Internet-Drafts as reference
20	material or to cite them other than as a ``working draft' or ``work in
21	progress.''
22
23	To learn the current status of any Internet-Draft, please check the
24	1id-abstracts.txt listing contained in the Internet-Drafts Shadow
25	Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or
26	munnari.oz.au.
27
28	Distribution of this document is unlimited. Please send comments to
29	jak@violet.berkeley.edu, or to the discussion lists uri@bunyip.com and
30	z3950iw@nervm.nerdc.ufl.edu.
31
32
33	2. Introduction
34
35	Z39.50 is an information retrieval protocol that does not fit neatly into
36	a retrieval model designed primarily around the stateless fetch of data.
37	Instead, it models a general user inquiry as a session-oriented, multi-
38	step task, any step of which may be suspended temporarily while the
39	server requests additional parameters from the client before continuing.
40	Some, none, or all of these client/server interactions may require
41	participation of the client user, depending only on the client software
42	(the protocol itself makes no such requirements).
43
44	On the other hand, retrieval of "well-known" data may be performed in
45	a single step, that is, with a degenerate Z39.50 session consisting of
46	exactly one protocol search request and response. Besides the basic
47	search sub-service, there are several ancillary sub-services (e.g., Scan,
48	Result Set Delete). Among the functions covered by combinations of the
49	sub-services, two core functions emerge as appropriately handled by two
50	separate URL schemes: the Session URL and the Retrieval URL.
51
52	Using two schemes instead of one makes a critical distinction between a
53	Z39.50 Session URL, which opens a client session initialized for
54	interactive use by the user, and a Z39.50 Retrieval URL, which opens and
55	closes a client session to retrieve a specific information item. Making
56	this distinction at the scheme level allows the user interface to reflect
57	it on to the user, without requiring the user interface to parse otherwise
58	opaque parts of the URL (consistent with current practice).
59
60
61	3. Some Basic Concepts
62
63	This section briefly describes the usage of Z39.50-specific terminology
64	within the URL definitions below: specifically, the terms database,
65	elementset, recordsyntax, and docid.
66
67	The Z39.50 protocol specifies various information retrieval operations,
68	the two most basic of which are Search and Present. In a Search operation
69	a client provides search criteria and indicates a database (or several
70	databases) on the server to search. The essential result of a Search
71	operation is that a result set is created at the server, consisting of
72	pointers to the selected database records.
73
74	Z39.50 models database records, abstract database records, and retrieval
75	records. A database record is a unit of information in a database,
76	represented in a data structure local to the server. An abstract database
77	record is an abstract representation of that information, where the client
78	and server share a common understanding of the representation. This allows
79	logical elements to be addressed and selected for transfer, via an element
80	set specification, or, as used below, an "elementset". A retrieval record
81	is the set of selected elements packaged in an exportable structure,
82	by the application of a "recordsyntax".
83
84	Thus a Search operation results in entries pointing to database records;
85	via a Present operation, a client requests a retrieval record, corresponding
86	to a database record, corresponding to an entry in the result set. The client
87	indicates the composition and format of the retrieval record by specifying
88	an elementset and recordsyntax, respectively.
89
90	A special case of a Z39.50 search is a "known-item" search, when a client
91	intends that a search identify a single, known database record, or "document"
92	(for purposes of illustration, assume that a database record corresponds
93	to a document), and further, the client knows an identifier for the document
94	that can be used to effect this known-item search. In this case, this
95	identifier is often referred to as a document identifier, or "docid".
96
97
98	4. The Z39.50 Session URL
99
100	The Z39.50 Session URL may be informally described as providing the
101	mechanism to switch the user to a Z39.50 client application.
102
103	- Host is required.
104	- Port is optional, and defaults to 210.
105	- All other parameters are optional.
106	- The Z39.50 client will start a session to the specified host/port
107	(alternatively, it need not explicitly start a session, but may
108	instead utilize an already open session to the same host/port).
109	- A database must be included if docid is included.
110	- If docid is included, the client will perform the specified search
111	(in the same manner as for the retrieval URL, specified below).
112	- If docid is not included, and other parameters (besides host/port)
113	are specified, the client may use those parameters as "hints".
114	Various clients may choose to treat them as requirements, or as
115	preferences, or ignore them.
116	- In any case (whether a search is performed or not), the client will
117	leave the Z39.50 session open for the user, to do retrievals, new
118	searches, etc. (This is the main distinction from the Retrieval URL
119	which leaves it up to the client whether or not to keep the Z39.50
120	session open.)
121
122
123	5. The Z39.50 Retrieval URL
124
125	The Z39.50 Retrieval URL is intended to allow a Z39.50 session to be used as
126	a transparent transfer mechanism to retrieve a specific information object.
127	A Z39.50 client uses information in the URL to formulate a Search Request.
128	The server's Search Response indicates how many records match the Request.
129	If the number of matching records does not equal one, the retrieval is
130	considered unsuccessful, and the client application's behavior is not defined.
131	If the number of matching records equals one, the server may have included
132	the desired record in the Search Response. If not, the client requests
133	transmission of the record with a Present Request. After the client has
134	received the specified record it may close the Z39.50 session immediately,
135	or keep it open for subsequent retrievals.
136
137	- Host is required.
138	- Port is optional, and defaults to 210.
139	- A database is required.
140	- The meaning of a retrieval URL with no docid is undefined.
141	- The docid is placed into a type-1 query, as the single term, in
142	the general format (tag 45), using the Bib-1 attribute set, with
143	a Use attribute value of docid, and a structure attribute of URx.
144	The docid string is server-defined and completely opaque to the client.
145	- If element set name (esn) is not specified, it is the client's choice.
146	If esn is specified, it should be used either in the Search
147	request for the value of small- and/or medium- set-element-set-names
148	or in a Present request following a Search. These terms and their
149	use are defined within the Z39.50 Standard [2].
150	- If record syntax (rs) is not specified, it is the client's choice.
151	If one or more record syntaxes are specified, the client should select
152	one (preferably the first in the list that it supports) and use it in
153	a Search or Present request as the value of PreferredRecordSyntax.
154
155
156	6. BNF for Z39.50 URLs
157
158	The Z39.50 Session and Retrieval URLs follow the Common Internet Scheme
159	Syntax as defined in RFC 1738, "Uniform Resource Locators (URL)" [1].
160	In the definition, literals are quoted with "", optional elements
161	are enclosed in [brackets], "\|" is used to designate alternatives,
162	and elements may be preceded with <n>* to designate n or more
163	repetitions of the following element; n defaults to 0.
164
165	z39.50url = zscheme "://" host [":" port]
166	["/" [database *["+" database]
167	["?" docid]]
168	[";esn=" elementset]
169	[";rs=" recordsyntax *[ "+" recordsyntax]]]
170
171	zscheme = "z39.50r" \| "z39.50s"
172	database = uchar
173	docid = uchar
174	elementset = uchar
175	recordsyntax = uchar
176
177	Future extensions to these URLs will be of the form of [;keyword=value].
178
179	The following definitions are from RFC 1738. Between the Internet Draft
180	version and RFC 1738 two relevant changes were made: '=' was moved from
181	the <extra> character class to <reserved>, and <national> was removed from
182	the alternatives in <unreserved>. Neither <national> nor <punctuation> is
183	referred to in this document nor in RFC 1738.
184
185	lowalpha = "a" \| "b" \| "c" \| "d" \| "e" \| "f" \| "g" \| "h" \|
186	"i" \| "j" \| "k" \| "l" \| "m" \| "n" \| "o" \| "p" \|
187	"q" \| "r" \| "s" \| "t" \| "u" \| "v" \| "w" \| "x" \|
188	"y" \| "z"
189	hialpha = "A" \| "B" \| "C" \| "D" \| "E" \| "F" \| "G" \| "H" \| "I" \|
190	"J" \| "K" \| "L" \| "M" \| "N" \| "O" \| "P" \| "Q" \| "R" \|
191	"S" \| "T" \| "U" \| "V" \| "W" \| "X" \| "Y" \| "Z"
192
193	alpha = lowalpha \| hialpha
194	digit = "0" \| "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \|
195	"8" \| "9"
196	safe = "$" \| "-" \| "_" \| "." \| "+"
197	extra = "!" \| "*" \| "'" \| "(" \| ")" \| ","
198	national = "{" \| "}" \| "\|" \| "\" \| "^" \| "~" \| "[" \| "]" \| "`"
199	punctuation = "<" \| ">" \| "#" \| "%" \| <">
200
201	reserved = ";" \| "/" \| "?" \| ":" \| "@" \| "&" \| "="
202	hex = digit \| "A" \| "B" \| "C" \| "D" \| "E" \| "F" \|
203	"a" \| "b" \| "c" \| "d" \| "e" \| "f"
204	escape = "%" hex hex
205	unreserved = alpha \| digit \| safe \| extra
206	uchar = unreserved \| escape
207	xchar = unreserved \| reserved \| escape
208	digits = 1*digit
209
210	7. Security Considerations
211
212	The two Z39.50 URL schemes are subject to the same security implications
213	as the general URL scheme [1], so the usual precautions apply. This means,
214	for example, that a locator might no longer point to the object that was
215	originally intended. It also means that it may be possible to construct
216	a URL so that an attempt to perform a harmless idempotent operation such
217	as the retrieval of an object will in fact cause a possibly damaging
218	remote operation to occur.
219
220
221	8. Acknowledgements
222
223	The Z39.50 Implementors Group contributed the substance of this document.
224
225
226	9. References
227
228	[1] Berners-Lee, T., Masinter, L., McCahill, M. (editors), "Uniform
229	Resource Locators (URL)", RFC 1738, December 1994.
230	ftp://ds.internic.net/rfc/rfc1738.txt
231
232	[2] ANSI/NISO Z39.50-1995, "ANSI Z39.50: Information Retrieval Service
233	and Protocol", 1995. ftp://ftp.loc.gov/pub/z3950/
234
235	[3] ANSI/NISO Z39.50-1992, "ANSI Z39.50: Information Retrieval Service
236	and Protocol", 1992.
237	ftp://ftp.cni.org/pub/NISO/docs/Z39.50-1992/www/Z39.50.toc.html
238	(also available in hard copy from Omnicom Information Service,
239	115 Park St., SE, Vienna, VA 22180).
240
241
242	10. Editors' Addresses
243
244	Ray Denenberg
245	Library of Congress
246	Collections Services
247	Network Development/MSO
248	Washington DC 20540
249	ray@rden.loc.gov
250	Voice: (202) 707-5795
251	Fax: (202) 707-0115
252
253	John A. Kunze
254	Center for Knowledge Management
255	University of California, San Francisco
256	530 Parnassus Ave, Box 0840
257	San Francisco, CA 94143-0840
258	jak@ckm.ucsf.edu
259	Voice: (415) 502-6660
260	Fax: (415) 476-4653
261
262	SilverPlatter Information Ltd.
263	10 Barely Mow Passage
264	Chiswick, London W4 4PH
265	U.K.
266	DenisL@SilverPlatter.com
267	Voice: +44 (0)181-995-8242
268	FAX: +44 (0)181-995-5159
269
270
271	Appendix. Examples of Z39.50 URLs
272
273	A basic Z39.50 session URL that a client might use to open a connection
274	to the MELVYL union catalog "cat" at the University of California is
275
276	z39.50s://melvyl.ucop.edu/cat
277
278	A URL that would open the MELVYL magazine database just long enough
279	to fetch an article from volume 30, number 19 of a hypothetical
280	periodical might look like
281
282	z39.50r://melvyl.ucop.edu/mags?elecworld.v30.n19
283
284	As a final example, here is another retrieval URL that a client could
285	use to request a full record (element set "f") in the MARC syntax from
286	a hypothetical database called TMF at CNIDR:
287
288	z39.50r://cnidr.org:2100/tmf?bkirch_rules__a1;esn=f;rs=marc
289
290	As in the previous example, the part of the string after the `?' is
291	determined by the server. In this example, the server is running on
292	non-standard port 2100.