Internet DRAFT - draft-winkler-wixp

draft-winkler-wixp







Network Working Group                                         H. Winkler
Internet-Draft                                     Wellstorm Development
Expires: September 17, 2006                               March 16, 2006


                Well Information Exchange Protocol: WIXP
                         draft-winkler-wixp-00

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 September 17, 2006.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   This memo presents a protocol that uses HTTP to exchange, update, and
   delete Wellsite Information Transfer Standard Markup Language
   (WITSML) documents.









Winkler                Expires September 17, 2006               [Page 1]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


Table of Contents

   1.  Requirements notation  . . . . . . . . . . . . . . . . . . . .  3
   2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  Model  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
   4.  Discovery  . . . . . . . . . . . . . . . . . . . . . . . . . .  6
     4.1.  Discovering the collections in the repository  . . . . . .  6
     4.2.  Discovering the URIs of WITSML objects . . . . . . . . . .  7
   5.  Adding a document to the repository  . . . . . . . . . . . . .  9
   6.  Manipulating Documents . . . . . . . . . . . . . . . . . . . . 10
     6.1.  MIME type  . . . . . . . . . . . . . . . . . . . . . . . . 10
     6.2.  GET  . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
     6.3.  PUT  . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
     6.4.  DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     6.5.  POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
   7.  Repository Description Document (RDD)  . . . . . . . . . . . . 13
     7.1.  The root <repository> element  . . . . . . . . . . . . . . 13
     7.2.  The root <collection> element  . . . . . . . . . . . . . . 13
     7.3.  The <name> element . . . . . . . . . . . . . . . . . . . . 13
     7.4.  The <object> element . . . . . . . . . . . . . . . . . . . 13
       7.4.1.  'type' attribute . . . . . . . . . . . . . . . . . . . 13
       7.4.2.  The <name> element . . . . . . . . . . . . . . . . . . 13
       7.4.3.  'date' attribute . . . . . . . . . . . . . . . . . . . 13
       7.4.4.  The <link> element . . . . . . . . . . . . . . . . . . 13
     7.5.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . 14
   8.  Relax NG Compact Schema  . . . . . . . . . . . . . . . . . . . 15
   9.  Authentication and Authorization . . . . . . . . . . . . . . . 16
   10. Security Considerations  . . . . . . . . . . . . . . . . . . . 17
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 18
     11.2. Informative References . . . . . . . . . . . . . . . . . . 18
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20
   Intellectual Property and Copyright Statements . . . . . . . . . . 21


















Winkler                Expires September 17, 2006               [Page 2]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


1.  Requirements notation

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














































Winkler                Expires September 17, 2006               [Page 3]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


2.  Introduction

   The WITSML SIG [1] has defined a body of XML document types
   ([WITSML131])for describing entities in oil and gas drilling.
   Additionally, it has defined SOAP protocols for exchanging and
   modifying that data.  That protocol has been successful in meeting
   its goal of enabling the flow of well site data between operators and
   service companies.  Yet implementation of that protocol can be
   complex, limiting the adoption rate among vendors with less direct
   need for the full search and update semantics in that protocol.

   To encourage broader implementation, and to enhance accessibility by
   many different kinds of clients, this specification defines a
   protocol for document exchange based on HTTP and the architecture of
   the web ([W3C.WD-webarch-20040816]).

   This specification does not modify any WITSML document formats.  It
   specifies only a protocol for exchanging and modifying them.  To
   implement this specification, clients and servers just obey the rules
   of HTTP [RFC2616], and understand a simple document type, that
   locates the WITSML documents on the server.






























Winkler                Expires September 17, 2006               [Page 4]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


3.  Model

   A WIXP service exposes two kinds of resources: The WITSML documents
   themselves, and XML documents describing how to find them.  The
   service identifies each resource by a URI [RFC3986].  Client
   applications use HTTP methods GET, POST, PUT and DELETE to retrieve
   and manipulate these resources:

   o  GET retrieves a document.  The URI may identify a WIXP repository
      description, a WIXP collection, or a WITSML object.

   o  POST creates a document or adds a subordinate element to a
      document.

      *  If the URI identifies a WIXP repository, POST creates a new
         document in the repository.

      *  If the URI identifies a "growing" WITSML object, POST appends a
         fragment to a repeating element in the document.

   o  PUT updates an existing WITSML document, replacing the whole
      document.

   o  DELETE removes a WITSML object from the repository.

   Most of the rules governing client-server interaction are simple
   HTTP.  WIXP-aware clients and servers understand, additionally, the
   meanings of the repository description documents, and that POSTing to
   the URIs of growing WITSML objects will append to them.






















