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 element . . . . . . . . . . . . . . 13 7.2. The root element . . . . . . . . . . . . . . 13 7.3. The element . . . . . . . . . . . . . . . . . . . . 13 7.4. The element . . . . . . . . . . . . . . . . . . . 13 7.4.1. 'type' attribute . . . . . . . . . . . . . . . . . . . 13 7.4.2. The element . . . . . . . . . . . . . . . . . . 13 7.4.3. 'date' attribute . . . . . . . . . . . . . . . . . . . 13 7.4.4. The 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: Our WITSML Repository bhaRuns cementJobs wells wellbores 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 "" 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 "" 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: TEST WELLBORE 1 2006-03-10T11:32:27.038-06:00 XML Contains View TEST WELLBORE 2 2006-02-06T15:06:22.624-06:00 XML Contains View TEST WELLBORE 3 2006-02-06T15:04:35.426-06:00 XML Contains View 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 "" 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 "" elements: POST HTTP/1.1 Host: witsml.example.org Content-Type: text/plain; charset="UTF-8" Content-length: 106 846.00000,-999.00000,-999.00000,17.50000 846.50000,-999.00000,-999.00000,9.10000 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 "" element "" as its root element. 7.1. The root element A document with a root "" element describes the repository as a whole.; a document with a root "" element describes collections within a repository. 7.2. The root element A document with a root element describes collections within a repository. 7.3. The element The "" element supplies a human readable name for the collection 7.4. The element The "" 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 element The "" element supplies a human readable name for the object 7.4.3. 'date' attribute 7.4.4. The element "" 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, . 11.2. Informative References [ATOMPUB] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", 2006, . [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, . Winkler Expires September 17, 2006 [Page 18] Internet-Draft Well Information Exchange Protocol: WIXP March 2006 URIs [1] 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]