Network Working Group Internet Draft: XML DTD for ACAP A. Melnikov Document: draft-melnikov-acap-xml-01.txt Messaging Direct, Ltd. Expires: May 2001 November 2000 XML DTD for ACAP - ACAP data interchange format Status of this Memo: This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at <http://www.ietf.org/ietf/1id-abstracts.txt> The list of Internet-Draft Shadow Directories can be accessed at <http://www.ietf.org/shadow.html>. A version of this draft document is intended for submission to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested. Copyright Notice Copyright (C) The Internet Society 2000. All Rights Reserved. 0. Meta-information on this draft This information is intended to facilitate discussion. It will be removed when this document leaves the Internet-Draft stage. 0.1. Open issues and work to do 0). Default XML encoding is UTF-8? 1). Do we want data type for numbers? 2). I would like to use strong data types. Use NOTATION declaration? 3). When use base-64 encoding for attribute values? Other open issues may be found in the document. They are marked with >>> 0.2. Changes from revision 00 1). Added attribute for dataset quota. 1. Abstract This document describes a XML DTD suitable for describing application configuration information or modifications made to configuration information. The file format is typically used to import and export configuration information between ACAP servers, or to describe a set of changes which are to be applied to a ACAP database or a set of ACAP databases. There are a number of situations where a common interchange format is desirable. For example, one might wish to export a copy of the contents of a ACAP server to a file, move that file to a different machine, and import the contents into a second ACAP server. In addition, well-defined interchange format facilitates the development of data import or migration tools. This document describes the interchange format that has the same objective for ACAP as [LDIF] has for LDAP. 2. Conventions used in this document The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as defined in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. When UTF-8 [UTF8] is referred to in this document, it refers to Unicode version 2.0, and not Unicode version 1.1. XML elements are enclosed in angle brackets in order to distinguish them from ACAP terms with same names. 2. "ACAP in XML" DTD 2.1. Basic data types <!ENTITY %HostAndPort "CDATA" -- Host name or IP address --> <!ENTITY %URL "CDATA" -- ACAP URL as defined in [ACAP] --> <!ENTITY %AttrName "CDATA" -- attribute name as defined in [ACAP] --> <!ENTITY %EntryName "CDATA" -- entry name as defined in [ACAP] --> <!ENTITY %FQEntryName "CDATA" -- fully qualified entry name (e.g. "/personality/user/mel/work") as defined in [ACAP] --> <!ENTITY %DatasetName "CDATA" -- dataset name as defined in [ACAP] --> <!ENTITY %AcapTime "CDATA" -- time in the format of modtime as defined in [ACAP] --> <!ENTITY %MimeType "CDATA" -- mime-type as defined in [MEDIA-TYPES] --> <!ENTITY %UINT32 "CDATA" -- unsigned 32 bit integer --> 2.2. ACAP servers and ACAP operations The root element of the DTD descibed in this document is <acapservers>. It represents the collection of ACAP servers. Each ACAP server is represented by <acap> element. Nested elements represent some ACAP operation (<rename>) or a collection of an ACAP operations (<delete>, <modify>). There is a one-to-one correlation between ACAP operations which change ACAP database (modify (add or replace), delete, and entry rename), and the names of the elements that describe these operations (<modify>, <delete> and <rename> elements). This correspondence is intentional, and permits a straightforward translation from the described operation to protocol operations. <!ELEMENT acapservers (acap)*> <!ELEMENT acap (operation)*> <!ATTLIST acap server %HostAndPort; #IMPLIED> <!ELEMENT operation (modify | delete | rename)*> <!ELEMENT modify (dataset)*> <!ATTLIST modify mode (add | replace) #REQUIRED> Note: If mode is equal to "replace" then entry content (if <entry> element is used) or acl (if <setacl> element is used) is removed first and then all attributes/acls are added. >>>Maybe add 'add' as the default value? <!ELEMENT dataset (setacl*, entry*)> Note: Dataset attributes (default dataset ACLs, dataset inheritance and others) must be represented as the attributes of the "" entry of a dataset as described in Section 5 of [ACAP]. dataset.acl and dataset.acl.<attribute> MUST be represented as <acl> element (see <values> description in Section 2.3.2) <!ATTLIST dataset name %DatasetName; #REQUIRED -- dataset name quota %UINT32; #IMPLIED -- quota limit in bytes, 0 means no quota --> Note: Although ACAP is missing command for setting quotas, some out of band mechanism can be used by import utility to set them. Note: Subdatasets of a dataset MUST be represented with dataset/entry element nesting. As the result dataset name in <dataset> element MUST be subdataset of the higher level <dataset> if any. For example, the following ACAP tree /option/ site/ common/ vendor.MD.Execmail/ Telementry MainWindow vendor.MD.M-Store/ SASL may be represented as <dataset name="/option/site/common"> <entry name="vendor.MD.Execmail"> <dataset name="/option/site/common/vendor.MD.Execmail"> <entry name="Telemetry">...</entry> <entry name="MainWindow">...</entry> </dataset> </entry> <entry name="vendor.MD.M-Store"> <dataset name="/option/site/common/vendor.MD.M-Store"> <entry name="SASL">...</entry> </dataset> </entry> </dataset> <!ELEMENT setacl (acl-object, acl)> <!ELEMENT acl-object (dataset-name, (attribute-name, entry-name?)?) -- dataset-name MUST be equal or subordinate of the the dataset element --> Note: From [ACAP]: "acl object" specifyis what the ACL applies to. This is a parenthesized list. The list contains just the dataset name when referring to the default ACL for a dataset. The list contains a dataset name and an attribute name when referring to the default ACL for an attribute in a dataset. The list contains a dataset name, an attribute name, and an entry name when referring to the ACL for an attribute of an entry of a dataset. <!ELEMENT dataset-name EMPTY> <!ATTLIST dataset-name name %DatasetName; #REQUIRED> <!ELEMENT attribute-name EMPTY> <!ATTLIST attribute-name name %AttributeName; #REQUIRED> <!ELEMENT entry-name EMPTY> <!ATTLIST entry-name name %EntryName; #REQUIRED> <!ELEMENT rename EMPTY> <!ATTLIST rename dataset %DatasetName; #REQUIRED from %EntryName; #REQUIRED to %EntryName; #REQUIRED> Note: Hierarchical rename is not allowed for an entry <!ELEMENT delete (delacl*, fqentry-name*)> <!ELEMENT delacl EMPTY> <!ATTLIST delacl dataset %DatasetName; #REQUIRED attribute %AttrName; #REQUIRED entry %EntryName; #IMPLIED identifier CDATA #IMPLIED> <!ELEMENT fqentry-name EMPTY> <!ATTLIST fqentry-name name %FQEntryName; #REQUIRED> 2.3. Entries and Attributes 2.3.1. Predefined Attributes <!ELEMENT entry (modtime?, subdataset*, attribute*, dataset*)> <!ATTLIST entry name %EntryName; #REQUIRED -- ACAP Entry name> <!ELEMENT modtime EMPTY> <!ATTLIST modtime time %AcapTime; #REQUIRED> <!ELEMENT subdataset EMPTY> <!ATTLIST subdataset href %URL; #REQUIRED> 1.3.2 Attribute Metadata Different ACAP attribute metadata items are represented in different ways: 1). attribute name is represented as <attribute> element attribute "name" 2). attribute acl is represented as <acl> element 3). attribute value is represented as one of the following elements : <value>, <value-acl>, <multivalue>, <nil> or <default> <!ELEMENT attribute (acl?, (value | value-acl | multivalue | nil | default))> <!ATTLIST attribute name %AttrName; #REQUIRED mime-type %MimeType; #IMPLIED> >>> Does any client will need "size" attribute metadata? <!ELEMENT acl (ace)*> <!ELEMENT ace EMPTY> <!ATTLIST ace identifier CDATA #REQUIRED rights CDATA #REQUIRED> <!ELEMENT multivalue (value)*> <!ELEMENT value (#PCDATA)*> <!ATTLIST value encoding (binary | base64) 'binary'> Note 1: Binary data that contains characters in the range 0x00 - 0x1F MUST be base-64 encoded. The data that contains characters in the range 0x80 - 0xFF must be base-64 encoded if it is not already in UTF-8. Note 2: All symbols that have special meaning in XML MUST be encode according to XML rules (for example character '<' must be encoded as <). <!ELEMENT value-acl acl -- Used for representing dataset.acl and dataset.acl.<attribute> --> <!ELEMENT nil EMPTY> <!ELEMENT default EMPTY> 3. Examples Example 1: <acapservers> <acap name="acap1.eva.net"> <modify mode="add"> <dataset name="/personality/~" > <entry name="personal"> <modtime time=20000403110923Z/> <subdataset href="."/> <!-- replicated copy is stored on a different server--> <subdataset href="acap://acap2.myserver.net"/> <attribute name="personality.File-Into.Local"><value>sent mail</value></attribute> <attribute name="personality.Header.Extra"><value>Pet: Yak</value></attribute> <attribute name="personality.MIME.Composition-Type"><value>text/enriched</value></attribute> <attribute name="personality.Real-Name"><value>L. Eva Message</value></attribute> <attribute name="personality.Return-Address"><value>lem@pop.isp.com</value></attribute> <attribute name="personality.Server.SMTP"><value>smtp://smtp.isp.com</value></attribute> <attribute name="personality.Signature.Text"><value>-- L. Eva Message</value></attribute> </entry> </dataset> </modify> </acap> </acapservers Example 2: <acapservers> <acap name="acap1.messagingdirect.com"> <rename dataset="/personality/user/mel" from="work" to="work1"/> </acap> <acap name="acap2.messagingdirect.com"> <modify mode="add"> <dataset> <setacl> <acl-object><dataset-name name="/personality/user/mel/work1"/><attribute-name name="personality.Server.SMTP"/></acl-object> <acl> <ace identifier="mel" rights="xrwia"/> <ace identifier="mother" rights="r"/> </acl> </setacl> </dataset> </modify> <delete> <delacl dataset="/personality/user/mel" attribute="personality.Return-Address" entry="work" identifier="anyone"/> <fqentry-name name="/options/user/mel/test"/> </delete> </acap> </acapservers 4. References [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd., November 1997. <ftp://ftp.isi.edu/in-notes/rfc2234.txt> [ACAP] Newman, Myers, "ACAP -- Application Configuration Access Protocol", RFC 2244, Innosoft, Netscape, November 1997. <ftp://ftp.isi.edu/in-notes/rfc2244.txt> [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997. <ftp://ftp.isi.edu/in-notes/rfc2119.txt> [URL-BASIC] Berners-Lee, Masinter, McCahill, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994. <ftp://ftp.isi.edu/in-notes/rfc1738.txt> [UTF8] Yergeau, F. "UTF-8, a transformation format of ISO 10646", RFC 2279, Alis Technologies, January 1998. <ftp://ftp.isi.edu/in-notes/rfc2279.txt> [MEDIA-TYPES] Freed, Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, Innosoft, First Virtual, November 1996 <ftp://ftp.isi.edu/in-notes/rfc2046.txt> 5. Security Considerations <<To be completed later>> 6. Acknowledgments <<To be completed later>> 7. Author's Address Alexey Melnikov Messaging Direct, Ltd. Address: 10117 Jaspet Avenue, Edmonton, Alberta, Canada, T5J1W8 Tel: 1 (780) 424-4922 Ext. 357 Email: mel@messagingdirect.com 8. Full Copyright Statement Copyright (C) The Internet Society 2000. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.