Winkler                Expires September 17, 2006               [Page 5]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


4.  Discovery

4.1.  Discovering the collections in the repository

   When given the URI of a repository, clients GET a document from that
   URI.

   Client                                Server
   |                                          |
   |  1.) GET Repository URI                  |
   |----------------------------------------->|
   |                                          |
   |  2.) Repository CDD                      |
   |<-----------------------------------------|
   |                                          |

   The Repository Description Document (RDD) is described in Section 7.
   Below is a short example of the root RDD for a repository:

   <repository xmlns="http://www.witsml.net/ns/repository">
     <name>Our WITSML Repository</name>
     <object type="bhaRun">
       <link rel="collection" href="bhaRun">bhaRuns</link>
     </object>
     <object type="cementJob">
       <link rel="collection" href="cementJob">cementJobs</link>
     </object>
     <object type="well">
       <link rel="collection" href="well">wells</link>
     </object>
     <object type="wellbore">
       <link rel="collection" href="wellbore">wellbores</link>
     </object>
   </repository>

   Figure 2

   Servers MUST expose a RDD at some URI.  The RDD SHOULD enumerate
   collection links for "well" objects, so that clients can traverse a
   hierarchy of contained objects to locate the objects of interest.
   The RDD MAY enumerate collection links for all object types, as a
   shortcut.

   Having obtained the RDD, the client can locate collections of WITSML
   documents by following the "<link>" elements whose "rel" attribute is
   ""collection"".





Winkler                Expires September 17, 2006               [Page 6]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


4.2.  Discovering the URIs of WITSML objects

   Clients obtain more RDDs by following collection links in the
   repository's root RDD as described in Section 4.1.  A collection link
   is a "<link>" element whose "rel" attribute is ""collection"".

   Client                                Server
   |                                          |
   |  1.) GET Collection URI                  |
   |----------------------------------------->|
   |                                          |
   |  2.) Repository Description Document     |
   |<-----------------------------------------|
   |                                          |

   Below is a sample RDD that might have been obtained by following the
   collection link from the "wellbore" object in the example in
   Figure 2:

   <collection xmlns="http://www.witsml.net/ns/repository" >
     <object type="wellbore">
       <name>TEST WELLBORE 1</name>
       <date>2006-03-10T11:32:27.038-06:00</date>
       <link rel="instance" href="TEST-WB-1">XML</link>
       <link rel="contains" href="TEST-WB-1-C">Contains</link>
       <link rel="view" href="TEST-WB-1-V">View</link>
     </object>
     <object type="wellbore">
       <name>TEST WELLBORE 2</name>
       <date>2006-02-06T15:06:22.624-06:00</date>
       <link rel="instance" href="TEST-WB-2">XML</link>
       <link rel="contains" href="TEST-WB-2-C">Contains</link>
       <link rel="view" href="TEST-WB-2-V">View</link>
     </object>
     <object type="wellbore">
       <name>TEST WELLBORE 3</name>
       <date>2006-02-06T15:04:35.426-06:00</date>
       <link rel="instance" href="TEST-WB-3">XML</link>
       <link rel="contains" href="TEST-WB-3-C">Contains</link>
       <link rel="view" href="TEST-WB-3-V">View</link>
     </object>
   </collection>


   The RDD enumerates the objects in the collection.  It describes
   metadata about the object, and may contain several links for each
   object.  Each "wellbore" object in the sample above contains links to
   the XML object itself, to a collection of "contained objects" per the



Winkler                Expires September 17, 2006               [Page 7]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


   WITSML containership hierarchy, and to a view resource.  None of
   these link types are mandatory.  A server may choose not to support a
   view link type, or it may choose links to expose or hide based on the
   user's privileges.

   If the user has appropriate privileges, servers SHOULD supply a link
   to contained objects for "well", "wellbore", and any other WITSML
   objects that can contain other other objects.  Servers SHOULD supply
   a link to the instance data .  Servers SHOULD supply metadata
   including the object's name and date.









































Winkler                Expires September 17, 2006               [Page 8]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


5.  Adding a document to the repository

   Clients can add documents to a repository by POSTing documents to the
   repository URI:

   Client                                Server
   |                                          |
   |  1.) POST Repository URI                 |
   |----------------------------------------->|
   |                                          |
   |  2.) 201 Created                         |
   |<-----------------------------------------|
   |                                          |

   If the server successfully added the document to the repository, it
   SHOULD return HTTP 201 Created, and return the URI it has assigned to
   the new object in the Location header.  This is just the behavior
   specified by [RFC2616].

































