ACAP Datatyping and Datatyping Discovery
draft-ietf-acap-dewinter-dtype-00

Versions: 00                                                            
Network Working Group                                       J. De Winter
Internet Draft: ACAP-DISCOVER                        Wildbear Consulting
Document: draft-ietf-acap-dewinter-dtype-00.txt           April 25, 1997
Expires: Oceober 31, 1997


           ACAP Datatyping and Datatyping Discovery


Status of this Memo

   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 draft 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.

   This document suggests a proposed protocol for the Internet
   community, and requests discussion and suggestions for improvements.
   Distribution of this draft is unlimited.

   The protocol discussed in this document is experimental and subject
   to change.  Persons planning on either implementing or using this
   protocol are STRONGLY URGED to get in touch with the author before
   embarking on such a project.


1.0 Abstract

   The Application Configuration Access Protocol (ACAP) is designed to
   support remote storage and access of program option, configuration
   and preference information.  In certain circumstances, it is desirable
   or necessary to deal with information that has a limit imposed on it.
   While the general ACAP specification does provide for a (SYNTAX) alert
   to inform the submittor that the stored information was not in a valid
   syntax for that field, there is no generic method to discover that syntax.

   There is strong feeling in the ACAP working group that variable length
   strings should be used for data where possible, but there is also the
   knowledge that ACAP will be used to configure and access existing systems
   where the use of such variable length strings may be difficult or impossible.

2.0 Specification

   The DISCOVER extension may be used with any ACAP server which returns
   "DISCOVER" as one of the supported capabilities in the initial untagged
   ACAP response.  The decision on whether or not to preload certain information
   for datasets is left to the client implementation.  It should be noted
   however that most of the discvoery information in a large number of the
   datasets is consistant accross all instances of that dataset, and caching
   could provide a substantial savings.

2.1 Referencing

   Each of the datasets contain a given set of entries.  The Discover extension
   extends each of these entries to provide an in-situ method of discovering
   their type information.  This information is only provided if asked for, so
   a client implementation that does not support the DISCOVER extension will not
   be affected.

   Every entry in every dataset will include all of the mandatory elements
   described below, and may include the optional elements.  Please note that
   a given type of field may also mandate one of the optional elements to
   provide more information on that field.

   Each of the accesses within the datasets to this extended information will
   be prefixed by "Extension.Type".  For example, to find the type of a given
   addressbook item "EMail", a client would request information about
   "EMail.Extension.Type.<x>" where <x> is the desired piece of type information.
   If all of the type information is desired, the "Extension.Type" can be used
   by itself to return all of the type information for that item.

   For the purpose of quota information, none of this dataset discovery information
   should be accounted for towards any quota count, as it is server supplied
   information the client does not have any control over.

2.2 Mandatory Elements

2.2.1 Extension.Type.Cache

   This field is assigned a value of 'yes' or 'no' and specifies if the discovery
   information for this field is for the dataset or for this specific instance of
   the dataset.  Caching of disocvery information over a dataset is encouraged, but
   it is understood that certain enties may mandate dynamic information.

2.2.2 Extension.Type.Description

   This field is assigned a string of no more that 512 characters that describes
   the field itself.  This description should take into account any character sets
   selected and offer a base description in English.

2.2.3 Extension.Type.Type

   This field is assigned a value that denotes what kind of data it will contain.
   This list shall be considered to be set unless ammended by a standards track
   document.  If ammended, an addition extension tag should be used to advertise
   the additional dataset ability.

   Additional elements to be used with the typing are provided as elements that
   occur after the type declaration itself.  In the case of a type that does not
   have any additional elements, the type is returned as is.  Otherwise, the type
   is followed by a SPACE character and a SPACE separated list of elements.

2.2.3.1 Extension.Type.Type = "vstring"

   The variable length string (hence referred to as vstring) is used to store an
   arbitrarily long string of information.  This information should be stored as
   per the instructions in the [ACAP] document.  There is no additional information
   that needs to be provided with this type.

2.2.3.2 Extension.Type.Type = "bstring"

   The bounded length string (hence referred to as bstring) is used to store a
   fixed number of characters.  This type is primarily for fields where there
   are strong constraints on the number of characters needed to fulfil this item.
   The minimum and maximum elements define the lower and upper bounds
   on the string.  The default values for those elements are 0 and 254, effectively
   making them the same as the string type defined below.

