WITSML Application Programming Interface Overview

Version 1.3.1

This document contains the following sections:

Changes between versions 1.3.0 and 1.3.1 are defined in the Schema Change Detail and in the API specification documents. This overview is non-normative and is not part of the standard.

Introduction

The Wellsite Information Transfer Standard Markup Language (WITSML) is a standard for sending well site information in an XML document format between business partners. XML schemas are used to define the content of an XML document. The WITSML standard consists of specifications which will now be versioned independently: Data Schema and Application Program Interface (API). This document provides an overview of the Application Program Interface. The use of the Data Schema is required but use of the API is optional.

The API specification defines interfaces that will be implemented by a WITSML server for supporting client/server access. The specification defines two interfaces: Store and Publish. The Store interface is the primary interface and it provides basic access of information such as Get, Update, Add and Delete. The Publish interface is primarily intended to provide the WITS functionality of streaming data as it is being acquired.

The following files are the Web Service Description Language (WSDL) files used to expose the STORE and PUBLISH interfaces to SOAP clients: WMLS.WSDL and WMLP.WSDL.

Server Profiles

In order to make it easier to understand what API functionality may be used by different servers, a set of server profiles has been developed. These profiles are intended to enable WITSML consumers to identify the expected behaviour of WITSML server products.

The profiles are identified as: "Data Transfer", "Data Management" and "Archival" profiles and are described in more detail below.

Data Transfer Profile

A "Data Transfer" server is one that provides a transfer of near-real time data from one or more wells. This capability would normally be provided by a service company that is performing data acquisition services at a wellsite but it could also be provided by a 3rd party company that provides a WITSML server to aggregate data streams from multiple service companies.

A Data Transfer server will typically maintain data for wells while they are being drilled but may also contain relevant data sets from associated offset wells.

To the external customer the Data Transfer server exposes the GetVersion, GetCapabilities, GetFromStore and Publish/Subscribe functionality, enabling retrieval of real time data and queries for other WITSML data objects. The Publish/Subscribe functionality will probably be limited to the realtime, trajectory, trajectoryStation or mudLog objects. The details of the WITSML objects available via the GetFromStore API call are obtainable from the server via a query for the WITSML capabilities object.

The Data Transfer server may implement other WITSML methods in order to receive data from acquisition systems at the rig to enable it to build up its internal data store of WITSML objects but these activities are under the control of the provider of the server and not exposed to the external customers.

Data Management Profile

A "Data Management Profile" server is one that can maintain a longer term data store and also support the additional functionality of AddToStore, UpdateInStore and DeleteFromStore in addition to the basic capabilities of the Data Transfer server. The ability to call the data transformation methods (Add, Update, Delete) will have to be managed via a server-specific set of permissions that restricts these methods to specific users or groups of users.

A Data Management Profile Server will typically contain data from both active and inactive wells and be used to provide WITSML data to applications and analysis software

The details of the WITSML objects available via the API calls are obtainable from the server via a query for the WITSML capabilities object.

Archival Profile

An "Archival Profile" server is one that is used to maintain a historical record of data in WITSML accessible format. This may, for example, be used by a government agency to make available an archive of public domain well data to the industry. It does not support the Publish/Subscribe API and only exposes the GetFromStore method to the outside world. It may need to support AddToStore, UpdateInStore and DeleteFromStore for internal use in populating and managing the data store.

An Archival Profile Server will typically contain data from inactive wells and be used to provide WITSML data to applications and analysis software

The details of the WITSML objects available via the API calls are obtainable from the server via a query for the WITSML capabilities object.

Profile Summary

The following table summarizes the capabilities are expected of the different server profiles:

 Server Profile  Methods Available to Client

  Data Transfer

  (Provides access to near
  real-time data)

  WMLP_GetVersion
  WMLS_GetVersion

  WMLP_GetCapabilities
  WMLS_GetCapabilities

  WMLP_GetBaseMsg
  WMLS_GetBaseMsg

  WMLP_Subscribe

  WMLS_GetFromStore

  Data Management

  (Provides access to and
  manipulation of near
  real-time and archived
  data)

  WMLP_GetVersion
  WMLS_GetVersion

  WMLP_GetCapabilities
  WMLS_GetCapabilities

  WMLP_GetBaseMsg
  WMLS_GetBaseMsg

  WMLP_Subscribe

  WMLS_GetFromStore

  WMLS_AddToStore

  WMLS_UpdateInStore

  WMLS_DeleteFromStore

  Archival

  (Provides read-only
   access to historical
  archive data)

  WMLS_GetVersion

  WMLS_GetCapabilities

  WMLS_GetBaseMsg

  WMLS_GetFromStore

Schemas, XML documents, and Style sheets:

The Core API specification requires the following data object schemas and component sub-schemas. Component schemas are XML schemas, but they do not represent complete data objects.  A component schema may be included by more than one data object schema. All component schemas are prefixed with (cs_). Each component schema file generally defines one "type" that has the same name as the file name. Schema file cs_dataTypes.xsd defines many simplistic data types that are referenced by elements and attributes in data object and component schemas. It is directly or indirectly included in all data object schemas. Schema file cs_catalog.xsd defines all enumeration data types that are referenced by elements and attributes in data object and component schemas.

The following schemas represent the information content of parameters in the API interface. They do not represent data objects that can be queried using the API query mechanisms.

Capability of Client Schema

  Schemas   Links to Documents
  XSD
  Schema
  XML
  Document
  XML via
  Stylesheet
  Stylesheet
  Source
 obj_capClient.xsd XSD XML XML/XSL XSL
      cs_contact.xsd XSD      


Capability of Publisher Schema

  Schemas   Links to Documents
  XSD
  Schema
  XML
  Document
  XML via
  Stylesheet
  Stylesheet
  Source
 obj_capPublisher.xsd XSD XML XML/XSL XSL
      cs_contact.xsd XSD      
      cs_function.xsd XSD      


Capability of Server Schema

  Schemas   Links to Documents
  XSD
  Schema
  XML
  Document
  XML via
  Stylesheet
  Stylesheet
  Source
 obj_capServer.xsd XSD XML XML/XSL XSL
      cs_contact.xsd XSD      
      cs_function.xsd XSD      


Capability of Subscriber Schema

  Schemas   Links to Documents
  XSD
  Schema
  XML
  Document
  XML via
  Stylesheet
  Stylesheet
  Source
 obj_capSubscriber.xsd XSD XML XML/XSL XSL
      cs_contact.xsd XSD      


Capability of Subscription Schema

  Schemas   Links to Documents
  XSD
  Schema
  XML
  Document
  XML via
  Stylesheet
  Stylesheet
  Source
 obj_subscription.xsd XSD XML XML/XSL XSL


Copyright (c) 2005 Petrotechnical Open Standards Consortium, Inc. (POSC) All rights reserved.
POSC® and the POSC logo® are registered trademarks and WITSML™ and the WITSML logo™ are trademarks of POSC