Winkler                Expires September 17, 2006               [Page 9]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


6.  Manipulating Documents

   To get, update or delete a WITSML document in the repository,
   applications use the GET, PUT and DELETE methods respectively, on the
   URI of the document itself.  This is just the behavior specified by
   [RFC2616].  Additionally, we will define what it means to POST to a
   WITSML document URI.  We described how to obtain these URIs in
   Section 4.2.

6.1.  MIME type

   In Content-type headers, WITSML documents SHOULD have the type
   "application/witsml+xml" once registration for that type has
   completed per [RFC4288]

6.2.  GET

   Servers MUST support GET on WITSML document URIs.

   Client                                Server
   |                                          |
   |  1.) GET Document URI                    |
   |----------------------------------------->|
   |                                          |
   |  2.) WITSML Document                     |
   |<-----------------------------------------|
   |                                          |

   To retrieve a document, clients execute GET on its URI.  To assure
   that clients and caches can detect stale objects, servers SHOULD
   follow the "Rules for When to Use Entity Tags and Last-Modified
   Dates" in Section 13.3.4 of [RFC2616].  When retrieving documents for
   later modification with PUT, clients should record the returned
   entity tag or modification date.

6.3.  PUT

   Servers MAY support PUT on WITSML document URIs.













Winkler                Expires September 17, 2006              [Page 10]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


   To update a document a client will previously have obtained the
   document from its URI using GET.  The client then modifies the
   document and executes PUT on its URI.

   Client                                Server
   |                                          |
   |  1.) GET Document URI                    |
   |----------------------------------------->|
   |                                          |
   |  2.) 200 OK                              |
   |<-----------------------------------------|
   |                                          |
   |  3.) PUT Modified Doc to URI             |
   |----------------------------------------->|
   |                                          |
   |  4.) 200 OK                              |
   |<-----------------------------------------|
   |                                          |

   Clients SHOULD request the PUT conditionally, using HTTP headers If-
   Unmodified-Since or If-Match.  Doing so prevents overwriting changes
   made to the document since the last time the client retrieved it.

6.4.  DELETE

   Servers MAY support DELETE on WITSML document URIs.

   Client                                Server
   |                                          |
   |  1.) DELETE Document URI                 |
   |----------------------------------------->|
   |                                          |
   |  2.) 200 OK                              |
   |<-----------------------------------------|
   |                                          |

   To delete a document from the repository, clients execute DELETE on
   its URI.

6.5.  POST

   Servers MAY support POST on WITSML document URIs.  This section
   prescribes the meaning of POST on a WITSML document URI.








Winkler                Expires September 17, 2006              [Page 11]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


   Client                                Server
   |                                          |
   |  1.) POST Document URI + fragment        |
   |----------------------------------------->|
   |                                          |
   |  2.) 204 No Content                      |
   |<-----------------------------------------|
   |                                          |

   Several WITSML object types are called "growing objects" For example,
   "log" objects accumulate "<data>" elements.  A client may POST a
   WITSML fragment in the entity of a request to the document's URI.  If
   supporting this behavior, the server SHALL append the fragment to the
   appropriate growing portion of the document.  This is consistent with
   [RFC2616]'s description of POST : _"The POST method is used to
   request that the origin server accept the entity enclosed in the
   request as a new subordinate of the resource"_.  If POST is
   successful, the server SHOULD return 204 No Content, as no new
   resource has been created.

   For the "log" example, the client would POST one or more "<data>"
   elements:

   POST HTTP/1.1
   Host: witsml.example.org
   Content-Type: text/plain; charset="UTF-8"
   Content-length: 106

   <data>846.00000,-999.00000,-999.00000,17.50000</data>
   <data>846.50000,-999.00000,-999.00000,9.10000</data>

   The Content-type for posting a fragment _MUST NOT_ be "application/
   witsml+xml"

   A server may support POSTing other media types to a document URI, or
   POSTing to non-growing WITSML objects.  This specification does not
   define any expected behavior for doing so.














Winkler                Expires September 17, 2006              [Page 12]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


7.  Repository Description Document (RDD)

   An RDD may have either a "<repository>" element "<collection>" as its
   root element.

7.1.  The root <repository> element

   A document with a root "<repository>" element describes the
   repository as a whole.; a document with a root "<collection>" element
   describes collections within a repository.

7.2.  The root <collection> element

   A document with a root <collection> element describes collections
   within a repository.

7.3.  The <name> element

   The "<name>" element supplies a human readable name for the
   collection

