Network Working Group J. Snell
Internet-Draft November 13, 2005
Expires: May 17, 2006
Atom Publishing Protocol - Introspection
draft-snell-atompub-app-introspection-00.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of 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 May 17, 2006.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This specification defines an introspection format for the Atom
Publishing Protocol.
Snell Expires May 17, 2006 [Page 1]
Internet-Draft APP Introspection November 2005
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3
3. APP Introspection Documents . . . . . . . . . . . . . . . . . 3
3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Element Definitions . . . . . . . . . . . . . . . . . . . . . 4
4.1. The 'app:introspection' Element . . . . . . . . . . . . . 4
4.2. The 'app:workspace' Element . . . . . . . . . . . . . . . 5
4.3. The 'app:collection' Element . . . . . . . . . . . . . . . 5
5. Security Considerations . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9
Intellectual Property and Copyright Statements . . . . . . . . . . 10
Snell Expires May 17, 2006 [Page 2]
Internet-Draft APP Introspection November 2005
1. Introduction
This specification defines an XML format for describing Atom
Publishing Protocol [I-D.ietf-atompub-protocol]Collection resources.
2. Notational Conventions
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 BCP 14, [RFC2119], as
scoped to those conformance targets.
This specification uses XML Namespaces [W3C.REC-xml-names-19990114]
to uniquely identify XML element names.
"app": "http://www.w3.org/2005/Atom-Introspection"
This specification uses terms from the XML Infoset [W3C.REC-xml-
infoset-20040204]. However, this specification uses a shorthand; the
phrase "Information Item" is omitted when naming Element Information
Items. Therefore, when this specification uses the term "element,"
it is referring to an Element Information Item in Infoset terms.
3. APP Introspection Documents
This specification describes the format for Atom Publishing Protocol
Introspection Documents.
An Introspection Document represents zero or more APP Collections and
Workspaces. A Workspace is a logical collections of related APP
Collections. The root of the Introspection document is the app:
introspection element.
namespace app = "http://www.w3.org/2005/Atom-Introspection"
start = appIntrospection
Introspection Documents are specified in terms of the XML Information
Set, serialised as XML 1.0 [W3C.REC-xml-20040204] and identified with
the "application/app-introspection+xml" media type. Introspection
Documents MUST be well-formed XML. This specification does not
define a DTD for Introspection Documents, and hence does not require
them to be valid (in the sense used by XML).
APP Introspection allows for the use of IRI's [RFC3987], xml:base
[W3C.REC-xmlbase-20010627] and xml:lang in the same fashion described
in Section 2 of the Atom Syndication Format specification [I-D.ietf-
Snell Expires May 17, 2006 [Page 3]
Internet-Draft APP Introspection November 2005
atompub-format].
3.1. Example
Simple Example
<?xml version="1.0" ?>
<app:introspection
xmlns:app="http://www.w3.org/2005/Atom-Introspection">
<app:collection
title="Bookmarks"
type="entry"
href="http://example.com/bookmarks" />
<app:collection
title="Photos"
href="http://example.com/photos" />
</app:introspection>
Workspace Example
<?xml version="1.0" ?>
<app:introspection
xmlns:app="http://www.w3.org/2005/Atom-Introspection">
<app:workspace title="My Weblog">
<app:collection
title="Entries"
type="entry"
href="http://myblog.example.com/entries" />
<app:collection
title="Photos"
type="image/*"
href="http://myblog.example.com/photos" />
<app:collection
title="Files"
href="http://myblog.example.com/files" />
</app:workspace>
</app:introspection>
4. Element Definitions
4.1. The 'app:introspection' Element
The 'app:introspection' Element is the root of APP Introspection
Documents.
Snell Expires May 17, 2006 [Page 4]
Internet-Draft APP Introspection November 2005
appIntrospection =
element app:introspection {
atomCommonAttributes,
( appWorkspace*,
& appCollection*,
& extensionElement* )
}
This specification assigns no significance to the order of the child
elements of 'app:introspection'.
4.2. The 'app:workspace' Element
The 'app:workspace' Element represents a logical collection of
related APP Collections.
appWorkspace =
element app:workspace {
atomCommonAttributes,
& attribute title (text),
( appCollection*,
& extensionElement )
}
The 'title' attribute specifies a human-readable, language-sensitive
label for the workspace.
This specification assigns no significance to the order of the child
elements of 'app:workspace'.
4.3. The 'app:collection' Element
The 'app:collection' Element represents a collection resource as
specified by the Atom Publishing Protocol.
appCollection =
element app:collection {
atomCommonAttributes,
& attribute title (text),
& attribute href (IRI),
& attribute type ( 'entry' | extensionType )?,
( extensionElement )
}
extensionType = ( NMTOKEN | mediaType | mediaRange )
The 'title' attribute specifies a human-readable, language-sensitive
label for the collection.
Snell Expires May 17, 2006 [Page 5]
Internet-Draft APP Introspection November 2005
The 'href' attribute specifies the IRI of an APP collection resource.
The 'type' attribute MAY be used to specify the types of resources
contained by the collection. A value of 'entry' indicates that the
collection membership consists entirely of Atom Entry Documents. If
the collection element does not contain a 'type' attribute, the
membership of the collection SHOULD be considered to be
unconstrained. If the value specified is a media type or media
range, the membership of the collection SHOULD be considered to be
constrained to resources of the specified type or covered by the
specified range. If the 'type' attribute specifies a value that is
not understood by the an application, the application MUST ignore the
attribute as if the attribute were not present.
5. Security Considerations
TBD
6. IANA Considerations
An Introspection Document can be identified by the following media
type.
Snell Expires May 17, 2006 [Page 6]
Internet-Draft APP Introspection November 2005
MIME media type name:
application
MIME subtype name:
app-introspection+xml
Mandatory parameters:
None
Optional parameters:
"charset":
This parameter has identical semantics to the charset
parameter of the "application/xml" media type as
specified in [RFC3023].
Encoding considerations:
Identical to those of "application/xml" as described
in [RFC3023], section 3.2.
Security considerations:
As defined in this specification.
In addition, as this media type uses the "+xml" convention,
it shares the same security considerations as described in
[RFC3023], section 10.
Interoperability considerations:
There are no known interoperability issues.
Published specification:
This specification.
Applications that use this media type:
No known applications currently use this media type.
Additional information:
Magic number(s):
As specified for "application/xml" in [RFC3023], section 3.2.
File extension:
.appx
Fragment identifiers:
As specified for "application/xml" in [RFC3023], section 5.
Base URI:
As specified in [RFC3023], section 6.
Macintosh File Type code:
TEXT
Person and email address to contact for further information:
James Snell <jasnell@gmail.com>
Intended usage:
COMMON
Author/Change controller:
IESG
Snell Expires May 17, 2006 [Page 7]
Internet-Draft APP Introspection November 2005
7. Acknowledgements
This draft incorporates ideas discussed by the members of the Atom
Publishing Format and Protocol working group. This draft also adapts
some of the language and text from the Atom Syndication Format
[I-D.ietf-atompub-format] in order to achieve a stylistic similarity
between the drafts.
8. References
[I-D.ietf-atompub-format]
Sayre, R. and M. Nottingham, "The Atom Syndication
Format", draft-ietf-atompub-format-11 (work in progress),
August 2005.
[I-D.ietf-atompub-protocol]
Hora, B. and J. Gregorio, "The Atom Publishing Protocol",
draft-ietf-atompub-protocol-06 (work in progress),
November 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, January 2005.
[W3C.REC-xml-20040204]
Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T.,
and E. Maler, "Extensible Markup Language (XML) 1.0 (Third
Edition)", W3C REC REC-xml-20040204, February 2004.
[W3C.REC-xml-infoset-20040204]
Tobin, R. and J. Cowan, "XML Information Set (Second
Edition)", W3C REC REC-xml-infoset-20040204,
February 2004.
[W3C.REC-xml-names-19990114]
Hollander, D., Bray, T., and A. Layman, "Namespaces in
XML", W3C REC REC-xml-names-19990114, January 1999.
[W3C.REC-xmlbase-20010627]
Marsh, J., "XML Base", W3C REC REC-xmlbase-20010627,
June 2001.
Snell Expires May 17, 2006 [Page 8]
Internet-Draft APP Introspection November 2005
Author's Address
James M Snell
Phone:
Email: jasnell@gmail.com
URI: http://snellspace.com
Snell Expires May 17, 2006 [Page 9]
Internet-Draft APP Introspection November 2005
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Disclaimer of Validity
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM 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.
Copyright Statement
Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Snell Expires May 17, 2006 [Page 10]