2.2.3.3 Extension.Type.Type = "string"

   The string is defined as a short string containing from 0 to 254 characters,
   not including any implementation specific terminating characters.  This is a
   subset of the 'bstring' type described above, where the minimum is 0 and the
   maximum is 254.

2.2.3.4 Extension.Type.Type = "whole"

   The string is defined to consist of a sequence of numeric characters that
   comprise an unsigned 32 bit value.  The optional base element denotes
   the numeric base of the whole number, and defaults to base 10 if not present.
   The grammar in section 3.0 provides a BNF description of how the whole number
   can be expressed.

2.2.3.5 Extension.Type.Type = "bwhole"

   The string represents a bounded whole number (hence refered to as bwhole).  This
   is a number that falls within the same constraints as the whole type, but with
   the upper and lower bound of the number specified by the optional minimum and
   maximum elements.  If not present, the default values for the minimum and maximum
   elements are 0 and 100 respectively.

2.2.3.6 Extension.Type.Type = "integer"

   The string is defined to consist of a sequence of numeric characters plus the
   prefix unary minus character, and is used to comprise a signed 32 bit value
   in base 10.

2.2.3.7 Extension.Type.Type = "binteger"

   The string represents a bounded integer number (hence refered to as binteger).  This
   is a number that falls within the same constraints as the integer type, but with
   the upper and lower bound of the number specified by the optional minimum and
   maximum elements.  If not present, the default values for the minimum and maximum
   elements are 0 and 100 respectively.

2.2.3.8 Extension.Type.Type = "boolean"

   The string represents a true or false value.  The true value may be represented by
   the strings "1", "yes", or "true".  The false value may be represented by the
   strings "0", "no", or "false".  The server should be consistant in its setting of
   the given field to a given pair of these values.

2.2.3.9 Extension.Type.Type = "date"

   The string represents a time in "yyyy/mm/dd" format.

2.2.3.10 Extension.Type.Type = "time"

   The string repsents a time in "hh:mm:ss" format, assuming GMT.

2.2.3.11 Extension.Type.Type = "datetime"

   The string represents a combined date and time, assuming GMT, of
   "yyyy/mm/dd hh:mm:ss".

2.2.3.12 Extension.Type.Type = "fstring"

   The string represents a formatted string (hence referred to as fstring).
   If the first character is a '[', then the format in the Dataset.Format
   element is an ABNF construct, with the rules for the ABNF contained within
   [ABNF].  See section XXXX for a listing of the built-in constructs that the
   ABNF parser can assume unless otherwise specified.

   If the format string is empty, then the fstring is assumed to behave like
   a vstring.  Otherwise, the format is assumed to be a simple format string,
   using the '*' and '?' characters to replace one or more characters and a
   single character.  The '*' and '?' characters can be used by escaping them
   with a '\' character before them, and the '\' character must be escaped
   itself as well.

2.2.3.13 Extension.Type.Type = "select"

   The string represents a given entry from a list of acceptable entries.  The
   list of acceptible entries is denoted by the list element, and by default
   contains a single element consisting of the empty string.

2.2.3.14 Extension.Type.Type = "mime"

   The string represents a mime object.  The constrains on the type of MIME object
   allowed for this field are specified with the optional MimeDataType element.
   The default for the mime_list element is "(*/*)".

[Open Issue: Need to talk to RobE regarding storing of mime information and make
 sure that things sync up.]

2.2.3.15 Extension.Type.Type = "complex"

   The string represents a complex data type, as it may be desirable in some cases
   to pass the string to a backend process for validation or compilation.  In this
   case, if a (SYNTAX) response is generated, then the human readable section of the
   response will reflect the error that occured during submission.

   Example: storing a [SIEVE] script using ACAP with a server implementation that
            compiles the script and validates the script before it accepts it.

[Open Issue: Is is possible to return more than one error string?]

2.3 Optional Elements

2.3.1 Dataset.Hint

   This string represents a hint of no more that 512 character than can assist
   a client program in providing the user with a hint on what type of data is
   expected for this field.

