Network Working Group G. Sneddon
Internet-Draft March 23, 2009
Intended status: Experimental
Expires: September 24, 2009
Atom Export Format
draft-sneddon-atom-export-00
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
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.
This Internet-Draft will expire on September 24, 2009.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract
This document specifies a method of using the Atom Syndication Format
as an export format.
Sneddon Expires September 24, 2009 [Page 1]
Internet-Draft Atom Export Format March 2009
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3
2.1. Conformance Requirements . . . . . . . . . . . . . . . . . 3
3. Atom Export Documents . . . . . . . . . . . . . . . . . . . . . 3
4. index.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
7. Normative References . . . . . . . . . . . . . . . . . . . . . 5
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 6
Appendix B. Known Issues . . . . . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7
Sneddon Expires September 24, 2009 [Page 2]
Internet-Draft Atom Export Format March 2009
1. Introduction
[[anchor2: This section is yet to be written.]]
2. Notational Conventions
This specification is defined in terms of the US-ASCII character set
as defined in [ANSI.X3-4.1986]. Except where explicitly specified,
all strings are case-sensitive.
2.1. Conformance Requirements
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].
This document places certain restrictions depending on the purpose of
the software implementing it. These groups are: importers, which
process an Atom Export document and make a copy of it within their
own data store; and, exporters, which create an Atom Export document
from the contents of their own data store.
Occasionally, an implementation is required to raise a fatal error.
When an importer is required to raise a fatal error, it MUST abort
processing of the Atom Export Document and MUST NOT continue
processing of any sort. When an exporter is required to raise a
fatal error, it MUST abort creating of an Atom Export Document, and
MUST discard what it has thus far produced.
3. Atom Export Documents
An Atom Export Document is an archive file containing one or more
Atom Feed Documents [RFC4287]. (The archive can, however, contain
arbitrary files of any format.)
Implementations MUST support ustar [IEEE.1003-1.2008] archives, and
SHOULD support GZIP [RFC1952] compressed ustar archives. Exporters
SHOULD create GZIP compressed ustar archives.
The root of the archive, for the purposes of this document, MUST be
found using the following algorithm:
1. Let "current directory" be the upper-most directory of the
archive.
Sneddon Expires September 24, 2009 [Page 3]
Internet-Draft Atom Export Format March 2009
2. If "current directory" contains, case-sensitively, a file called
"index.xml", then "current directory" is the root. Terminate the
algorithm.
3. If "current directory" contains no files and one directory, then
let "current directory" be that directory. Jump to step 2 of
this algorithm.
4. Otherwise, this algorithm has failed. Raise a fatal error.
When creating an Atom Export document, the exporter SHOULD create a
single outer directory containing the "index.xml" file.
When importing an Atom Export Document, processing MUST begin at the
"index.xml" file located at the root of the archive. Importers MUST
support Feed Paging and Archiving [RFC5005], and SHOULD support Atom
Threading Extensions [RFC4685].
When used as a link relation of an atom:link element which is a child
of the root element in an Atom Feed Document, the link relations
defined by Feed Paging and Archiving [RFC5005] MUST only be created
by exporters when their "href" attribute's value matches the "path-
noscheme" production in [RFC3986] and points to another Atom Feed
Document in the Atom Export Document. Upon encountering a atom:link
element that does not meet the above requirement, an importer SHOULD
NOT follow the link if it is an absolute IRI, and MUST raise a fatal
error if upon attempting to access the the document linked to by the
"href" it is found not to exist (e.g., it is a relative URI and the
file does not exist within the Atom Export Document, it is a HTTP URI
and the status-code returned is 404 or 410).
Any file linked (either via atom:link or another linking method, such
as within an Atom Text Construct or atom:content element) via a
relative IRI that exists within the Atom Export Document SHOULD be
copied by an importer to a location at which it will be accessible
once imported, updating the IRI reference if needed. Equally, the
importer SHOULD keep track of all alternate links (in the atom:link
sense of the word link) for all entries and update IRI references
that point to alternate representations within the Atom Export
Document so that they are accessible in the imported copy.
4. index.xml
The "index.xml" file, located at the root of the archive, MUST be an
Atom Feed Document [RFC4287].
The "index.xml" file represents the main stream of entries of the
Sneddon Expires September 24, 2009 [Page 4]
Internet-Draft Atom Export Format March 2009
export.
If "index.xml" makes use of Feed Paging and Archiving [RFC5005], the
exporter MUST create "index.xml" as the first page if it uses paging,
and as the current page if it uses archiving. Importers MUST make no
assumption about the feed ordering, and MUST therefore handle cases
where "index.xml" is not the first/current page identically to as if
it had been.
5. Security Considerations
As this specification primarily relies upon other specifications to
define the formats used within this specification, it is subject to
the same security considerations as they are. Please obtain the
documents listed under "Normative References" for their security
considerations.
If an implementation expands the Atom Export Document into a larger
filesystem for processing, it must beware of relative IRIs that would
cause the implementation to operate on files outside of the expanded
archive.
Arbitrary files can be contained with the Atom Export Document: any
implementation must ensure that due care is taken so that these do
not pose a risk. These can especially become a risk if they are
copied (due to being linked) to somewhere publicly accessible, or
somewhere where they could be executed (such as a CGI script on a
web-server).
6. IANA Considerations
[[anchor9: This section is yet to be written, primarily because it is
pending a decision about archive formats (this has repercussions on
detecting what archive format is used, and thus on this section).]]
7. Normative References
[ANSI.X3-4.1986]
American National Standards Institute, "Coded Character
Set - 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986.
[IEEE.1003-1.2008]
Institute of Electrical and Electronics Engineers,
"Standard for Information Technology - Portable Operating
Sneddon Expires September 24, 2009 [Page 5]
Internet-Draft Atom Export Format March 2009
System Interface (POSIX)", IEEE Standard 1003.1,
September 2008.
[RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L., and G.
Randers-Pehrson, "GZIP file format specification version
4.3", RFC 1952, May 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
Syndication Format", RFC 4287, December 2005.
[RFC4685] Snell, J., "Atom Threading Extensions", RFC 4685,
September 2006.
[RFC5005] Nottingham, M., "Feed Paging and Archiving", RFC 5005,
September 2007.
[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing
Protocol", RFC 5023, October 2007.
Appendix A. Acknowledgments
[[anchor12: This section is yet to be written.]]
Appendix B. Known Issues
[[anchor14: Remove this section upon publication.]]
o Need to register MIME type.
o Need to decide about archive formats (this has an effect on MIME
type registration).
o Need to review the document v. I-D requirements.
o Need to define processing when parsing enclosed file fails.
o Resolving IRIs (defining / to be the root of the archive).
Sneddon Expires September 24, 2009 [Page 6]
Internet-Draft Atom Export Format March 2009
o Security considerations will have to say more.
o Work out why RFC5023 is referenced, or delete reference.
Author's Address
Geoffrey Sneddon
Email: me@gsnedders.com
URI: http://gsnedders.com/
Sneddon Expires September 24, 2009 [Page 7]