[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

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]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/