7.4.  The <object> element

   The "<object>" embodies a collection of information about an object
   or an object type.

7.4.1.  'type' attribute

   The type attribute specifies the WITSML object type

7.4.2.  The <name> element

   The "<name>" element supplies a human readable name for the object

7.4.3.  'date' attribute

7.4.4.  The <link> element

   "<link>" describes a hyperlink to some resource associated with the
   object.

7.4.4.1.  'href' attribute

   The href is the URI of a resource.

7.4.4.2.  'rel' attribute

   The "rel" attribute tells the meaning or relation of the link.  Any



Winkler                Expires September 17, 2006              [Page 13]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


   string is allowed.  Certain strings are currently defined, and all
   clients SHOULD understand these:

      _collection_: The href is a collection of objects of the object's
      type.

      _instance_: The href is the XML instance document of the object.

      _contains_: The href is a collection document (Section 7)
      enumerating the other objects contained (in the WITSML sense)
      within this object.  For example, if the object is of type well,
      the "contains" link would refer to a collection document
      enumerating wellbores.

      _view_: The href refers to a graphical rendering of the object.

7.5.  Extensibility

   RDDs are extensible.  Clients MUST ignore elements and attributes
   they don't recognize.  This schema will evolve by adding elements and
   attributes to the default namespace in Section 8.  Servers may also
   extend the document format by adding names and attributes from
   private namespaces, anywhere in the document.




























Winkler                Expires September 17, 2006              [Page 14]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


8.  Relax NG Compact Schema

   [provisional]

   default namespace = "http://www.witsml.net/ns/repository"

   any = anyAttribute | text | anyElement
   anyAttribute = attribute * { text }
   anyElement = element * { (anyAttribute | text | anyElement)* }

   object = element object {
     attribute type { xsd:NCName },
     (date? &
     link*)
   }
   date = element date {
     attribute type { xsd:NCName },
     link*
   }

   repository = element repository {
   anyAttribute* ,
   (
       element name { text },
        (anyElement* | object*)*
   )
   }

   collection = element collection {
   anyAttribute* ,
   (
       element name { text }?,
        (anyElement* | object*)*
   )
   }

   link = element link {
       ((attribute href { text },
       attribute rel { xsd:NCName }) |
       anyAttribute*),
       text
   }

   start = (repository | collection)







Winkler                Expires September 17, 2006              [Page 15]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


9.  Authentication and Authorization

   Servers typically need to restrict access to resources according to
   the user's identity.  This specification does not limit the mechanism
   that servers may employ.  For greatest interoperability servers and
   clients should support the Basic and Digest mechanisms described in
   [RFC2617].  These mechanisms are vulnerable to replay attacks unless
   the session is encrypted using TLS ([RFC2246]).











































Winkler                Expires September 17, 2006              [Page 16]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


10.  Security Considerations

   Most owners of well information consider it sensitive.  All data
   should be exchanged over a secure channel according to [RFC2246].















































Winkler                Expires September 17, 2006              [Page 17]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


11.  References

11.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2246]  Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
              RFC 2246, January 1999.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC2617]  Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
              Leach, P., Luotonen, A., and L. Stewart, "HTTP
              Authentication: Basic and Digest Access Authentication",
              RFC 2617, June 1999.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC4288]  Freed, N. and J. Klensin, "Media Type Specifications and
              Registration Procedures", BCP 13, RFC 4288, December 2005.

   [WITSML131]
              "WITSML v1.3.1 API Specification", 2005,
              <http://www.witsml.org/Docs/Documents.html#v131API>.

11.2.  Informative References

   [ATOMPUB]  Gregorio, J. and B. de hOra, "The Atom Publishing
              Protocol", 2006, <http://bitworking.org/projects/atom/
              draft-ietf-atompub-protocol-08.html>.

   [W3C.WD-webarch-20040816]
              Walsh, N. and I. Jacobs, "Architecture of the World Wide
              Web, First Edition", W3C LastCall WD-webarch-20040816,
              August 2004.

   [WITSML-ORG]
              POSC, "WITSML SIG", 2006, <http://www.witsml.org/>.








Winkler                Expires September 17, 2006              [Page 18]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


URIs

   [1]  <http://www.witsml.org>
















































Winkler                Expires September 17, 2006              [Page 19]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


Author's Address

   Hugh Winkler
   Wellstorm Development

   Email: hughw@wellstorm.com













































Winkler                Expires September 17, 2006              [Page 20]

Internet-Draft  Well Information Exchange Protocol: WIXP      March 2006


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 (2006).  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.




Winkler                Expires September 17, 2006              [Page 21]