2.3.7 Dataset.Hide

   This element may be used with any of the given types to ask the client program
   to try and hide the value from the user.  This is primarily for fields such as
   passwords and password validation where displaying of the password itself is
   not desired.  Note that with some fields, operating system constraints may not
   allow the given display to hide the value in question. (e.g. multiple select
   list box)

2.3.8 Dataset.ForceUpper and Dataset.ForceLower

   These elements are used with the string types to provide a way to force an
   entry to be in upper or lower case.
[Open Issue:  How would this apply to other charsets?]

2.4  Error detection

   If the dataset in question supports any of the data types other than the
   vstring data type, it is possible to return an error to the client, indicating
   the unsuitability of the data.  In this case, the server will return an
   extended response code of "SYNTAX" with the human readable text possibly giving
   more information on the nature of the syntactical error reported.  For the
   datatype "complex", it is highly recommended that the human readable text
   reflect as much information as possible to the client.

3.0  Syntax

   This syntax is expressed using BNF, except that the # constructor for list
   uses a SPACE character as a separator, rather than a comma.  Any text provided
   as part of the grammar should be considered case-insensitive.

   digit_nz  ::= "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"

   digit     ::= "0" / digit_nz

   number    ::= digit_nz *digit / digit
             ; 32 bit unsigned number with no leading zeros
             ; 0 <= n < 4,294,967,296

   minimum   ::= number

   maximum   ::= number

   whole     ::= number

   integer   ::= [ "-" ] digit_nz *digit / digit
             ; 32 bit signed number with no leading zeros
             ; -2,147,483,647  <= n < 2,147,483,648

   boolean_true ::= "true" / "yes" / "1"

   boolean_false ::= "false" / "no" / "0"

   boolean   ::= boolean_true / boolean_false

   base      ::= "2" / "8" / "10" / "16"

   date_year ::= 4digit

   date_month ::= 2digit

   date_day   ::= 2digit
              ; Note: day of the month

   date      ::= date_year "/" date_month "/" date_day

   time_hour ::= 2digit
             ; 0 <= n <= 23

   time_minute ::= 2digit
             ; 0 <= n <= 59

   time_second ::= 2digit
             ; 0 <= n <= 59

   time_zone  ::= ( "+" / "-" ) 4digit

   time      ::= time_hour ":" time_minute ":" time_second SPACE time_zone

   datetime  ::= date SPACE time

   abnf_build ::= to be added

   glob_char ::= CHAR8 except "*", "?", and "\\"

   glob_build ::= *( "*" / "?" / "\*" / "\?" / "\\" / glob_char )

   quoted_char ::= CHAR8 except "\" and <">

   quoted-string ::= <"> *( <\"> / "\\" / quoted-char ) <">

   list      ::= "(" #quoted-string ")"

   mime_item ::= "*" / CHAR8

   mime_subtype ::= mime_item

   mime_type ::= mime_item

   mime_list ::= "(" #( mime_type "/" mime_subtype ) ")"
                 ; note that if the mime_type is "*", the mime_subtype must be "*"

   type      ::= "vstring" / "bstring" [ SPACE minimum SPACE maximum ] /
                 "fstring" [ SPACE ( abnf_build / glob_build )] /
                 "string" / "whole" [ SPACE base ] /
                 "bwhole" [ SPACE minimum SPACE maximum [ SPACE base ]] /
                 "integer" / "binteger" [ SPACE minimum SPACE maximum ] /
                 "boolean" / "date" / "time" / "datetime" /
                 "select" [ SPACE list ] / "mime" [ SPACE mime_list ] /
                 "complex"

3.0 References
   [ACAP] Myers, J., and Newman, C., "Application Configuration Access
   Protocol (ACAP)", Work in Progress of the IETF ACAP WG,
   draft-ietf-acap-spec-??.txt.  Check Internet Drafts listing for
   latest version.

   [MIME-1] Borenstein, N., and Freed, N., "MIME (Multipurpose Internet
   Mail Extensions) Part One: Mechanisms for Specifying and Describing
   the Format of Internet Message Bodies", RFC 1521.

4.0 Security Considerations

   There are no known security issues with this extension.

5.0 Author's Addresses

   Jack De Winter
   Wildbear Consulting, Inc.
   17 Brock Street
   Kitchener, Ontario N2M 1X2
   Canada

   Email: jack@wildbear.on.ca