Application Program Interface

VERSION v1.4.0

Enabling the right-time, seamless flow of well data

WITSML API between operators and service companies to speed
Specifications and enhance decision making..

Version: WITSML Application Programming Interface

Version 1.4.0
Abstract This document describes the components of the
WITSML Version 1.4.0 API. The components consist
of the Client/Server and Subscribe/Publish web
service interfaces.

Prepared by: Energistics and the WITSML SIG

Date published: 12 November 2008

Document type: formal specifications

Keywords: standards, energy, drilling, web service.

WITSML Application Program Interface

Document Information
DOCUMENT VERSION: 1.4.0 draft e
DATE: November 12, 2008
Technical Color: R:210, G:124, B:50
Language US English

This document was produced by

Energistics and the WITSML SIG.

Energistics™, POSC®, Epicentre®, WITSML™, PRODML™, Upstream Standards. Bottom Line Results.™,
The Energy Standards Resource Centre™ and their logos are trademarks or registered trademarks of
Energistics. Access, receipt, and/or use of these documents and all Energistics materials are generally
available to the public and are specifically governed by the Energistics Product Licensing Agreement
(http://www.energistics.org/posc/Product_License_Agreement.asp)

Page 2 of 147
WITSML Application Programming Interface

Amendment History
Version Date Comment By
1.4.0 12 November Changed the document name to remove “Core”. Gary
2008 Removed the term core from all references to the Masters
API.
Reformatted to new Energistics template.
 Section “1 Introduction” moved to the “Executive
Summary”.
 Section “2 Document Revisions” moved to this
“Amendment History”.
 Section “3 Terminology and Basic Concepts” was
renumbered to “2 Terminology and Basic
Concepts”.
 Section “4 API Objectives and Constraints”
moved to section “1 Introduction”.
 Section “5 Use Cases” moved to subsection “1.1
Scope”.
 The sections beginning with “6 The Interfaces”
were renumbered such that section “6” became
section “3”.
 Added the following subsections:
o 1.2 Document Structure
o 1.3 Intended Audiences
o 1.4 Usage, Intellectual Property Rights,
and Copyright
o 1.6 References
o “1.7 Conventions
o 1.8 Motivation
o 1.9 History
o 1.10 Future Plans
 All examples are now in a courier font.
 Almost all newlines used to create space
between paragraphs have been eliminated.
 Added figure captions.
 Corrected misspellings.

Page 3 of 147
WITSML Application Programming Interface

1.4.0d 3 November Issue 1.3.1-108 “log object and index curve values” Gary
2008 In section “STORE and PUBLISH behavior”, modified Masters
bullet 2.b to indicate that the structural range must
match the data range.
Issue 1.3.1-88 “dTim behavior in realtime”
In section “WMLS_GetFromStore”, modified note 14
to indicate that a value of dTimLastChange requests
realtime only data which has changed since that time.
1.4.0rc 30 July 2008 Issue 1.2-155 “Define optionsIn for optional cascaded Gary
deletes” Masters
Added “cascadedDelete” as an OptionsIn for section
“WMLS_DeleteFromStore” and modified “Note
#2”.Added error code -207 to section “Return Values”.
Deleted comment about referential integrity in section
“APPENDIX A”.
Issue 1.3.1-5 “WMLS_UpdateInStore behavior”
In section “Unique Identifiers (UID's)”, changed
“should” to “recommended” for globally unique uids
and added a table to summarize the Store uid
optionality requirements. In section
“WMLS_AddToStore”, documented that parentage
uid values are also required. In section
“WMLS_DeleteFromStore”, documented that QueryIn
does not conform to a schema. In section
“WMLS_UpdateInStore,” documented that the XMLin
parameter must conform to an update schema
variant. In section “WMLS_GetFromStore”, clarified
that QueryIn is not schema compliant.
Issue 1.3.1-54 “UpdateInStore and structural range”
In sections “APPENDIX D” and “STORE and
PUBLISH behavior”, documented that “append”
means to add new data whose index is greater than
the current maximum index. In section “STORE and
PUBLISH behavior”, clarify than a “replace” is
logically an “insert” if no data exists within the
specified range. In section “Return Values”, added
error codes -208 and -209.
Issue 1.3.1-96 “WITSML API 1.4a Draft
Documentation Issue”
In section “Choosing an Interface”, deleted the
paragraphs on “changed data”.
Issue 1.3.1-98 “Response to WITSML Version 1.4.0
Release Candidate”,
In section “Querying for Rows in a Systematically
Growing Object”, changed the returned
dataRowCount from 3 to 5. In section “APPENDIX B -
Unit of Measure”, add a subsection on default units.

Page 4 of 147
WITSML Application Programming Interface

1.4.0c 30 July 2008 Issue 1.3.1-102 “Response to WITSML Version 1.4.0 Gary
continu Release Candidate” Masters
ed In section “WMLS_AddToStore”, made some minor
clarifications on the realtime behavior and added
commonData to example. In section “#APPENDIX A -
Example Data Object Schema”, added commonData
to examples. In section “WMLS_UpdateInStore”,
eliminated the delete functionality. In section
”WMLS_DeleteFromStore”, added the delete
functionality from the update section, added the
capability of deleting non-containers using an empty
element or attribute, added note to look at growing-
object behavior and added comment on deleting sub-
nodes only requiring user update rights. In sections
“STORE and PUBLISH behavior”, “Deleting Rows in
a Systematically Growing Object” and “Deleting
Columns in a Systematically Growing Object”.
deleted now-invalid sentence about "normal behavior
that only an object can be deleted”. In several spots,
clarified that delete from store an also delete subset.
Issue 1.3.1-105 “Comments about WITSML version
1.4.0”
In section “Combining Data Item and Object
Selection”, documented the possibility of “greater
than” comparisons instead of “greater than or equal
to”.
Issue 1.3.1-107 “Clarification required for WitsML-
v1.3.1.1 log indexType”
In section “log Data Object Example”, eliminated
explicit example values for indexType. Used a valid
value for the example.

Page 5 of 147
WITSML Application Programming Interface

1.4.0a 14 July 2008 Changed all version references from “1.3.1” to Gary
“1.4.0”. Changed all namespace designations from Masters
“130” to “140” (including “140ex”).
Changed POSC to Energistics.
In section ”Sensor Data over WITSML”, fixed
example which had mnemonic as an attribute.
Issue 1.2-153 “Must document semantics of Get,
Add, Update and Delete for realtime”
Added a note to WMLS_DeleteFromStore that allows
deletion from realtime based on natural key match..
Documented that WMLS_UpdateInStore can update
realtime based on natural keys.
Issue 1.3-60 “6.3.1 Case Sensitivity- WISTSML 1.3.1
spec”
Documented in section “Case Sensitivity” that uids
are case sensitive in queries.
Issue 1.3.1-1 “What does "empty object" mean?”
Issue 1.3.1-19 “Query Start/End indexes special
handling (trajectory, mudlog)”
Added note to section “WMLS_GetFromStore” to
document that all criteria must be met or nothing will
be returned. Modified sections “STORE and
PUBLISH behavior”, “trajectory Data Object
Example”, “mudLog Data Object Example” and
“Querying for Rows in a Systematically Growing
Object“ to document that if no data is found in a
selection range then “nothing will be returned
because not all criteria will have been met” (i.e.,
eliminated statements that only header or empty
object will be returned).
Issue 1.3.1-5 “WMLS_UpdateInStore behavior”
Added notes to WMLS_UpdateInStore to clarify the
behavior. This changes the behavior for recurring
containers without a uid from ”insert and delete” to
“insert only”. Documented that the XMLin should
conform to a derived “read” schema where everything
is optional (same for WMLS_DeleteFromStore and
WMLS_GetFromStore – write schema for
WMLS_AddToStore). Documented that the result of
the update should conform to the “write” schema.
Issue 1.3.1-29 “Minor error in the WITSML API
documentation”
In section “Querying for Rows in a Systematically
Growing Object” changed the return value of
dataRowCount from 5 to 3.
Issue 1.3.1-40 “Getting Permission”
In section “Return Values”, added error code 206.
Issue 1.3.1-49 “Realtime Behavior”
Documented a note in section “WMLS_AddToStore
that the realtime object can be accessed via the store
interface using natural keys and that only the most
recent data will be retained

Page 6 of 147
WITSML Application Programming Interface

1.4.0a 14 July 2008 Issue 1.3.1-52 “Max # of log curve points returned” Gary
continu In section “WMLS_GetFromStore”, added to note 12. Masters
ed
Issue 1.3.1-58 “Minimum number of objects in a
WITSML document”
Documented that the XMLout from
“WMLS_GetFromStore” should conform to a derived
“read” schema where all elements and attributes are
optional. Deleted note 13.c. Added note that the
QueryIn template will not be schema compliant if it
contains empty values but should be compliant with
read schema if no empty values are used. In section
“Process interaction with ‘uom’”, did not remove “or
absent” because absent just means that the client did
not request a unit in which case the server returns the
value in a default unit.
Issue 1.3.1-63 “Detection of new data objects”
In section “Combining Data Item and Object
Selection”, documented the possibility of “greater
than or equal to” comparisons.
Issue 1.3.1-67 “Data quality and consistency”
In the section “Responsibilities” of the unit appendix,
documented that a unit can change.
Issue 1.3.1-75 “Change-detection behavior”
Added element objectGrowing to mudLog, log and
trajectory in section “APPENDIX A - Example Data
Object Schema”.
Inserted new “Appendix D: Special Handling of
Change Information” which incremented the letter
and numbering of the subsequent appendixes.
Changed the name of “Appendix D: Special Handling”
to “Appendix E: Special Handling of Growing
Objects”.
Issue 1.3.1-79 “abstractString and
abstractUncollapsedString do not handle a empty
string”
Assumed that this issue modified the agreement in
Issue 1.3.1-5 by eliminating any options which are not
“read” schema compliant (i.e., empty values for
attributes or non-container elements). Documented
that XMLin in WMLS_UpdateInStore must be “read”
schema compliant.
Issue 1.3.1-82 “WITSML Compression”
Documented a compression-method OptionsIn (with
a value of "gzip" or :”none”) in WMLS_AddToStore,
WMLS_GetFromStore, WMLS_UpdateInStore. Also
added a compression-direction OptionsIn (with a
value of "request", "response", "both") in
WMLS_GetFromStore. Defaulted to "response" for
Get. In section “Return Values“, defined an error code
for a requested compression option not supported.

Page 7 of 147
WITSML Application Programming Interface

1.4.0a 14 July 2008 Issue 1.3.1-83 “Object uid” Gary

continu In section “Unique Identifiers (UIDs)” documented Masters
ed that only a top level object (e.g., well) has a globally
unique uid. All dependent objects (e.g., wellbore)
have a uid that is unique within the context of its
nearest parent object.

Page 8 of 147
WITSML Application Programming Interface

Table of Contents

Executive Summary 13
1. Introduction 14
1.1 Scope 14
1.1.1 Sensor Data over WITSML 14
1.1.2 Rig Site Repository/Aggregator 18
1.2 Document Structure 20
1.3 Intended Audiences 21
1.4 Usage, Intellectual Property Rights, and Copyright 21
1.5 Terminology and Definitions 22
1.6 References 22
1.7 Conventions 22
1.8 Motivation 23
1.9 History 23
1.10 Future Plans 23
2. Terminology and Basic Concepts 24
2.1 WITSML] Object or Data Object 24
2.2 Unique Identifiers (UIDs) 25
2.3 Representation versus Transport 26
2.4 Transport versus Storage 26
2.5 [WITSML] Document 26
2.6 Subscribe/Publish Application Program Interface (API) 26
2.7 Client/Server Application Program Interface (API) 26
2.8 Versioning 27
2.8.1 Versioning - API Signature 27
2.8.2 Versioning - API Capabilities 28
2.8.3 Versioning - Executable Programs 28
2.8.4 Incrementing Version Numbers 28
3. The Interfaces 29
3.1 STORE and PUBLISH 29
3.2 Choosing an Interface 29
3.3 Common Behavior 30
3.3.1 Case Sensitivity 30
3.3.2 Query and Subscription Templates 31
4. STORE Interface 32
4.1 Introduction 32
4.2 Query Templates 34
4.2.1 Introduction 34
4.2.2 Data Item Selection 35
4.2.3 Object Selection 36
4.2.4 Combining Data Item and Object Selection 37
4.2.5 Selection using Recurring Data Items 38
4.2.6 Minimum Query Template 40
4.3 Authentication and Encryption 40
4.4 Capabilities Objects 41
4.4.1 Client Capabilities (capClient) Object 41
4.4.2 Server Capabilities (capServer) Object 41
4.4.3 Capabilities by Object 42
4.5 STORE Functions 45
4.5.1 WMLS_AddToStore 46
4.5.2 WMLS_DeleteFromStore 48
4.5.3 WMLS_GetBaseMsg 52

Page 9 of 147
WITSML Application Programming Interface

4.5.4 WMLS_GetCap 53
4.5.5 WMLS_GetFromStore 54
4.5.6 WMLS_GetVersion 57
4.5.7 WMLS_UpdateInStore 58
4.6 STORE Interface - WSDL File 62
4.6.1 File Listing 63
4.6.2 Narrative 68
5. PUBLISH Interface 70
5.1 Introduction 70
5.2 Subscription Requests 73
5.2.1 action attribute - the action being requested 75
5.2.1.1 action=”add” - add a new subscription 75
5.2.1.2 action=”modify” - modify an existing subscription 76
5.2.1.3 action=”cancel” - cancel one or all existing subscriptions 77
5.2.1.4 action=”verify” - verify an existing Subscription 78
5.2.1.5 action=”retransmit” - retransmit the realtime headers 79
5.2.2 retCode attribute - the return code 79
5.2.3 idSub attribute - the subscription identifier 80
5.2.4 test attribute - test network connectivity 80
5.2.5 host, process, port and encrypt attributes - specify the subscriber’s URL 81
5.2.6 idPub attribute - identify the Publisher 82
5.2.7 retry attribute - the error retry count 82
5.2.8 updateInterval attribute - limit the publication rate 83
5.2.9 Subscription Object Attribute Summary 84
5.3 Subscription Templates 85
5.3.1 Realtime Example 88
5.4 Publishing and Maintaining Subscriptions 91
5.5 POST Request 92
5.5.1 Syntax 92
5.5.2 Notes: 93
5.5.3 Example: 93
5.6 Authentication and Encryption 93
5.7 Capabilities Objects 94
5.7.1 Subscriber Capabilities (capSubscriber) Object 94
5.7.2 Publisher Capabilities (capPublisher) Object 94
5.7.3 Capabilities by Object 95
5.8 PUBLISH Functions 98
5.8.1 WMLP_GetBaseMsg 98
5.8.2 WMLP_GetCap 99
5.8.3 WMLP_GetVersion 100
5.8.4 WMLP_Subscribe 101
5.9 PUBLISH Interface - WSDL File 102
5.9.1 File Listing 103
5.9.2 Narrative 106
6. APPENDIX A - Example Data Object Schema 108
7. APPENDIX B - Unit of Measure 113
7.1 Overview 113
7.2 Basics 113
7.3 Process interaction with ‘uom’ 114
7.4 Server defaults 114
7.5 Responsibilities 115
7.6 Updating 115
8. APPENDIX C - Defined Values 116
8.1 Return Values 116
9. APPENDIX D – Special Handling of Change Information 118
10. APPENDIX E – Special Handling of Growing Objects 120

Page 10 of 147
WITSML Application Programming Interface

10.1 Randomly growing objects 122

10.2 Systematically Growing Objects 123
10.3 STORE and PUBLISH behavior 124
10.4 STORE Interface Examples 127
10.4.1 trajectory Data Object Example 128
10.4.2 mudLog Data Object Example 130
10.4.3 log Data Object Example 132
10.4.3.1 Querying for Rows in a Systematically Growing Object 135
10.4.3.2 Updating Rows in a Systematically Growing Object 140
10.4.3.3 Deleting Rows in a Systematically Growing Object 142
10.4.3.4 Adding Columns in a Systematically Growing Object 143
10.4.3.5 Deleting Columns in a Systematically Growing Object 144
10.5 PUBLISH Interface Example 145
11. APPENDIX F - Service Agreement 147
12. APPENDIX G - Custom Data 148
12.1 Namespace 148

Page 11 of 147
WITSML Application Programming Interface

Executive Summary
This document describes the components of the WITSML Version 1.4.0 Application Programming Interface
(API). These components consist of the Client/Server and Subscribe/Publish interfaces.

Page 12 of 147
WITSML Application Programming Interface

1. Introduction
The WITSML API is intended to be platform independent. It should be useable by any programming language
that can invoke a function-call interface. An object-oriented language is not required, although object-oriented
wrappers over the WITSML API could be developed.
The API is specified in function-call syntax, and specifies simple data types (integers, strings, etc) for
parameters and return values. Pointers and structures are not used.
Unless noted otherwise, function calls are synchronous (blocking).
The concurrent use of API functions by multiple client applications is dependent on the particular API
implementation.
This specification describes only the external interfaces exposed by the API, not any particular
implementation. The internal implementation of the API can and will vary. All references in this document to
implementation scenarios are for the purpose of example only.

1.1 Scope
The following use cases are intended to illustrate how the two API interfaces - Client/Server and
Subscribe/Publish - might be used. The use cases do not necessarily illustrate recommended solutions to
specific business requirements.
1.1.1 Sensor Data over WITSML
This example illustrates how WITSML realtime data objects could be transferred using the Subscribe/Publish
mode from a sensor aggregator application on a rig to an application in the operating company’s offices.
The sensor aggregator system is the Publisher and the office system is the Subscriber. The realtime data
objects are “pushed” from the Publisher to the Subscriber.
The first phase in the process involves “subscribing” to one or more of the Publisher’s available realtime data
channels. To do this, the potential Subscriber sends a subscription request to the Publisher. The subscription
request will specify, among other things, that the Subscriber wishes to receive the WITSML realtime data
object and which channels of the realtime object.
In order to know what data object types and realtime channels it can request, the Subscriber can first ask the
Publisher for that information.
The Subscriber can determine what data object types are available by using SOAP to invoke the Publisher’s
WMLP_GetCap (Get Capabilities) function, denoted by (1) in the diagram below.

Page 13 of 147
WITSML Application Programming Interface

SUBSCRIBING
Publisher Subscriber

WMLP_GetCap
1
sensor Publisher Capabilities Object
2

WMLS_GetFromStore 3
sensor
sensor aggregator Available Channels
4 office
application application
WMLP_Subscribe
(and send Subscriber
sensor
Capabilities Object)
5
Subscription Identifier
7 6

Subscriptions
Storesection
"ines used
to create
Figure 1: Subscribing Scenario
space
between function returns the Publisher’s Capabilities object (2) to the Subscriber,
The Publisher's WMLP_GetCap
paragraphs
which lists the data object types the Publisher can provide. In this example, the Publisher would list only the
have
realtime data object type been
in the returned Capabilities object, as that is the only data object type it can publish.
eliminated.
The Subscriber then needs to know what channels are available for the realtime object. This information is
not conveyed in the Publisher's Capabilities object, since it can vary by well, wellbore or time. Instead, the
Subscriber can query the Publisher for this information (3), using the WMLS_GetFromStore function. For
example, the following query would return the channel mnemonics and well/wellbore identifiers for all realtime
objects on the Publisher (4).
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="" uidWellbore="">
<channel>
<mnemonic />
</channel>
</realtime>
</realtimes>
If the Subscriber already knew the well/wellbore identifiers, it could have specified them in the query:
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<channel>
<mnemonic />
</channel>
</realtime>
</realtimes>
This could result in a smaller result set and a quicker, more efficient query.

Page 14 of 147
WITSML Application Programming Interface

Note

Notice that we said the Subscriber invoked the "Publisher's" WMLS_GetFromStore function.
But WMLS_GetFromStore is a STORE interface function, not a Publisher function.
What's going on here?
The answer is that in order to allow potential Subscribers the ability to dynamically
determine what data object instances (not merely the object types) that are available for
subscription, a Publisher must implement a part of the STORE interface; it must be both a
Publisher and a Server. However, in this case, it is not necessary for the Publisher system
to implement all the STORE interface functions, but only the WMLS_GetFromStore function.
It can then indicate its limited implementation by including only the WMLS_GetFromStore
function in the capServer object it provides to Client systems.

Once the Subscriber has determined which channels on which wells and wellbores are available to be
published, it then invokes the Publisher’s WMLP_Subscribe function (5) and subscribes to one or more
realtime channels. Included in the Subscription request (which is itself passed as a WITSML data object) are
the Subscriber’s host name and various other information that the Publisher will need when it has data to
send to the Subscriber. The Subscriber also passes its own Capabilities object to the Publisher. 1 Thus, both
the Publisher and Subscriber now know each other’s capabilities.
So that subscriptions are not lost across restarts of the Publisher system, the Publisher then records the
subscription in a non-volatile store (7) and returns a unique subscription identifier to the Subscriber (6). The
Subscriber can later use this subscription identifier to cancel, modify or verify the subscription.
Once the subscription has been accepted, we are then ready for the second phase of the process: publishing
the data.
Whenever new or changed data for the specified channels become available – perhaps immediately after the
subscription was received or at some time later - the sensor aggregator application will create a WITSML
realtime data object and send it to all Subscribers who are subscribed to that channel of the realtime data
object.
The sensor aggregator application is responsible for parsing the data coming in from the sensors, associating
that data to the appropriate data items defined for the WITSML realtime data object, supplying any missing
data items and creating the WITSML realtime data objects.
The sensor aggregator application then uses HTTP/S POST to send the WITSML data objects to the
Subscriber, as denoted by (2) in the diagram on the next page.

1
for example, the Subscriber will convey in its capabilities object the version of the API that it implements. This will allow new versions

of the API to be implemented without disrupting existing systems.

Page 15 of 147
WITSML Application Programming Interface

PUBLISHING

Publisher Subscriber

HTTP/S POST Web Server

sensor
3

sensor
2
Subscriber Process
sensor aggregator
application
1
4
sensor WMLI
Implementation

Proprietary
Data Store

Figure 2: Publishing Scenario

On the Subscriber system, a process running under a Web server receives the WITSML data objects (3), 2
extracts the data items from the data object and then persists them to its own internal data store (4).
Note

While this use case illustrated using the Subscribe/Publish API to transport the WITSML
realtime data (notification) object, it’s important to note that the Subscribe/Publish API is
used to issue notifications of changes to any of the WITSML data object types. For
example, a Subscriber can request that a Publisher send it notifications of any new or
changed well objects. Although suited for use in situations where new transient data is
periodically available - such as with the realtime object - the Subscribe/Publish API is not
restricted to use for only the realtime data object.

2
because HTTP/S is used to transport the published data, this use case shows the Subscriber process running under a generic HTTP/S

Server (aka, “web server”). A Subscriber is free to implement its own dedicated, embedded HTTP/S processing if it wishes.

Page 16 of 147
WITSML Application Programming Interface

1.1.2 Rig Site Repository/Aggregator

This example illustrates how a server located at a rig site could act as a central repository for data related to
its well(s).
Some of the data stored in such a repository would be collected by other front-end applications used on the
rig, such as drilling management systems. These applications would act as clients, and use the rig server as
a persistent store, to either augment or replace their own internal proprietary databases. These applications
could provide the user interface for initially defining the well, accepting manual input and for producing and
distributing periodic reports.
Other applications on the rig would use the server as a realtime data Subscriber, in a similar manner to what
was illustrated in the first use case. Sensor aggregator applications would collect realtime data and publish it
to a Subscriber process running on the rig server.
Backend applications located either at the rig or at the office could then act as Clients and retrieve data from
the server on-request. A data analysis application, for example, could populate its own well definition based
on the well object it retrieves from the server, and then retrieve the stored log curves for analysis.

drilling
sensor management
application
data analysis
sensor application
sensor aggregator
application
On-Request

via
sensor
SOAP
REALTIME On-Request

objects via
Web Server
via SOAP

HTTP

POST

Subscriber WMLS
Process Implementation

Proprietary
Data Store

Figure 3: Aggregator Scenario

In this example, the rig server performs as both a Subscriber and Server. When being used as a persistent
store by the drilling management or data analysis applications, it is acting as a Server. When receiving data
from the sensor aggregator application, it is operating as a Subscriber.
Most of the internal processes involved in receiving the realtime data and persisting it are the same as for the
Subscribe/Publish use case described earlier, and we have omitted some of that detail here (the process of
requesting the subscription has been omitted, for example, although it is still applicable).
However, we have made one change of note to the Subscriber processing: in the first use case, we showed
the Subscriber process writing directly to its own proprietary data store.

Page 17 of 147
WITSML Application Programming Interface

But in this case, we show the Subscriber process invoking the STORE interface instead. Since the STORE
interface must be implemented on this server anyway (to provide access for clients), it makes sense to use
this same implementation to store the realtime data received by the Subscriber process. This would assume
that log data is being stored – not realtime data.
There are typically different implementation considerations for storing large volumes of data – particularly if
received in “realtime” mode - versus supporting relatively lower volume transactional updates or queries. In
order to maintain good performance in both modes, the fairly static and low volume data objects such as well,
rig and wellbore might be stored by the STORE implementation in one database while the realtime data
objects received from the sensor application might be stored as logs in a different database, using a different
storage mechanism. But client applications are not aware of this; they merely request STORE to access a
particular object, regardless of how it is stored.

clients "see" only one

virtual store

WMLS
Implementation

Data Store Data Store

for high volume for low volume
objects objects

Figure 4: High Data Volume Scenario

Page 18 of 147
WITSML Application Programming Interface

1.2 Document Structure

This document defines the web service which can be used to transport XML that conforms to the WITSML
Data Schema specification.

Orientation

Specification Application
Programming Interface Client

Server
Data Schema

Reference

Training

Documents Code

Figure 5: WITSML Standards Documentation Overview

Section 1, the introduction, presents the context for the document as a whole. It contains descriptions of the
intended audience, intellectual property and copyright statements, terms and definitions, references, and
background and history of this document and its content.
Section 2, Terminology and Basic Concepts, describes terminology and concepts which are fundamental to
this document.
Section 3, The Interfaces, describes high level differences between two alternative sets of methods: STORE
and PUBLISH.
Section 4. STORE Interface, describes the methods used to add, update, delete and query data objects.
Section 5, PUBLISH Interface, describes the methods used for subscriptions related to automatically
receiving a copy of data objects when they change.
Section 6, 9 APPENDIX A - Example Data Object Schema, describes a representative schema to which the
examples conform.
Section 7, APPENDIX B - Unit of Measure, describes how units of measure are handled.
Section 8, APPENDIX C - Defined Values, describes return codes.
Section 9, APPENDIX D – Special Handling of Change Information, describes special STORE behavior
related to capturing information about when an object changes in a WITSML server.
Section 10, APPENDIX E – Special Handling of Growing Objects, describes special behavior for objects to
which data is added over time.
Section 11, APPENDIX F - Service Agreement, describes information that is relevant to contractual
relationships between a service provider and a service consumer.
Section 12, APPENDIX G - Custom Data, describes the handling of a special capability that can be used for
proprietary extensions to the data schema.
The reader of a printed copy of this document is advised to check that the printed copy is the current version
by checking the Energistics web site, http://www.energistics.org.

Page 19 of 147
WITSML Application Programming Interface

1.3 Intended Audiences

In this section, the types of people who are primary and secondary intended readers and users of this
document and other related documents are identified.

E & P Business/Asset Manager

IT Director

Integration Project Manager

ROLE

Enterprise Architect

Data Architect
Drilling Engineer

Application Manager
USE KEY

A= PRIMARY DOCUMENT
Key document to read
B=SECONDARY DOCUMENT
Good material to review
C= LESS USEFUL
Review as needed
DOCUMENTATION

WITSML Application Programming Interface C C B B C A B

WITSML Data Schema Specification C B C B B B A
Figure 6: WITSML Standards Documentation Reader’s Guide

1.4 Usage, Intellectual Property Rights, and Copyright

The material described in this document was developed by Energistics and is the intellectual property of
Energistics. Energistics develops material for open, public use in order that the material can be of maximum
value to the industry as a whole.
Use of the material in this document is governed by the Energistics Intellectual Property Policy document and
the Product Licensing Agreement, both of which can be found on the Energistics Web Site,
http:/www.energistics.org.
The following statements characterize the intent of the Energistics use policies:
 That all material developed and published by Energistics, and used by other persons or
organizations, remain under Energistics’ control.
 Others should be able to comment on published Energistics materials.
 Others may copy the material to enable its use.
 Users of Energistics materials acknowledge Energistics as the source.
No one may restrict the usage and/or dissemination of Energistics published materials by attempting to
copyright, trademark, license, or to use any other restrictive practice.

Page 20 of 147
WITSML Application Programming Interface

1.5 Terminology and Definitions

Table 1: Terms

Term Definition
API Application Programming Interface. Within this document, this refers
to web services.
SOAP Simple Object Access Protocol
WITSML Wellsite Information Transfer Standard ML
WMLP A contraction of “WITSML Publish”.
WMLS A contraction of “WITSML Store”.
XML Extensible Markup Language

1.6 References
Table 2: References

Organiza Standards Standards Names Dates Remarks

tions Designations
IETF HTTP/1.1 HTTP 1.1 June 1999 Used for transport.
Standard
W3C SOAP 1.1 SOAP 1.1 8 May 2000 Used for transport.
Standard
W3C WSDL 1.1 WSDL 1.1 15 March Used to define normative data
Standard 2001 structures of web service methods.
W3C XML Schema XML Schema Part 28 October Used to define data structures in WSDL
1.1 1: Structures 2004 and in Data Schemas.
W3C XML Schema XML Schema Part 28 October Used to define data structures in WSDL
1.1 2: Datatypes 2004 and in Data Schemas.
IETF rfc 4122 A Universally July 2005 May be used to create globally unique
Unique IDentifier identifiers for independent objects.
(UUID) URN
Namespace
W3C HTML 4.01 application/x-www- 24 December Used to encode parameter-value pairs.
Specification form-urlencoded 1999

1.7 Conventions
This section describes the use of key terms, notations, and abbreviations in this document.
THIS DOCUMENT DOES NOT CURENTLY CONFORM TO THESE 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 RFC
2119. (http://www.ietf.org/rfc/rfc2119.txt)
Text in a Grey underlined typeface represents a hyperlink
Text in Green highlights a statement that defines something that is included in scope.
Text in Red highlights a statement that defines something that is excluded from scope.

Page 21 of 147
WITSML Application Programming Interface

Text in italic blue represents information about concepts and facilities that might appear in a future version of
this material

1.8 Motivation
A primary focus for the changes in this version was to enhance support of automated workflows. The addition
of “APPENDIX D – Special Handling of Change Information” was a direct result of this effort. Another result
was clarification of STORE handling of realtime data. Most other changes represent a continual tightening of
the specifications.

1.9 History
WITSML was initially developed by the WITSML project, an oil industry initiative sponsored by BP and Statoil,
and later by Shell, as a new standard for drilling information transfer. Initial participation was from the major
service companies Baker Hughes, GeoQuest, Halliburton, Landmark and Schlumberger. As of the completion
of WITSML V1.2 in March 2003, POSC (now called Energistics) accepted custody of WITSML and is
managing the support and future evolution of WITSML through the WITSML Special Interest Group.
WITSML was designed to be a more modern alternative to WITS (Wellsite Information Transfer Standard)
and some of the original semantic content of the Data Schemas was derived from the WITS specification.
The most recent previous version of this specification was v1.3.1 which was released in December 2005.

1.10 Future Plans

The user community for the WITSML Standards is the Energistics WITSML Special Interest Group (WITSML
SIG). The SIG has ongoing activities to monitor WITSML use and to identify, refine, and agree on
recommendations for enhancements. Energistics and the SIG work together on a formal version
management process that can lead to future versions of the WITSML Standards being planned, developed,
and released.

Page 22 of 147
WITSML Application Programming Interface

2. Terminology and Basic Concepts

2.1 [WITSML] Object or Data Object
A WITSML data object is a logical organization and grouping of the data items associated with the major
components and operations involved in drilling a well. For example, a group known as the rig “data object”
would contain the data items related to the rig, such as its owner, type and manufacturer.
► A WITSML data object is not, however, a formal programming object
(with methods, properties, events, etc).
These data objects can be organized into a single hierarchical “tree”, with the well object at the top of the
tree. The well object is the parent of one or more wellbore objects, a wellbore object has one or more
children, and so on.

well

wellbore

mudLog trajectory log

Figure 7: Implied Object Hierarchy

► When being exchanged between systems, each of the logical objects is represented as a physical XML
document.
That is, all the data items in one wellbore object are transported as one XML document, which is simply a text
file. In order to transport the complete tree shown above, five XML documents are required. The objects can
be logically thought of as being in one tree, but they are physically represented as five separate documents.
Since each object carries with it its own identifier and the identifier(s) of its parent, grand-parent, etc, the tree
can be reconstructed from the individual documents.

Page 23 of 147
WITSML Application Programming Interface

2.2 Unique Identifiers (UIDs)

Every WITSML data object has within it an identifier, and the identifier(s) of its ancestry. For instance, a Mud
Log (mudLog) object has an identifier of itself, and the identifiers of its parent (wellbore) object and its
grandparent (well) object.
These identifiers are known as "unique identifiers" or UIDs. The Mud Log’s own identifier is its uid attribute, its
parent wellbore is its uidWellbore attribute and its grandparent is its uidWell attribute.
It is recommended that the uid of each singular independent object be made globally unique by generating
uids according to UUID algorithm of rfc 4122 (http://www.faqs.org/rfcs/rfc4122.html). An independent object is
one which is not identified within the context of another object (e.g., well is an independent object). The
unique identifier of all dependent objects (e.g., wellbore) are only required to be unique within the context of
its nearest parent object. For example, the unique identifier in trajectory is only required to be unique within
the context of its parent wellbore.
Because these system oriented-unique identifiers might contain internal keys or other not-easily-readable
values, elements have been defined to carry more "human readable" names of an object and its parentage,
such as nameWell, nameWellbore, name, etc.
Each repeatable (i.e., has maxOccurs greater than 1) container element (i.e., has element children) that
needs to be individually queried by the server (e.g., update a single node) must have a uid attribute. If an
element has a uid attribute then all repeatable parent elements must also have a uid attribute. A non-
repeatable element should not have a uid attribute. For the purposes of this discussion, a foreign key to a
non-parent node is not considered to be a uid value. The only purpose of uid values is to insure uniqueness
of nodes in a server. Best practice should not assume any semantic content of a uid value.
Each individual child uid value is only required to be unique within the context of its nearest repeatable parent
node. The unique key for any node is the combination of all uid values in the hierarchy down to and including
that node. Each uid value may actually be unique within a broader context but best practice should not
assume a broader context.
Some WITSML objects that utilize the plural convention may combine to represent one hierarchical tree (e.g.,
well/wellbore/...). For objects that represent a common hierarchy, the repeatable parent node may exist in
another object that is referenced using a parent key. For example, the wellbore object would reference a well
uid. Since the unique key for a node must necessarily include the unique key for its nearest repeatable parent
node, the unique key of a child object of a wellbore object would include the wellbore key (i.e., a well uid
value and a wellbore uid value) in addition to its own uid value.
Similarly, any "natural" human recognizable identifiers (e.g., name, index) for a node should be populated
with values that identify the node within the context of the nearest repeatable parent node. For objects that
represent a common hierarchy, the name pointer to parent another object is part of the uniqueness of that
object. The possibly-unique natural key for a node is the combination of all natural identifiers in the hierarchy
down to and including that node. While natural keys are not required to be unique within the context of a
server, every effort should be made to insure their uniqueness in order to eliminate ambiguity. Where the
natural keys are not unique then human inspection is required to determine if the nodes represent the same
thing (and they should be combined) or if they represent different things (and their identity should be
changed).
The following table summarizes the optionality requirements of uid attributes in the WMLS (Store) functions.

Table 3: WMLS uid optionality

Get From Store Add To Store Update In Store Delete From Store
Result Request Request Request
object uid optional optional required required
parentage uid optional required required required
child uid optional required required optional

Page 24 of 147
WITSML Application Programming Interface

2.3 Representation versus Transport

WITSML data objects being exchanged between systems are always represented as XML documents. The
WITSML XML Schemas define the format of these objects when they are represented as XML documents.
Since XML documents are simply text files, they can be transported by various means, such as email or other
file transfer method. A WITSML data object could even be in the form of a printed or Faxed document.
The WITSML API described in this document specifies a standardized way of electronically transporting
WITSML data objects between systems using the HTTP/S-based protocols. However, it is acceptable for
companies to agree to send and receive WITSML data streams without the use of the WITSML API.

We will use the term "HTTP" in this document to specify "Hypertext Transport Protocol (un-
encrypted)".
We will use the term "HTTPS" to specify "Hypertext Transport Protocol over Secure Sockets
Layer (encrypted)"
We will use the term "HTTP/S" when generically referring to both HTTP and HTTPS.

2.4 Transport versus Storage

WITSML data objects being transported between systems must be represented as XML documents.
The specification does not dictate, however, how the WITSML data objects are to be stored within those
systems. The data objects might be stored as text files or in a database system.
WITSML defines an interoperability specification concerning how the data must be represented and a
standard way of exchanging the data electronically. It does not define the storage mechanism.

2.5 [WITSML] Document

One or more complete WITSML data objects - such as well, wellbore or log - when they are represented as
an XML text string. Consistent with the way the XML literature uses the word "document", the term does not
necessarily mean a physical file. A text string of XML being sent via an HTTP/S POST is also an XML
document. If that XML represents one or more WITSML objects, it is then a WITSML document. Also see
WITSML object/Data Object.

2.6 Subscribe/Publish Application Program Interface (API)

Using the Subscribe/Publish API, WITSML data objects are periodically “pushed” from a Publisher to a
Subscriber. The Subscriber defines what data objects it wishes to have sent to it by sending a subscription to
the Publisher. The Subscriber then waits to receive the requested data objects. When new or changed data
objects are available which match the subscription - either immediately or at some time in the future - the
Publisher sends them to the Subscriber. Subscribe/Publish uses the SOAP protocol to transport the
subscription/acknowledgment between the Subscriber and Publisher, and uses the HTTP/S POST protocol to
push the data objects from the Publisher to the Subscriber.
► The Subscribe/Publish API is also known as the PUBLISH interface, or by the prefix of its functions:
“WMLP” (a contraction of “WITSML Publish”).

2.7 Client/Server Application Program Interface (API)

In Client/Server mode, WITSML data objects are “pulled” on-demand by a Client from a Server. The Client
makes a request of the Server, and the Server immediately responds with an acknowledgement or an error
code. The Client can add, update, delete and retrieve WITSML data objects on the Server. Client/Server uses
the SOAP protocol to transport the requests/responses between Client and Server.
► The Client/Server API is also known as the STORE interface, or by the prefix of its functions:
“WMLS” (a contraction of “WITSML Store”).

Page 25 of 147
WITSML Application Programming Interface

2.8 Versioning
There are four major entities in the WITSML specification that can be "versioned":
 the data objects
 the API signature
 the API capabilities
 the executable programs
Each of these four entities use versioning in slightly different contexts:
Versioning - Data Objects
For a data object, the version number specifies the version of the XML Data Schema against which the object
can be validated. The number is conveyed in the version attribute of the data object's plural container
element:
<wells version="1.4.0.0" … >
<well … />
</wells>
The example indicates that the well object is compliant with the WITSML 1.4.0.0 XML Data Schemas.

A client or subscriber can also determine the version of WITSML data supported by the
server via WMLS_GetVersion.

2.8.1 Versioning - API Signature

The API signature is a contract between the provider system (server or publisher)
and the consumer system (client or subscriber) that specifies how the Web Service will interact in terms of
what function calls are available, their parameters, the protocols they run over and where the service is
located.
The contract is defined in a Web Services Description Language (WSDL) file, described in this document.
Once defined, it should not change, else consumer applications that were written to an earlier specification
might "break".
When new functionality needs to be added, the contract - the WSDL file - can be updated (but hopefully in a
way that extends but does not break the existing functionality!). Or if the changes are such that it is not
possible to provide backward compatibility to existing clients, a completely new WSDL file (with a different
Web Service name) could be published.
A new or updated WSDL file constitutes a new version of the API signature. The version of the WSDL file is
specified by the URI of the targetNamespace attribute of its <definitions> element:
<definitions name='WMLS' targetNamespace='http://www.witsml.org/wsdl/120' …
There is also a <documentation> element in the WSDL file that specifies the version in a more easily-
readable form:
<documentation>WITSML Version 1.2.0 STORE interface WSDL file </documentation>
Client programs should use the targetNamespace URI rather than the <documentation> element to
determine the version of the WSDL file.
The presently published WSDL file is version 1.2.0.

Page 26 of 147
WITSML Application Programming Interface

2.8.2 Versioning - API Capabilities

The API capabilities describe the "details" about how the client/server and subscriber/publisher interfaces
operate. An API's capabilities further define and clarify the basic functionality which the API signature
advertises (think of the capabilities as being the "fine print" on the contract). For example, while the API
signature says that a client can issue a "Get From Store" function call to retrieve WITSML data objects from a
server, it is the API's capabilities that determine which data objects are available on a particular server.
An API's capabilities - or more precisely, the capabilities of a particular implementation of the API - are
conveyed in Capabilities Objects, which are a special kind of WITSML API object. There is a Capabilities
Object for a Server, a Client, a Publisher and a Subscriber. The version of the capabilities implemented by a
WITSML component, such as a Server, is conveyed in the apiVers attribute of the Capabilities Object.
Here is an example of a Server's capabilities (capServer) object showing the version:
<capServers … >
<capServer apiVers="1.4.0">
…
<capServer>
</capServers>
The Capabilities Objects are exchanged using the WMLx_GetCap functions of the API or by passing the
objects as parameters to the function calls.
2.8.3 Versioning - Executable Programs
The version or "build" number of an executable program is provided as additional information, and can be
used to assist in troubleshooting, for example. The program's version/build number is chosen solely by the
particular implementer, and does not necessarily correlate to the version numbering scheme used by the
other WITSML entities.
Here is an example of a Server's capabilities (capServer) object showing the executable version:
<capServers ...>
<capServer>
<version>1.4.0.1463</version>
<capServer>
</capServers>

2.8.4 Incrementing Version Numbers

Note that the version numbering of the various WITSML entities is mostly independent of one another. The
version numbers may increment at different rates and times for different parts of the WITSML specification.
In the future, it is expected that the API signature will almost "never" change, while the data objects will likely
experience the greatest rate of change, with the API implementation's rate of change somewhere in the
middle. And, of course, changes to program version/build numbers will vary by implementation.

Page 27 of 147
WITSML Application Programming Interface

3. The Interfaces
3.1 STORE and PUBLISH
The WITSML API defines two interfaces:
STORE (aka, Client/Server or WMLS)
PUBLISH (aka, Subscribe/Publish or WMLP)
The STORE interface provides Client applications access to WITSML data objects stored on a Server.
The PUBLISH interface provides Subscriber applications the ability to query a Publisher for what WITSML
data object types are available for publication, to subscribe to changes to data objects to be published at
some time in the future and to maintain the subscription requests held by the Publisher.
Both the STORE and PUBLISH interfaces are exposed to client applications via SOAP (Remote Procedure
Call-style).

3.2 Choosing an Interface

In addition to their functional differences, the STORE and PUBLISH interfaces also differ in their underlying
goals and philosophies.
The STORE interface is an immediate-response, synchronous client-server mechanism. Its reliability is
subject only to the limitations of the underlying transport protocols.
On the other hand, the PUBLISH interface - or more precisely, the actual push or publication of the requested
data - is a best-effort, delayed-action delivery mechanism.
While features have been included in the PUBLISH interface to reduce the likelihood of data loss, it’s still
possible for the PUBLISH interface to fail to deliver requested data objects to a subscriber, such as when a
subscriber is not ready to receive the data objects when they are published. The publisher does not, for
example, “queue” undeliverable data for later delivery, once the error retry count has been exhausted. Every
reasonable attempt will be made by the publisher to deliver the data objects, but if connectivity is lost for any
reason the specification does not require or imply that undelivered data objects will be retained for resending
once connectivity is re-established.
The system designer should take into account these design differences between the STORE and PUBLISH
interfaces when choosing which is applicable for a particular application. For situations where 100% data
reliability is required, the “pull” model of the STORE interface is available. For situations in which periodic
polling of a server for new/changed data objects isn’t possible (i.e., the data source has no persistent store)
or isn’t desirable (i.e., due to load on the network or client), the PUBLISH model provides the ability to publish
changes to data objects in an efficient, but not guaranteed, manner.

Page 28 of 147
WITSML Application Programming Interface

3.3 Common Behavior

3.3.1 Case Sensitivity
All functions exposed by the STORE and PUBLISH interfaces preserve upper and lower case characters
present in all data items that have an underlying data type of “String”.
The “country” data item of the well object, for example, has a WITSML-defined data type which is derived
from the W3C-data type of “String”.
Therefore, if the country data item contains “Norway” when stored to a server, it will contain exactly the same
case - “Norway” - when later retrieved by a Client application, or when published to a Subscriber.
However, when performing a query against a (non-uid) stored data item, the WITSML interfaces perform
case-insensitive comparisons. If a client application wishes to retrieve (or have published to it) all well objects
where “country is equal to Norway”, it could simply specify “norway” and have returned to it objects
containing:
<country>Norway</country>
<country>norway</country>
<country>NORWAY</country>
… or any other combination of character case.
When performing a query against a uid value, the WITSML interfaces perform case-sensitive comparisons.
Multiple objects should not be returned for a query using uid values.
► WITSML servers preserve case in persisted string data items, but are not case sensitive when servicing
STORE or PUBLISH interface queries against those persisted data items. The exception is uid values which
are case sensitive in queries.
Stated another way: (non-uid) string data values which differ only in character case are treated as being
“equal”.

Page 29 of 147
WITSML Application Programming Interface

3.3.2 Query and Subscription Templates

Both the STORE and PUBLISH interfaces utilize the concept of a “Template” to specify which data objects
and data items within those objects are to be accessed.
A Template is a well-formed XML document that specifies “by example” what WITSML data objects - and data
items within those objects - are to be acted-upon.
The STORE interface uses Query Templates to specify the objects being accessed by the Client application,
and the PUBLISH interface uses Subscription Templates to specify the objects to be published to the
Subscriber.
Both Query and Subscription Templates are based on the idea of "you get only what you ask for". For
example, if you want a list of well objects with the <name> and <country> XML data elements, you would
specify:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well uid="">
<name/>
<country/>
</well>
</wells>
The returned well data objects might contain:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well uid="W-1">
<name>6507/7-1</name>
<country>Norway</country>
</well>
<well uid="W-2">
<name>6507/7-2</name>
<country>Norway</country>
</well>
<well uid="W-3">
<name>EI128/10-2</name>
<country>United States</country>
</well>
</wells>

CONCEPTS

Notice that no other attributes or child elements of the well element were returned in our example,
even those that might be defined as “required” by the WITSML schemas. If an attribute/element isn’t
explicitly requested in the Template, it will not be present in the returned objects.
If the client/subscriber requires a valid XML document be returned, it must explicitly include all
schema-mandatory attributes and elements in the query template.
Since a Template is permitted to omit required elements/attributes of a data object, a Template
cannot (typically) be validated against the WITSML schemas. A Template is a well-formed XML
document, but not necessarily a valid XML document.

Although the Query and Subscription Templates are almost identical in concept, they have minor differences
in their usage, and so we’ll discuss them individually in the STORE and PUBLISH interfaces.

Page 30 of 147
WITSML Application Programming Interface

4. STORE Interface
4.1 Introduction
The STORE interface provides Client applications the ability to:
 add a WITSML data object to a Server
 update an existing WITSML data object on a Server
 delete an existing WITSML data object (or a subset) on a Server
 query (retrieve) one or more existing WITSML data objects from a Server
When using the STORE interface, the transfer of WITSML data objects between client and server
is initiated by the client. The client application issues the request to access the stored objects - or
to a add new one - and the server immediately (synchronously) responds to the request.
The WITSML data objects are exchanged between client and server as XML documents.
The functions (methods) exposed by the STORE interface are prefixed with “WMLS_”.
The WMLS_ functions are exposed to client applications via SOAP (Remote Procedure Call-
style). A standardized Web Services Description Language (WSDL) file is used to define the
STORE interface exposed via SOAP.

CONCEPT

Although the WITSML client applications use the STORE interface to access the server as if
the various WITSML objects were stored as XML documents…there is no requirement for
the STORE implementation to internally persist the data as XML.
The client application hands-over to STORE one WITSML object in the form of an XML
document, and can later retrieve one or more objects in the form of an XML document.
The persistence mechanism used internally by the STORE implementation is not specified,
and the client application must not assume any particular storage mechanism, such as flat files
or a relational database. The only data format exchanged between the STORE implementation
and the client application are XML text documents.

Page 31 of 147
WITSML Application Programming Interface

To retrieve a WITSML data object stored on a server, the client application passes the type of
WITSML object and a Query Template as parameters to the WMLS_GetFromStore function:
RetVal = WMLS_GetFromStore(‘well‘, ç data object type
‘<wells…><well uid=“123”><name/></well></wells>‘,ç Query Template
OptionsIn,
CapabilitiesIn,
XMLout, ç returned objects
SuppMsgOut)
The server’s STORE implementation returns an XML document containing the WITSML object(s)
which satisfy the Query Template, and a return value (RetVal) indicating the success or failure of
the function.
► Query Templates are described in the next topic.
The client application can also add a single WITSML data object to a server by passing an XML
document containing the object to the WMLS_AddToStore function:
RetVal = WMLS_AddToStore("well", StringContainingXML)
And likewise, the client application can update or delete a single WITSML data object stored on
the server using the WMLS_UpdateInStore and WMLS_DeleteFromStore functions.

RESTRICTION

The WMLS functions exposed by the STORE interface all specify a single WITSML data object type
(well, rig, etc) in their data object type parameter. While some of the STORE interface functions allow
multiple occurrences of the same data object type to be manipulated in one invocation, none allow the
mixing of multiple data object types. And thus, the XML documents transported by the STORE
functions - both the data objects and the Query Templates described next - may contain multiple
occurrences of a single data object type, but not multiple data object types.

Page 32 of 147
WITSML Application Programming Interface

4.2 Query Templates

The following describes the standard behavior of the Query Template. There are some data
objects - log, mudLog and trajectory - that have special handling defined which extends this
standard behavior (see “Appendix D - Special Handling of Growing Objects”).

4.2.1 Introduction
The various STORE functions accept a Query Template as an input parameter.
In the example in the previous section, the second parameter is the Query Template. Here we
have restructured that example Query Template parameter so that the nesting of the XML
elements is more apparent: 3
<wells xmlns="http://www.witsml.org/schemas/140ex">
the Query <well uid=”123”>
<nameLegal/> the query
Template
</well>
</wells>
This Query Template contains only one query, which requests the legal name of the well object
that has an ID of “123”.
All Query Templates must contain a plural container element; in this case, “<wells>”.
Within the plural container element can be one or more singular elements of the same data
object type; in this case, “<well>”.
The Query Template could have included more than one query:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well uid=”123”>
<nameLegal/> 1st query
</well>
<well uid=”456”>
<nameLegal/> 2nd query
</well>
</wells>
Each <well> element in this Query Template is a separate query. Multiple queries can only be
specified when retrieving data.
The ability to submit multiple queries for the same data object type is provided merely for
efficiency – there is otherwise no relationship between the queries. Each is a separate,
standalone query that will result in zero or more well data objects being selected for each.
The data object(s) selected by multiple queries will be returned as separate data objects in one
plural container. The data object(s) resulting from query 1 (if any) will be first, followed by the data
object(s) resulting from query 2, and so on.
The returned data objects will not be explicitly identified with the query that requested them.
When using multiple queries, it is the responsibility of the client to determine which data object(s)
were returned as a result of which query, if such a correlation is necessary.

3
XML is not sensitive to “white space” characters such as line feeds, so reformatting it this way doesn’t affect its

meaning.

Page 33 of 147
WITSML Application Programming Interface

4.2.2 Data Item Selection

The data items – either attributes or elements - to be returned by a query are
specified by including the XML attribute(s) or element(s) in the Query Template
without an associated value.

For those more comfortable with SQL syntax, this is equivalent to the “column” selection
criteria of the SQL Select statement:
SELECT column1, column2, … , columnN

For XML attributes, this is done by specifying:

attribute=””
For XML elements, this is done by specifying:
<element></element> or simply <element/>
For example, the following query includes the nameLegal element without a value…
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well>
<nameLegal/>
</well>
</wells>
…and will return:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well>
<nameLegal>HLH 4 Walker Survey</nameLegal>
</well>
<well>
<nameLegal>Watson 6 Sewell Survey</nameLegal>
</well>
… and so on for all well objects on the server
</wells>
There is no syntax for returning all data items, other than specifying all the attributes/elements
individually. However, the query parameter returnElements achieves the same result and is
equivalent to the SQL SELECT * statement.

Page 34 of 147
WITSML Application Programming Interface

4.2.3 Object Selection

The data objects to be returned by a query are specified by including the attribute(s) or
element(s) in the query template with an associated value. The object selectors will be returned
by the query in addition to the data item selectors.

Or in SQL syntax, this is equivalent to a “where" clause of the SQL Select statement:
SELECT column1, column2, … , columnN WHERE column1 = value1, …

For XML attributes, this is done by specifying:

attribute=”value”
For XML elements, this is done by specifying:
<element>value</element>
For example, the following query includes a value of “Mexico” for the country element…
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well>
<country>Mexico</country>
</well>
</wells>
…and will return only the well objects with a value of “Mexico” in the country element:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well>
<country>Mexico</country>
</well>
<well>
<country>mexico</country>
</well>
<well>
<country>MEXICO</country>
</well>
</wells>
► See the topic on Case Sensitivity to see why the above results are possible.

Page 35 of 147
WITSML Application Programming Interface

4.2.4 Combining Data Item and Object Selection

Object Selection can also be combined with Data Item Selection to return more useful data
objects. For example, to retrieve all the Mexico wells, their legal names and their unique
identifiers, you can specify:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well uid=””>
<country>Mexico</country>
<nameLegal/>
</well>
</wells>
In this example <country> is an Object Selection criteria - because it has a value - and
<nameLegal>, and uid are Item Selection criteria, because they have no value.
Well data objects will be returned for all Mexico wells on the server and the nameLegal data item
and the well’s unique identifiers (UIDs) will also be returned.
You can also specify multiple Object Selection criteria in the same query. If instead of returning all
the Mexico wells and their legal names, you wished to return all the Mexico wells with the legal
name of BossWell, you can specify two Object Selection criteria:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well…>
<country>Mexico</country>
<nameLegal>BossWell</nameLegal>
…
</well>
</wells>
► When multiple Object Selection criteria are included in one query, they are AND’ed together.
The returned result set will contain only the objects where all the Object Selection criteria are
true.
► Remember that when multiple queries are included in one Query Template, they are treated as
completely separate queries. So, instead of combining the country and nameLegal Object
Selection criteria in one query as we did in the example on the previous page, we had instead
specified two separate queries:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well>
<country>Mexico</country>
…
</well>
<well>
<nameLegal>BossWell</nameLegal>
…
</well>
</wells>
…the results are likely to be quite different from the previous example! In this case, all the Mexico
wells will be returned and all the wells named BossWell, not just the Mexico wells named
BossWell.

LIMITATION

Query Templates are intended to provide a simple means of retrieving data objects based on
an equal comparison against a single value for each data item, either attribute or element.
They do not provide the ability to perform comparisons other than “equal”, or to allow for more
than one comparison against a given data item. While the default comparison is “equal”, a few
“date and time” elements will be documented to have “greater than” comparisons.

Page 36 of 147
WITSML Application Programming Interface

4.2.5 Selection using Recurring Data Items

When recurring data is included in a query they are OR’ed together.
For example, the following query will return all channels where (uidWell=w1 AND
uidWellbore=w1b AND (mnemonic=BPOS OR mnemonic=ROP)).
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<channel>
<mnemonic>BPOS<mnemonic>
</channel>
<channel>
<mnemonic>ROP</mnemonic>
</channel>
</realtime>
</realtimes>
When multiple selection criteria is included in the recurring element, then the criteria are AND’ed
together.
For example, the following query will return all channels where (uidWell=w1 AND
uidWellbore=w1b AND ((mnemonic=BPOS AND qualData=good) OR (mnemonic=ROP AND
qualData=fair))).
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<channel>
<mnemonic>BPOS<mnemonic>
<qualData>good<qualData>
</channel>
<channel>
<mnemonic>ROP</mnemonic>
<qualData>fair<qualData>
</channel>
</realtime>
</realtimes>
The same selection items must exist in each recurring element.
For example, the following template requests mnemonic in one channel item and md in another.
The results of this query are server dependent..
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<channel>
<mnemonic>BPOS<mnemonic>
</channel>
<channel>
<md uom=”ft”>1000</md>
</channel>
</realtime>
</realtimes>

Page 37 of 147
WITSML Application Programming Interface

The selection criteria containing multiple recurring items should be kept simple and unambiguous.
For example, the following template requests mnemonic BPOS both explicitly (using
<mnemonic>BPOS<mnemonic>) and implicitly (using <mnemonic/>). Some servers may return
BPOS two times and some servers may only return it once while other servers may return an
error.
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<channel>
<mnemonic>BPOS<mnemonic>
</channel>
<channel>
<mnemonic/>
</channel>
</realtime>
</realtimes>
The results of the following query with nested recurring selection is also server dependent.
<mudLogs xmlns="http://www.witsml.org/schemas/140ex">
<mudLog uidWell="w1" uidWellbore="w1b" uid=”ml3>
<geologyInterval>
<typeLithology>interpreted<typeLithology>
<lithology>
<type>Limestone<type>
</lithology>
</geologyInterval>
<geologyInterval>
<typeLithology>cuttings typeLithology>
<lithology>
<type>Salt< type>
</lithology>
</geologyInterval>
</mudLog>
</mudLogs>

Page 38 of 147
WITSML Application Programming Interface

4.2.6 Minimum Query Template

A Query Template must be a well-formed XML document which includes only attributes and
elements defined by WITSML for the particular data object type.
It must include a default namespace declaration for the WITSML namespace (see below), and
any other necessary namespace declarations.
It need not be a valid document, however, as it can omit attributes/elements that are specified as
mandatory in the WITSML XML Schemas and empty values are not valid for some elements.
The examples in this specification will utilize the following namespace from the example schema
defined in section “Appendix A - Example Data Object Schema”:
xmlns=”http://www.witsml.org/schemas/140ex”
Therefore, the minimum valid Query Template to return all the wells on a server is:
<wells xmlns="http://www.witsml.org/schemas/140ex">
<well/>
</wells>
For real queries against a server, the namespace of the actual data schema must be substituted
for the example data schema namespace.

CONCEPT REINFORCEMENT

The above example will return only…

<wells>
<well/>
<well/>
…
</wells>
…nothing else.
This would be sufficient if all you needed was a count of all the wells on the server, but if
you needed additional data items about each well, you must ask for them, by including the
various elements/attributes in the Query Template.

4.3 Authentication and Encryption

The STORE interface uses HTTP/S Basic Authentication, as described in IETF RFC’s 2616
(HTTP 1.1) and 2617 (Authentication).
The userid and password transported via the HTTP/S Basic Authentication mechanism can be
used by the STORE implementation to perform authorization checking and control of client
access.
The capabilities and implementation of authorization checking, if any, are not specified by
WITSML. It is up to participating companies to agree if authentication is required to access a
WITSML server. If it is required, the authentication data should be sent with each WITSML
message.
Secure Sockets Layer (SSL) for HTTP (HTTPS) can be used to encrypt the HTTP traffic.

Page 39 of 147
WITSML Application Programming Interface

4.4 Capabilities Objects

The STORE interface uses two special objects to exchange information about the “capabilities” of
the Client and the Server. These special objects are called the Capabilities objects.

RESTRICTION

While the Capabilities objects are a type of “WITSML API object” they cannot be accessed by the
STORE interface’s standard data query functions. The Capabilities objects are not persisted as
data. They can only be accessed using the WMLx_GetCap functions and the CapabilitiesIn/Out
parameters of the various STORE interface functions.

4.4.1 Client Capabilities (capClient) Object

The Client Capabilities or “capClient” object is used to inform the Server of the Client’s functional
capabilities. The capClient object is conveyed as the CapabilitiesIn parameter of various STORE
interface functions. It must be passed on each call; the value is not maintained across calls.
The CapabilitiesIn parameter may be set to a null string to indicate that no capClient object is
being provided. When a capClient object is not provided, default values for the various
capabilities are used by the Server.
4.4.2 Server Capabilities (capServer) Object
The Server Capabilities or “capServer” object is used to inform the Client of the Server’s
functional capabilities. The capServer object is conveyed as the CapabilitiesOut parameter of the
STORE interface’s WMLS_GetCap (Get Capabilities) function.

Page 40 of 147
WITSML Application Programming Interface

4.4.3 Capabilities by Object

These are the presently defined capabilities that can be exchanged using the capClient and/or
the capServer objects:
Capability: version of the API which the Client or Server supports
Applies to: capClient and capServer objects
Conveyed as: apiVers attribute of the capServer or capClient element
Syntax: apiVers=”n.n.n”
Default : 1.4.0
Example: <capServer apiVers=”1.4.0”>
</capServer>
Notes: this is the value to be used if it is necessary to dynamically adapt to
differing implementation levels (do not use the version element below)
Capability: contact information for the Client or Server
Applies to: capClient and capServer objects
Conveyed as: contact child element of the capServer or capClient element
Syntax: <contact>
<name>xxx…xxx</name>
<email>xxx…xxx</email>
<phone>nnn…nnn</phone>
</contact>
Default: none
Example: <contact>
<name>Bob Junior</name>
<email>[email protected]</email>
<phone>1-800-555-1212</phone>
</contact>
Notes: any descriptive text
Capability: description of the Client or Server
Applies to: capClient and capServer objects
Conveyed as: description child element of the capServer or capClient element
Syntax: <description>xxxx…xxxx</description>
Default: none
Example: <capServer>
<description>Equip Rm A - Rack 12</description>
</capServer>
Notes: any descriptive text
Capability: name of the Client or Server
Applies to: capClient and capServer objects
Conveyed as: name child element of the capServer or capClient element
Syntax : <name>xxxx…xxxx</name>
Default : none
Example: <capServer>
<name>Server #1</name>
</capServer>
Notes: any descriptive text

Page 41 of 147
WITSML Application Programming Interface

Capability: vendor (producer) of the software

Applies to: capClient and capServer objects
Conveyed as: vendor child element of the capServer or capClient element
Syntax: <vendor>xxxx…xxxx</vendor>
Default: none
Example: <capServer>
<vendor>Acme Downhole Software</vendor>
</capServer>
Notes:
Capability: version (build) of the executable program
Applies to: capClient and capServer objects
Conveyed as: version child element of the capServer or capClient element
Syntax: <version>n.n.n.n</version>
Default: none
Example: <capServer>
<version>1.4.0.1451</version>
</capServer>
Notes:
Capability: schema version(s) that are supported
Applies to: capClient and capServer objects
Conveyed as: schemaVersion child element of the capServer or capClient element
Syntax: <schemaVersion>n.n.n.n,m.m.m.m</schemaVersion>
Default: none
Example: <capClient>
<schemaVersion>1.1.0,1.2.0,1.4.0.0</schemaVersion>
</capClient>
<capServer>
<schemaVersion>1.4.0.0</schemaVersion>
</capServer>
Notes: The values must match the version attribute in the plural object.
For capClient, the value is a comma separated list of values without
spaces. The oldest version should be listed first.
For Servers, the value must match a value that is returned
by the WMLS_GetVersion function.

Page 42 of 147
WITSML Application Programming Interface

Capability: the STORE functions, versions and data objects that the Server
supports for each function
Applies to: capServer object only
Conveyed as: function child element of the capServer element
dataObject child element of the function element
Syntax: <function name=”xxx”>
<dataObject>xxx</dataObject>
</function>
Default: none (Client should not assume capability exists if not explicitly listed)
Example: <capServer apiVers=”1.4.0”>
<function name=”WMLS_GetFromStore”>
<dataObject>well</dataObject>
<dataObject>wellbore</dataObject>
<dataObject>log</dataObject>
</function>
<function name=”WMLS_AddToStore”>
<dataObject>log</dataObject>
</function>
<function name=”WMLS_GetVersion”>
</function>
</capServer>
Notes: the example shows supports for only the three specified data object types
for WMLS_GetFromStore and only the log object for WMLS_AddToStore. The
function calls are from version 1.4.0 of the API. It also supports the
WMLS_GetVersion function. The capServer object does not need to specify the
WMLS_GetCap function, as this is implied if the capServer object is returned to
the Client.

Page 43 of 147
WITSML Application Programming Interface

4.5 STORE Functions

This section describes the STORE interface functions.
The following functions are defined:
WMLS_AddToStore - add one new object to the server
WMLS_DeleteFromStore - delete one existing object (or subset) from the server
WMLS_GetBaseMsg - get the fixed "base" description of a return value
WMLS_GetCap - get the server’s Capabilities object
WMLS_GetFromStore – gets one or more objects from the server
WMLS_GetVersion - retrieves the data version(s) that are supported
WMLS_UpdateInStore - update one existing object on the server
These functions are documented on the following pages.
The realtime object has been designed as a temporary envelope for real-time data. As such, it
does not contain uid attributes. Instead, natural keys have been defined in the schemas for use
as the unique identifier(s) in the WMLS_AddToStore, WMLS_UpdateInStore,
WMLS_DeleteFromStore and WMLS_GetFromStore functions. When accessed via the STORE
functions, the realtime objects will only contain the current header definition and the most recent
data for each group.

Page 44 of 147
WITSML Application Programming Interface

4.5.1 WMLS_AddToStore
Adds one WITSML object to the server. The object is passed in a single XML document,
containing a root plural object element (e.g., <wells>) enclosing one singular object element (e.g.,
<well>). The object is added using the object type specified by WMLtypeIn plus the unique
identifier(s) present in the WITSML objects. An object with the same type and unique identifier(s)
must not already exist in the persistent store (use WMLS_UpdateInStore if updating an existing
object). If a uid value is not defined for the object in the XMLin file, the server will create one and
return the created uid value in SuppMsgOut (if there are no errors). All other parentage and lower
level (child) uid values must be defined in the XMLin file. See the notes for exceptions on the
realtime object.
integer = WMLS_AddToStore(
[in] string WMLtypeIn,
[in] string XMLin,
[in] string OptionsIn,
[in] string CapabilitiesIn,
[out] string SuppMsgOut
);
Parameters (all required):
WMLtypeIn - input string - not case sensitive
- one WITSML object type (see the specific WITSML data schema)
XMLin - input string - case sensitive (an XML document - see Notes)
- the WITSML object(s) to be added (see Notes)
- the XML should conform to the derived “write” schema where child and
parentage uids are mandatory.
OptionsIn - input string
- The keyword of ‘compressionMethod’ specifies a type of compression
that the client has applied to the contents of XMLin. Currently, the only
recognized values are "none" and “gzip”. A value of "none" specifies that
no compression has been applied to XMLin. The default is "none".
CapabilitiesIn - input string - case sensitive (an XML document)
- the client’s capabilities object (capClient) to be sent to the Server; may
be a null string if no capabilities object is to be provided to the Server
SuppMsgOut - output string
- Supplemental message text. If a uid is created for the object, the
created uid value will be returned in this string. The uid value will not be
returned if there are any errors.
Return Value:
short (see “Appendix C – Defined Values”)

Page 45 of 147
WITSML Application Programming Interface

Notes:
1) the object is added to the server using the passed type (WMLtypeIn) plus the unique
identifier(s) present in the object (XMLin); unique identifiers are not passed as separate
parameters. The following XMLin will add a new well object with the UID of “new1”:
wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=”new1”>
…
</well>
</wells>
2) the XML document must contain the plural container object as its root XML element,
even though it encloses only one WITSML object:
<wells …> [required even though there is only one <well> element]
<well uid=”new4”>
…
</well>
</wells>
3) upper/lowercase string data values present in the XMLin string will be stored exactly
as supplied: “preserving their case”. Subsequent WMLS_GetFromStore invocations will
return the string data values in their originally supplied case.
4) The realtime object is a special case that does not contain uid attributes (other than
well and wellbore parentage uids). When accessed via the Store Interface:
a) The unique identifier(s) of the realtime object will be natural keys (possibly
compound) for each node as documented in the schema.
b) For each wellbore, the store interface will only retain one realtime containing the
most recent definition of the header and containing the most recent data value of
each group (e.g., latest record or latest channel value for each mnemonic).
c) Because only the most recent data items will be retained, the unique identifiers
for the recurring data structures will not contain the data indices such that the
retained data will be unique based on the unique identifiers.
d) For WMLS_AddToStore an object uid can never be provided and a uid value will
never be returned.
e) WMLS_AddToStore will ”add” data sub-objects. But because only one data value
for each group column will be retained, the effect will be a “replace”.
For example, the following will add a specific channel value but the server will
also delete the existing value for the mnemonic in the specified group so the
result will be for this channel structure to replace the existing channel structure
with the same unique identity.
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<channel>
<id>Pits</id>
<mnemonic>RHO</mnemonic>
<dTim>2001-11-01T08:15:00.000Z</dTim>
<value>129.6</value>
</channel>
<commonData>
<serviceCategory>MWD Service</serviceCategory>
</commonData>
</realtime>
</realtimes>

Page 46 of 147
WITSML Application Programming Interface

4.5.2 WMLS_DeleteFromStore
Permanently deletes one WITSML object from the server. The object to be deleted is specified by
the WMLtypeIn and QueryIn parameters.
integer = WMLS_DeleteFromStore(
[in] string WMLtypeIn,
[in] string QueryIn,
[in] string OptionsIn,
[in] string CapabilitiesIn,
[out] string SuppMsgOut
);
Parameters (all required):
WMLtypeIn - input string - not case sensitive
- one WITSML object type (see the specific WITSML data schema)
QueryIn - input string - case sensitive (an XML document)
- a Query Template that specifies the unique identifiers of the objects to
be deleted
- Because QueryIn can contain empty elements, it cannot be schema
validated but otherwise the XML should conform to a derived “read”
schema where all elements and attributes are optional except for all
object and parentage uids which are mandatory.
OptionsIn - input string
- The keyword of ‘cascadedDelete’ specifies whether or not cascaded
deletes are to be enforced. A value of “true” specifies that the deletion of
an independent object will result in the deletion of all objects whose
identity depends on that object. For example, deleting a well object would
result in the deletion of all dependent wellbore objects as well as any
objects which depend on those wellbore objects. Deletion means that the
dependent object cannot be "found" via the WITSML API interface
regardless of whether some vestiges of it exist in a back-end database.
Referential integrity will be partly enforced by nullifying all uidRef values
that point to the deleted objects. A value of “false” specifies that an
independent object cannot be deleted until all dependent objects have
been deleted. The default value is “false”. Note that this option does not
apply to child..
CapabilitiesIn - input string - case sensitive (an XML document)
- the client’s capabilities object (capClient) to be sent to the Server; may
be a null string if no capabilities object is to be provided to the Server
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C - Defined Values”)

Page 47 of 147
WITSML Application Programming Interface

Notes:
1) The client application specifies the object to be deleted using a Query Template,
passed via the QueryIn parameter. The uid for the object and its parents must be
specified. For example, the following will delete a specific wellbore object as identified by
the uidWell and uid attributes
<wellbores xmlns=“http://www.witsml.org/schemas/140ex”>
<wellbore uidWell=”12345” uid=”01” />
</wellbores>
2) If cascading deletes are not invoked, only bottom level objects should be deleted and
all child objects should be deleted before the parent is deleted. For example, a child
wellbore should be deleted before the parent well is deleted.

3) To eliminate the likelihood of accidental deletion of multiple objects,

WMLS_DeleteFromStore requires that the object present in the Query Template must
contain the unique identifier(s) (UIDs) of one object to be deleted. See note on unique
identifier of realtime object.
You cannot, for example, request WMLS_DeleteFromStore – in one step - to delete all
the wells where <country> is Mexico 4
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well> [this will fail because there is no uid specified]
<country>Mexico</country>
</well>
</wells>
4) If the client application needs to delete multiple objects based on selection criteria
other than the UID, it can first use WMLS_GetFromStore to retrieve the UIDs of the
objects based on the necessary criteria, and then repetitively pass each returned object
containing the UIDs to WMLS_DeleteFromStore.

For example, to delete all the planned well objects from a server:
a) use WMLS_GetFromStore to query for the UID of all the planned well objects. The
QueryIn parameter of WMLS_GetFromStore would contain:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=““>
<itemState>Planned</itemState>
</well>
</wells>
b) pass the returned well object(s) in multiple calls to WMLS_DeleteFromStore. The
QueryIn parameter of the first WMLS_DeleteFromStore might contain:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=“123”/>
</wells>
While the next one might contain:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=“456”/>
</wells>

4
but this can be accomplished in two steps – see the next note.

Page 48 of 147
WITSML Application Programming Interface

5) A sub-node within an object can be deleted by specifying an empty sub-node. An

empty container element contains no elements or attributes (except for a unique
identifier). An empty non-container element contains no value or attributes (except for a
unique identifier).

a) An empty attribute will delete the attribute. The following are exceptions to this
rule:
1. An empty uid attribute cannot be specified.
2. An empty uidRef attribute can only be specified if the related item has been
deleted.
3. An empty uom attribute cannot be specified.
b) An empty non-container element will delete its value and any attributes. For
example, the following will delete the country element in the specified well object.
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=”12345”>
<country />
</well>
</wells>
c) An empty recurring container with a unique identifier value will delete that specific
occurrence. For example, the following will delete a single trajectoryStation in the
specified object.
<trajectorys xmlns=“http://www.witsml.org/schemas/140ex”>
<trajectory uidWell="W-12" uidWellbore="B-01"
uid="pe84e">
<trajectoryStation uid=”123” />
</trajectory>
</trajectorys>
d) An empty recurring element (container or non-container) with no unique identifier
value will delete all occurrences. For example, the following will delete all
trajectoryStations in the specified object.

<trajectorys xmlns=“http://www.witsml.org/schemas/140ex”>
<trajectory uidWell="W-12" uidWellbore="B-01"
uid="pe84e">
<trajectoryStation/>
</trajectory>
</trajectorys>
e) An empty node cannot be specified for a mandatory element or attribute.
f) Deletion of sub-nodes, as opposed to the whole object, should only require user
update rights as opposed to user deletion rights.

Page 49 of 147
WITSML Application Programming Interface

6) Items can be deleted from realtime based on specified unique identifiers in the QueryIn
template. (See note in WMLS_AddToStore on the special nature of realtime when
accessed via STORE functions.)
a) Specifying only the realtime identifiers will delete the whole realtime for that wellbore.
For example, the following will delete the realtime object for a specific wellbore.
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
</realtimes>
b) Specifying an empty header element will delete the whole header (and thus all data).
This is required in order to delete individual non-recurring child elements. For
example:
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<realtimeHeader/>
</realtime>
</realtimes>
c) Specifying a header group without any column identifiers will delete all data for the
whole group. That is both the group description and the data will be deleted. For
example, the following will delete a specific realtime group in the specified wellbore
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<realtimeHeader>
<groupDefinition>
<id>Pits</id>
</groupDefinition>
</realtimeHeader>
</realtime>
</realtimes>
d) Similar to a systematically growing object , if a group column identifier is specified
then all information associated with that column will be deleted. For example, the
following will delete the RHO column from the Pits group (including any channel or
record data).
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<realtimeHeader>
<groupDefinition>
<id>Pits</id>
<channelDefinition>
<mnemonic>Z</mnemonic>
</channelDefinition>
</groupDefinition>
</realtimeHeader>
</realtime>
</realtimes>

Page 50 of 147
WITSML Application Programming Interface

e) Specifying a specific data item (channel or record) will delete just that data item. For
example, the following will delete a specific channel value.
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<channel>
<id>Pits</id>
<mnemonic>RHO</mnemonic>
</channel>
</realtime>
</realtimes>
7) See section “STORE and PUBLISH behavior” for additional behavior related to
growing objects.
4.5.3 WMLS_GetBaseMsg
Returns a string containing the fixed ("base") message text associated with a return value.
string = WMLS_GetBaseMsg(
[in] integer ReturnValueIn
);
Parameters (all required):
ReturnValueIn - input integer
- a valid Return Value (see “Appendix C - Defined Values”)
Return Value:
string the fixed descriptive message text associated with the Return Value
(a null string is returned if ReturnValueIn is invalid)
Notes:
1) This function returns only the fixed description of the specified Return Value.
2) Variable, context-specific "supplemental" message text and diagnostic information, if
any, is returned in the SuppMsgOut parameter of the various STORE functions.

Page 51 of 147
WITSML Application Programming Interface

4.5.4 WMLS_GetCap
Returns the capServer object that describes the capabilities of the Server for one data schema.
The capServer object is returned in the form of an XML document. Multiple calls to
WMLS_GetCap are required in order to determine the capabilities of the server for all data
schemas that it supports.

integer = WMLS_GetCap(
[in] string OptionsIn,
[out] string CapabilitiesOut,
out] string SuppMsgOut
);
Parameters (all required):
OptionsIn - input string
- The keyword "dataVersion" with a value of a data schema version
specifies that capabilities information is desired for that particular data
version. The returned capabilities object will utilize the namespace that is
appropriate for the data version. For example:
dataVersion=1.4.0.0
requests information about data version 1.4.0.0 utilizing a 1.4.0
capabilities object. The data schemas that are supported by the server
can be determined using WMLS_GetVerson. The version string must
match the value of attribute "version" on the plural object container. The
default is for the server to return information about the oldest data
version that is supported by the server.
CapabilitiesOut - output string - case sensitive (an XML document)
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C - Defined Values”)
Notes:
The OptionsIn parameter string is encoded utilizing the encoding rules for HTML form
content type application/x-www-form-urlencoded as specified at
http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.3.3
Note that this does not affect a single keyword and value pair.

Page 52 of 147
WITSML Application Programming Interface

4.5.5 WMLS_GetFromStore
Returns one or more WITSML objects from the Server. The objects are returned in the form of an
XML document containing a root plural object element (e.g., <wells>) enclosing one or more
singular object elements (e.g., <well>). The objects to be retrieved are identified by the object
type and Query Template passed to the function.

integer = WMLS_GetFromStore(
[in] string WMLtypeIn,
[in] string QueryIn,
[in] string OptionsIn,
[in] string CapabilitiesIn,
[out] string XMLout,
[out] string SuppMsgOut
);
Parameters (all required):
WMLtypeIn - input string - not case sensitive
- one WITSML object type
(see the specific WITSML data schema)
QueryIn - input string - case sensitive (an XML document)
- a Query Template that specifies the objects to be returned
- Because QueryIn can contain empty elements, it cannot be schema
validated but otherwise the XML should conform to a derived “read”
schema where all elements and attributes are optional.
OptionsIn - input string
- The keyword of ‘returnElements’ with a value of "all" requests that all
elements and attributes be returned. The template should be treated as if
all elements and attributes had explicitly been specified in the template. A
value of "requested" requests the mode of "you only get what you ask
for". For example:
returnElements=all
The default is "requested".
- The keyword of ‘compressionMethod’ specifies a type of compression
used for the parameters defined by compressionDirection. Currently, the
only recognized values are "none" and “gzip”. A value of "none" specifies
that no compression will be applied. The default is "none".
- The keyword of “compressionDirection” specifies which parameters will
be compressed with the specified method (possibly "none"). The
recognized values are "request", "response" or "both". A value of
"request" means that the client has applied the method to the contents of
QueryIn. A value of "response" means that the server must apply the
method to the contents of XMLout. A value of "both" means that both
QueryIn and XMLout will have the method applied. The default for
WMLS_GetFromStore is “response”.

Page 53 of 147
WITSML Application Programming Interface

CapabilitiesIn - input string - case sensitive (an XML document)

- the client’s capabilities object (capClient) to be sent to the
Server; may be a null string if no capabilities object is to
be provided to the Server
XMLout - output string - case sensitive
- the returned WITSML object(s) is an XML document
- the XML should conform to a derived “read” schema where all elements
and attributes are optional.
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C - Defined Values”)
Notes:
1) output parameters are valid only if Return Value = 1
2) no locking of the object is performed on the server
3) the returned document will contain a plural container object as its root XML element,
enclosing zero or more singular object elements:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well…>
…
</well>
<well…>
…
</well>
</wells>
4) if the Query Template does not result in any objects being returned, the returned
document will contain only the plural container element:
<wells/>
5) when multiple queries are present in the Query Template, the sets of objects returned
by the queries are returned in the order in which the queries were specified.
If the Query Template specified:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well…>
<country>UK</country>
</well>
<well…>
<country>Norway</country>
</well>
</wells>
The set of well objects in the UK (if any) would be returned before the set of well objects
in Norway (if any).
► The individual well objects within each set would be unordered, however.
6) The inclusion of a uom value in a query is to be regarded as a request for unit
conversion, not a query filter. See section “Process interaction with ‘uom’”.

Page 54 of 147
WITSML Application Programming Interface

7) If no value is available for an element or attribute then nothing will be returned. That is,
empty values will not be returned,
8) The elements will be returned in the order defined by the schema.
9) The order of the recurring data within an object is server dependent. The order that a
client added components will not necessarily be retained unless the schema documents
some significance of the order.
10) If multiple queries are contained in the template and one query fails then all of the
queries will fail.
11) The Extended Query Syntax that was in version 1.0 was eliminated from the standard
in version 1.2.
12) For various reasons, some servers may impose restrictions on retrievals. For
example, because the log data section can be so voluminous, a server may impose
constraints when retrieving curve data (as opposed to only retrieving header data):
a) A server may require that a specific log be identified
b) A server may not allow a request for all logs from one well.
c) A server may not allow a request for all logs from all wells.
d) In order to avoid clients killing a server the WITSML server might limit your result
set when you ask for log curves. The client should always compare the end index
in the log header with the end index in the result of its query. If there is a gap the
server has limited the result to a certain number of log points and the client will
need to ask again for the missing interval or at least for another interval
preceding the last result. A client should continue to do so until all the points in
the log curve have been retrieved.
13) The normal behavior for a server is to return only “what you ask for”. That is, in order
for an element to be returned it has to exist in the query template. This includes uom
attributes (see “Appendix B - Unit of Measure”).
a) For the special case of <customData> (see “Appendix G - Custom Data”), all
sub-nodes will be returned if only the customData element is specified. Querying
sub-nodes of customData is server dependent.
b) For the special category called growing objects, special behavior has been
defined. See “Appendix E – Special Handling of Growing Objects” for a
discussion of growing objects and their special behavior.
14) For realtime, if the client pulls more frequently than the server has fresh data then the
same realtime will be repetitively returned until new data is available. It is the clients
responsibility to inspect for duplicates based on the indices (e.g., dTim and md).
However, if the query specifies a value for dTimLastChange then it must be interpreted as
a request for only that data (channel or record) which has changed since (i.e., greater-
than) the specified value for dTimLastChange. This solution works for both depth and
time based data; however, best practice for all realtime data should have dTim defined by
the source system.
15) The OptionsIn parameter string is encoded utilizing the encoding rules for HTML form
content type application/x-www-form-urlencoded as specified at
http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.3.3
Note that this does not affect a single keyword and value pair.

Page 55 of 147
WITSML Application Programming Interface

16) The QueryIn template will not be schema compliant if it contains empty values. If it
does not contain empty values, it should be schema compliant against a derived “read”
schema where all elements and attributes are optional. The OptionsIn keyword
returnElements with a value of “all” can be used to construct a query without empty
values.
17) All of the criteria must be satisfied in a individual (singular) query or nothing (i.e., no
object) will be returned.
18) See note in WMLS_AddToStore on the special nature of realtime when accessed via
STORE functions.

4.5.6 WMLS_GetVersion
Returns a string containing the version(s) of data schemas that are supported by the server. A
particular data version can be passed to WMLS_GetCap via its OptionsIn parameter to request
information about the server capabilities with respect to that data version.
string = WMLS_GetVersion();
Parameters:
none
Return Value:
string - A comma separated list of schema versions (without spaces) that
are supported by the server. The oldest version should be listed
first, followed by the next oldest, etc.
Example: 1.2.0,1.4.0.0
Notes:
Each version number must match the contents of the version attribute on the plural
container element for each object.
For more information, see the topic on Versioning in the Terminology and Basic Concepts
section of this document.

Page 56 of 147
WITSML Application Programming Interface

4.5.7 WMLS_UpdateInStore
Updates one existing WITSML object on the Server. The WITSML object with the updated/added
values is passed in a single XML document, containing a root plural object element (e.g., <wells>)
enclosing one singular object element (e.g., <well>). The object to be updated is identified using
the object type specified by WMLtypeIn plus the unique identifier(s) present in the object. An
object with the same type and unique identifier(s) must already exist in the persistent store (use
WMLS_AddToStore if adding a new object).
integer = WMLS_UpdateInStore(
[in] string WMLtypeIn,
[in] string XMLin,
[in] string OptionsIn,
[in] string CapabilitiesIn,
[out] string SuppMsgOut);
Parameters (all required):
WMLtypeIn - input string - not case sensitive
- one WITSML object type (see the specific WITSML data schema)
XMLin - input string - case sensitive (an XML document)
- the updated WITSML object(s)
- the XML should conform to a derived “update” schema where all
elements and attributes are optional except for all uid attributes which are
mandatory.
OptionsIn - input string
- The keyword of ‘compressionMethod’ specifies a type of compression
that the client has applied to the contents of XMLin. Currently, the only
recognized values are "none" and “gzip”. A value of "none" specifies that
no compression has been applied to XMLin. The default is "none".
CapabilitiesIn - input string - case sensitive (an XML document)
- the client’s capabilities object (capClient) to be sent to the Server; may
be a null string if no capabilities object is to be provided to the Server
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C - Defined Values”)

Page 57 of 147
WITSML Application Programming Interface

Notes:
For the purpose of the following discussion, a container is an element which contains
other elements. A non-container is an element which has a value instead of other
elements.
1) the document must contain the required plural container item as its root XML element
2) The XMLin document must uniquely identify one object to be updated by including the
unique identifier of the object.
3) An element (container or not) in an existing container occurrence (recurring or not) can
be altered without changing anything else in the container.
4) An attribute can be altered without changing anything else in the element.
5) Specifying a value for an existing non-container element will replace the value for that
element. There is no check to see if the value is actually different. For example, the
following will update the itemState of well “123”.
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=“123“>
<itemState>Planned</itemState>
</well>
</wells>
6) Specifying a value for an existing attribute will replace the value for that attribute.
There is no check to see if the value is actually different.
7) Any new element or attribute will be inserted. A recurring container with a new unique
identifier value is a new element. New elements or attributes cannot be empty. For
example, the following will insert a new trajectoryStation, assuming that it did not already
exist: If it already existed, it would change the value of name, etc
<trajectorys xmlns=“http://www.witsml.org/schemas/140ex”>
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<trajectoryStation uid=”456”>
<name>new station</name>
</trajectoryStation>
</trajectory>
</trajectorys>
8) The result of the update must be schema compliant with the “write” schema. For
example, mandatory items cannot be totally eliminated because they are constrained by
minOccurs.
9) A uom attribute cannot be specified unless its corresponding value is specified. This
prevents any assumption that a client can influence the default unit of measure. For
example in the following, the md in the first station is not allowed but the md in the
second station is OK.
<trajectorys xmlns=“http://www.witsml.org/schemas/140ex”>
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<trajectoryStation uid=”123”>
<md uom=”ft” />
</trajectoryStation> Invalid because the md value not specified.
<trajectoryStation uid=”123”>
<md uom=”ft”>667.4</md> OK because the md value is specified.
</trajectoryStation>
</trajectory>
</trajectorys>

Page 58 of 147
WITSML Application Programming Interface

10) See note in WMLS_AddToStore on the special nature of realtime when accessed via
STORE functions. When WMLS_UpdateInStore is used to update realtime, the natural
identifiers will be used in the documented behavior related to “unique identifiers”. For
example:
The following will modify the value of qualData in the definition of the specified channel
(assuming that groupDefinition/id and channelDefinition/mnemonic are unique identifiers).
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<realtimeHeader>
<groupDefinition>
<id>Pits</id>
<channelDefinition>
<mnemonic>RHO</mnemonic>
<qualData>good</qualData>
</channelDefinition>
</groupDefinition>
</realtimeHeader>
</realtime>
</realtimes>
Assuming that channel/id and channel/mnemonic are unique identifiers, the following will
either (a) add a specific channel structure if the channel does not yet exist or (b) update
the existing values of dTim and value if the channel for id and mnemonic already exists.
<realtimes xmlns=“http://www.witsml.org/schemas/140ex”>
<realtime uidWell="W-12" uidWellbore="B-01" />
<channel>
<id>Pits</id>
<mnemonic>RHO</mnemonic>
<dTim>2001-11-01T08:15:00.000Z</dTim>
<value>129.6</value>
</channel>
</realtime>
</realtimes>

Page 59 of 147
WITSML Application Programming Interface

11) You cannot include Object Selection criteria in the XML document passed in XMLin.
For example, you cannot change all the legal names of all the wells in Scotland by merely
specifying:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well>
<nameLegal>changed Legal Name</nameLegal>
<country>Scotland</country>
</well>
</wells>
WMLS_UpdateInStore would not be able to determine which values were selection
criteria and which were merely new values to be updated (and the update would fail
nevertheless, because there is no UID specified for well…see Note #2).
You can accomplish the same task in three steps, however:
a) use WMLS_GetFromStore to select the UIDs of all the wells in Scotland. The
QueryIn parameter passed to WMLS_GetFromStore would be:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=””>
<nameLegal/>
<country>Scotland</country>
</well>
</wells>
This might return:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=”123”>
<nameLegal>existing legal name of 123</nameLegal>
<country>Scotland</country>
</well>
<well uid=”456”>
<nameLegal>existing legal name of 456</nameLegal>
<country>Scotland</country>
</well>
</wells>
b) programmatically update the legal names in the returned document to their new
values and split into multiple documents:
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=”123”>
<nameLegal>changed legal name of 123</nameLegal>
</well>
</wells>
and
<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=”456”>
<nameLegal>changed legal name of 456</nameLegal>
</well>
</wells>
c) pass the updated documents to WMLS_UpdateInStore in multiple calls. Each <well>
element will then update its persisted object with the new legal name

Page 60 of 147
WITSML Application Programming Interface

4.6 STORE Interface - WSDL File

The Web Service Description Language (WSDL) file used to expose the STORE interface to
SOAP clients is listed below. A narrative describing several key points follows the file listing.

IMPORTANT

In order to ensure interoperability between implementations, the only part of the WSDL file that
should normally be modified is the location attribute of the SOAP address element.
Other than the location attribute, the WSDL file should be used exactly as shown in the
following file listing.
The WSDL file is also provided in the WITSML distribution media.

Page 61 of 147
WITSML Application Programming Interface

4.6.1 File Listing

<?xml version='1.0' encoding='UTF-8' ?>
<definitions name='WMLS' targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
<documentation>WITSML Version 1.2.0 STORE interface WSDL file
</documentation>
<!-- Abstract Definitions Section - <types>, <message> and <portType> elements -->
<!-- <types> element declares user-defined machine and language independent data types,
and is not needed for the WITSML STORE interface, which uses only W3C-defined data
types -->
<!-- <message> elements define request/response messages and their parameters-->
<message name='Store.WMLS_AddToStore'>
<part name='WMLtypeIn' type='xsd:string'/>
<part name='XMLin' type='xsd:string'/>
<part name='OptionsIn' type='xsd:string'/>
<part name='CapabilitiesIn' type='xsd:string'/>
</message>
<message name='Store.WMLS_AddToStoreResponse'>
<part name='Result' type='xsd:short'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>

<message name='Store.WMLS_DeleteFromStore'>
<part name='WMLtypeIn' type='xsd:string'/>
<part name='QueryIn' type='xsd:string'/>
<part name='OptionsIn' type='xsd:string'/>
<part name='CapabilitiesIn' type='xsd:string'/>
</message>
<message name='Store.WMLS_DeleteFromStoreResponse'>
<part name='Result' type='xsd:short'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>

<message name='Store.WMLS_GetBaseMsg'>
<part name='ReturnValueIn' type='xsd:short'/>
</message>
<message name='Store.WMLS_GetBaseMsgResponse'>
<part name='Result' type='xsd:string'/>
</message>

Page 62 of 147
WITSML Application Programming Interface

<message name='Store.WMLS_GetCap'>
<part name='OptionsIn' type='xsd:string'/>
</message>
<message name='Store.WMLS_GetCapResponse'>
<part name='Result' type='xsd:short'/>
<part name='CapabilitiesOut' type='xsd:string'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>

<message name='Store.WMLS_GetFromStore'>
<part name='WMLtypeIn' type='xsd:string'/>
<part name='QueryIn' type='xsd:string'/>
<part name='OptionsIn' type='xsd:string'/>
<part name='CapabilitiesIn' type='xsd:string'/>
</message>
<message name='Store.WMLS_GetFromStoreResponse'>
<part name='Result' type='xsd:short'/>
<part name='XMLout' type='xsd:string'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>

<message name='Store.WMLS_GetVersion'>
</message>
<message name='Store.WMLS_GetVersionResponse'>
<part name='Result' type='xsd:string'/>
</message>

<message name='Store.WMLS_UpdateInStore'>
<part name='WMLtypeIn' type='xsd:string'/>
<part name='XMLin' type='xsd:string'/>
<part name='OptionsIn' type='xsd:string'/>
<part name='CapabilitiesIn' type='xsd:string'/>
</message>
<message name='Store.WMLS_UpdateInStoreResponse'>
<part name='Result' type='xsd:short'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>
<!-- <portType> element groups the functions (operations) into an interface -->
<portType name='StoreSoapPort'>
<!-- <operation> elements define the function signatures (operation name and parameters)
and associate the input and output messages -->
<!-- parameterOrder attribute values must be separated by a single space -->
<operation name='WMLS_AddToStore'
parameterOrder='WMLtypeIn XMLin OptionsIn CapabilitiesIn SuppMsgOut'>
<input message='wsdlns:Store.WMLS_AddToStore' />
<output message='wsdlns:Store.WMLS_AddToStoreResponse' />
</operation>
<operation name='WMLS_DeleteFromStore'

Page 63 of 147
WITSML Application Programming Interface

parameterOrder='WMLtypeIn QueryIn OptionsIn CapabilitiesIn SuppMsgOut'>

<input message='wsdlns:Store.WMLS_DeleteFromStore' />
<output message='wsdlns:Store.WMLS_DeleteFromStoreResponse' />
</operation>
<operation name='WMLS_GetBaseMsg' parameterOrder='ReturnValueIn'>
<input message='wsdlns:Store.WMLS_GetBaseMsg' />
<output message='wsdlns:Store.WMLS_GetBaseMsgResponse' />
</operation>
<operation name='WMLS_GetCap'
parameterOrder='OptionsIn CapabilitiesOut SuppMsgOut'>
<input message='wsdlns:Store.WMLS_GetCap' />
<output message='wsdlns:Store.WMLS_GetCapResponse' />
</operation>
<operation name='WMLS_GetFromStore'
parameterOrder='WMLtypeIn QueryIn OptionsIn CapabilitiesIn XMLout SuppMsgOut'>
<input message='wsdlns:Store.WMLS_GetFromStore' />
<output message='wsdlns:Store.WMLS_GetFromStoreResponse' />
</operation>
<operation name='WMLS_GetVersion'>
<input message='wsdlns:Store.WMLS_GetVersion' />
<output message='wsdlns:Store.WMLS_GetVersionResponse' />
</operation>
<operation name='WMLS_UpdateInStore'
parameterOrder='WMLtypeIn XMLin OptionsIn CapabilitiesIn SuppMsgOut'>
<input message='wsdlns:Store.WMLS_UpdateInStore' />
<output message='wsdlns:Store.WMLS_UpdateInStoreResponse' />
</operation>
</portType>
<!-- Concrete Definitions Section - <binding> and <service> elements -->
<!-- <binding> specifies the protocol binding for each operation in the <portType> section
-->
<binding name='StoreSoapBinding' type='wsdlns:StoreSoapPort'>
<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http' />
<operation name='WMLS_AddToStore'>
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_AddToStore' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLS_DeleteFromStore'>
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_DeleteFromStore' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'

Page 64 of 147
WITSML Application Programming Interface

encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLS_GetBaseMsg'>
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_GetBaseMsg' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLS_GetCap'>
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_GetCap' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLS_GetFromStore' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_GetFromStore' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLS_GetVersion' >
<soap:operation soapAction='http://www.witsml.org/action/120/Store.WMLS_GetVersion' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>

Page 65 of 147
WITSML Application Programming Interface

</operation>

<operation name='WMLS_UpdateInStore' >

<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_UpdateInStore' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
</binding>
<!-- <service> specifies the portType for each binding and the URL of the service -->
<service name='WMLS' >
<port name='StoreSoapPort' binding='wsdlns:StoreSoapBinding' >
<soap:address location='http://yourorg.com/yourwebservice' />
</port>
</service>
</definitions>

Page 66 of 147
WITSML Application Programming Interface

4.6.2 Narrative
 The only part of the WSDL file that should normally be modified is the location attribute of the
SOAP address element. This should be set to the URL of the Web Service (see
implementation specifics below):
<service name='WMLS' >
<port name='StoreSoapPort' binding='wsdlns:StoreSoapBinding' >
<soap:address location='http://yourorg.com/yourwebservice' />
</port>
</service>
 The WSDL file complies with Version 1.1 of the Web Services Description Language
(www.w3.org/TR/wsdl)
 The target namespace and wsdlns prefix used in the WSDL file are both declared as:
'http://www.witsml.org/wsdl/120'
<definitions name='WMLS'
targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
 A default namespace declaration is used to make the document more readable:
<definitions name='WMLS' targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
 The soapAction attribute of the SOAP operation elements specify a WITSML-related URI:
http://www.witsml.org/action/120/Store.WMLS_xxxx
The soapAction attribute is used by the HTTP transport as the value of the SOAPAction
HTTP header. Its use is not clear as of this writing; SOAP 1.1 states that it can be used to
identify the “intent” of messages.
<operation name='WMLS_AddToStore' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_AddToStore' />
<input>
…
 The namespace attribute of the SOAP body elements also specify a WITSML-related URI:
http://www.witsml.org/message/120
<operation name='WMLS_AddToStore' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Store.WMLS_AddToStore' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
</operation>
…

Page 67 of 147
WITSML Application Programming Interface

 Although XML generally ignores white-space, the values of certain XML attributes and
elements may be sensitive to the amount of white-space. For example, the parameterOrder
attribute of the <operation> element must have only a single space between parameters:
<operation name='WMLS_AddToStore'
parameterOrder='WMLtypeIn XMLin OptionsIn CapabilitiesIn SuppMsgOut'>
For an easy-to-read, understandable introduction to WSDL files, see the article titled “Web
Services Description Language (WSDL) Explained” by Carlos C. Tapang - Infotects (in the
Microsoft MSDN Library and elsewhere).

Page 68 of 147
WITSML Application Programming Interface

5. PUBLISH Interface
5.1 Introduction
The PUBLISH interface provides Subscriber applications the ability to:
 query a Publisher for what data object types are available for publication
 subscribe to changed WITSML data objects to be published at some time in the future
 maintain its subscription requests held by a Publisher.
When using the PUBLISH interface, the actual transfer of the requested WITSML data objects
between Publisher and Subscriber is performed by the Publisher when changed data objects
matching the Subscription become available (see CONCEPT box on next page). Although the
Subscriber initiates the process by sending a Subscription request to the Publisher that specifies
the objects it wishes to have sent to it, it’s still a “push” model in the sense that the requested
data objects are eventually pushed from Publisher to Subscriber.
Both the WITSML Subscription request and published data objects are XML documents.
The functions exposed by the PUBLISH interface are prefixed with “WMLP_”.
The WMLP_ functions are exposed to client applications as SOAP methods (Remote Procedure
Call-style). A standardized Web Services Description Language (WSDL) file is used to define the
PUBLISH interface exposed via SOAP.
The PUBLISH interface defines only the SOAP-exposed functions needed by a Subscriber to
determine what is available for subscription, and for the Subscriber to manipulate its
subscriptions. It does not expose an interface for invoking the publication (push) operation.
Publication is performed internally by the PUBLISH implementation when data is available for
publication, based on the subscriptions the Publisher has accepted.
The PUBLISH implementation uses HTTP/S POST to publish (push) the requested data objects
to the Subscriber. SOAP is used only for the Subscriber to access the Publisher during the
subscription process, not for the publication of the data objects

CONCEPT

A subscription to a data object is a request to receive the data object - or portions thereof -
when a future “change” is made to the data object.
Adding, modifying or deleting an object constitutes a “change” to the object.
A Publisher does not send the matching data object(s) immediately upon receipt of a
subscription.
A Publisher will send the data object to the Subscriber only when/if the data object changes
after the receipt of the subscription.
If the Subscriber application needs a full set of objects as a starting-point, it should use the
STORE interface to retrieve the initial contents of the objects.

Page 69 of 147
WITSML Application Programming Interface

Here is an example of a subscriber requesting two subscriptions. The subscriber application uses
SOAP to invoke the WMLP_Subscribe function on the Publisher . It passes the two Subscription
Requests in the SubscriptionIn parameter:
RetVal = WMLP_Subscribe(SubscriptionIn,
OptionsIn,
SubscriptionOut,
SuppMsgOut)
The SubscriptionIn parameter might contain:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add ”… >
<realtimes namespace="http://www.witsml.org/schemas/140ex">
<realtime … />
</realtimes>
<mudLogs namespace="http://www.witsml.org/schemas/140ex">
<mudLog … />
</mudLogs>
</subscription>
<subscription action=”add” … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well … />
</wells>
<wellbores namespace="http://www.witsml.org/schemas/140ex">
<wellbore … />
</wellbores>
<trajectorys namespace="http://www.witsml.org/schemas/140ex">
<trajectory … />
</trajectorys>
</subscription>
</subscriptions>
The Publisher inserts a return code (retCode attribute) into each Subscription Request (the
<subscription> element) and - if the subscription was accepted - the subscription identifier (idSub
attribute). It then returns the modified Subscription Requests to the Subscriber in the
SubscriptionOut parameter.
The Publisher also returns a value (RetVal) indicating the overall success or failure of the
function.
►Subscription Requests and their child elements - known as Subscription Templates - are
described in subsequent topics.

Page 70 of 147
WITSML Application Programming Interface

If RetVal = “1” (meaning OK) then SubscriptionOut might contain:

<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription retCode=”1” idSub=”12345” … > ß subscription accepted
…
</subscription>
<subscription retCode=”-101” … > ß error, so no idSub was returned
…
</subscription>
</subscriptions>
The first subscription was accepted (retCode=”1”) and was assigned a subscription ID of 12345.
The Subscriber can later use that ID to verify, modify or cancel the subscription or retransmit
realtime headers, by again invoking the WMLP_Subscribe function but passing a subscription
object with action=”verify”, “modify”, “cancel” or “retransmit” and the subscription ID.
The second subscription was rejected (retCode is a negative value). No subscription ID was
returned.

Page 71 of 147
WITSML Application Programming Interface

5.2 Subscription Requests

A Subscription Request is used both to request a new subscription and to modify an existing
subscription. A Subscription Request carries with it various information that identifies the
Subscriber.
Here is an example of one Subscription Request:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … /> ç the Subscription Request
</subscriptions>
The plural <subscriptions> element is required even when there is only one Subscription
Request. There can be one or more Subscription Requests contained within the plural
<subscriptions> element:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription …/>
<subscription …/>
</subscriptions>
Each Subscription Request must specify one or more WITSML data object types 5 to be
published. Here is an example of a Subscription Request for the well and wellbore data objects,
and a second Subscription Request for just the mudLog data object:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … > ç Subscription Request #1
<wells … /> ß Subscription Template #1a
<wellbores … /> ß Subscription Template #1b
</subscription>
<subscription … > ç Subscription Request #2
< mudLogs … /> ß Subscription Template #2
</subscription>
</subscriptions>
► The plural wells, wellbores and mudLogs child elements are known as Subscription
Templates, and will be described later. Subscription Templates specify which data objects and
which data items within each data object are to be published, much like the Query Templates
used by the STORE interface. We will discuss them in detail later on, but for now, let us continue
describing the Subscription Request (<subscription>) element.

5
the Subscription object cannot specify the Subscription or Capabilities object types, however.
Those object types cannot be published.

Page 72 of 147
WITSML Application Programming Interface

CONCEPT

Subscription Requests are treated as separate, independent requests, even if received from and
targeted to the same Subscriber.
Consider the following two Subscription Requests from the same Subscriber:
<subscriptions ...>
<subscription>
<wells namespace="http://www.witsml.org/schemas/140ex">
<well uid="w1"/>
</wells>
</subscription>
<subscription>
<wells namespace="http://www.witsml.org/schemas/140ex">
<well/>
</wells>
</subscription>
</subscriptions>
When well object "w1" changes, the Publisher will send the well object once for the first
subscription, and a second time as a result of the second subscription.
► No attempt is made by the Publisher to merge, consolidate or rationalize "overlapping"
Subscription Requests.

The Subscription Request (<subscription>) element accepts the following XML attributes:

Page 73 of 147
WITSML Application Programming Interface

5.2.1 action attribute - the action being requested

Each Subscription Request must contain an action attribute, specifying:
add - a new subscription is being added
modify - an existing subscription is being modified
cancel - one (or all) existing subscriptions are to be cancelled (deleted)
verify - one (or all) subscriptions are to be verified (and listed)
retransmit - retransmit the realtime headers.

5.2.1.1 action=”add” - add a new subscription

Here is an example of requesting a new subscription:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add” … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
After processing by the Publisher, each add request is returned to the Subscriber as-submitted
with a return code inserted (see retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add” retCode="1" … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
Note that the Subscription Template is made up of one or more plural container elements, such
as <wells>. This is done to allow multiple instances of the same object type to be specified in the
same Template.

Page 74 of 147
WITSML Application Programming Interface

5.2.1.2 action=”modify” - modify an existing subscription

If you need to modify an existing subscription, you specify action=”modify” and provide the
existing subscription ID using the idSub attribute:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”modify” idSub=”12345” … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
After processing by the Publisher, each modify request is returned to the Subscriber as-submitted
with a return code inserted (see retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”modify” idSub=”12345” retCode="1"…>
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
► When modifying an existing subscription, all attributes and elements must be re-specified on
the Subscription Request, and all Subscription Templates (such as the <wells> container in the
example above) must be re-specified; there is no “merging” of information from the existing
subscription to the updated one; action="modify" is a complete replacement.

Page 75 of 147
WITSML Application Programming Interface

5.2.1.3 action=”cancel” - cancel one or all existing subscriptions

If you need to cancel (delete) one existing subscription, you specify action="cancel" and provide
the existing subscription ID using the idSub attribute:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”cancel” idSub=”12345”>
</subscription>
</subscriptions>
When canceling a subscription, you do not need to specify a Subscription Template (i.e., child
elements of the <subscription> element).
After processing by the Publisher, each cancel request is returned to the Subscriber as-submitted
with a return code inserted (see retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”cancel” idSub=”12345” retCode="1">
</subscription>
</subscriptions>
If you need to cancel (delete) all the subscriptions for a given host you can specify
action="cancel", idSub="" and include the host attribute:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”cancel” idSub="" host="myhost.myorg.com">
</subscription>
</subscriptions>
The Publisher will delete all subscriptions associated with the host URL (see host attribute,
described later in this section).
After processing by the Publisher, each deleted subscription will be returned to the Subscriber
with a return code inserted (see retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”cancel” idSub=”12345”
host="myhost.myorg.com"
retCode="1">
</subscription>
subscription action=”cancel” idSub=”67890"
host="myhost.myorg.com"
retCode="1">
</subscription>
</subscriptions>

Page 76 of 147
WITSML Application Programming Interface

5.2.1.4 action=”verify” - verify an existing Subscription

You may verify an existing subscription and retrieve its present contents by specifying
action=”verify” and providing the existing subscription ID using the idSub attribute:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”verify” idSub=”12345” … >
</subscription>
</subscriptions>
Verify does not modify the subscription, and you do not have to specify a Subscription Template
when requesting action=”verify”.
After processing by the Publisher, the entire contents of the existing Subscription - including its
Subscription Template(s) - are returned to the Subscriber with a return code inserted (see
retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”verify” idSub=”12345” retCode="1" … >
… Subscription Template(s)
</subscription>
</subscriptions>
If you need to verify all your existing subscriptions, you can specify action="verify", idSub="" and
include your host attribute:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”verify” idSub="" host="myhost.myorg.com">
</subscription>
</subscriptions>
The Publisher will verify all subscriptions associated with your host URL (see host attribute,
described later in this section).
After processing by the Publisher, the entire contents of all existing Subscriptions matching the
host - including their Subscription Template(s) - are returned to the Subscriber with return codes
inserted (see retCode later in this section):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”verify” idSub=”12345” retCode="1" … >
… Subscription Template(s)
</subscription>
<subscription action=”verify” idSub=”67890” retCode="1" … >
… Subscription Template(s)
</subscription>
</subscriptions>

BEST PRACTICE NOTE

While verifying a subscription doesn’t modify its contents, a Publisher could track the date of last
verification, and use that information to determine which subscriptions are still being used and which
could be considered for “clean up”. Periodic subscription verification can help improve the reliability of
the Subscribe/Publish mechanism and prevent the buildup of “deadwood” subscriptions.

Page 77 of 147
WITSML Application Programming Interface

5.2.1.5 action=”retransmit” - retransmit the realtime headers

The realtime header is included with the first realtime that is returned for each wellbore. The
header is also returned if it is updated. If the realtimeHeaders are desired at any other time then a
subscription specifying action=”retransmit” and providing the existing subscription ID using the
idSub attribute should be submitted:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”retransmit” idSub=”12345” … >
</subscription>
</subscriptions>
The header will be sent with the next available new data.
5.2.2 retCode attribute - the return code
After processing by the Publisher, the Subscription Request(s) are returned to the Subscriber, but
with return codes (retCode attributes) inserted:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add” retCode=”1” … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
The retCode value indicates the disposition of the subscription request. A value of “1” means the
Subscription Request was processed without error.
Although the above example shows the returned Subscription Request for an “add” request, a
retCode attribute will be inserted into the returned Subscription Request regardless of what action
was requested.

Page 78 of 147
WITSML Application Programming Interface

5.2.3 idSub attribute - the subscription identifier

If the retCode value is “1” (meaning OK), the subscription ID (idSub attribute) will also have been
inserted into the returned Subscription Request:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add” retCode=”1” idSub=”XYZ123:12345” … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
The Subscription Identifier uniquely identifies the accepted Subscription Request within a global
context. This identifier must be used exactly as returned by the Publisher in subsequent requests
to modify, verify or cancel the Subscription. The Subscriber must not manipulate the returned
Subscription Identifier.

IMPLEMENTATION NOTE

The Publisher chooses what form the Subscription Identifier takes, such as a character or
numeric string. If a numeric value is used, it should be large enough to not “wrap” - and
cause duplicates IDs - within a reasonable amount of time.
5.2.4 test attribute - test network connectivity
Unless you request otherwise, whenever you request a new subscription or modify or verify an
existing one, a network test will first be performed by the Publisher to make sure it can contact
the Subscriber. The test will consist of an empty data object sent via HTTP/S POST from
Publisher to Subscriber, using the host, process, port, encrypt and idPub values specified in the
new/existing subscription.
► If the network test fails, no further processing will be done on the request and an error code
will be returned.
You may suppress the default network test by specifying the test attribute with a value of “false” in
your subscription object:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription action=”add” test=”false” … >
…
</subscription>
</subscriptions>

BEST PRACTICE NOTE

If your Subscriber system is running and its HTTP/S listener process is active, you should allow the
network test to be performed by omitting the test=”false” attribute. Performing the test will help
prevent the situation in which you’ve requested a subscription, but then fail to receive any data,
because the subscription specified an invalid host or listening process.

Page 79 of 147
WITSML Application Programming Interface

5.2.5 host, process, port and encrypt attributes - specify the subscriber’s URL
In addition to an action and sometimes a subscription ID, each Subscription object must also
contain the following attribute:
host - the DNS host name or IP address of the system that will
receive the published data objects as HTTP/S POSTs.
Optionally, the Subscription object can specify:
encrypt - whether HTTP (encrypt=”false”) or HTTPS (encrypt=”true”) is
to be used to POST the data to the listening process. If omitted,
the default is “false” (use HTTP)
process - the name of the HTTP/S listener process on the “host” system,
including the directory/path name if needed. A leading delimiter
is not required.
port - the TCP port number on which the HTTP/S listener “process”
is listening. If omitted, the default is 80 (if encrypt="false" or
encrypt is omitted) or 443 (if encrypt="true")
The host, process, port and encrypt attributes are combined to create the URL of the system to
which the published data will be sent. A URL consists of:
protocol://host:port/process
The encrypt attribute determines whether http or https will be used as the protocol.
The host attribute specifies the host portion of the URL.
The port value - if explicitly supplied - is used to specify the port portion of the URL. If the port
attribute is supplied, it is separated from the host by a colon (":") character. If the port attribute is
not supplied, the colon character will not be present in the URL.
The process attribute specifies the process portion of the URL. If specified, a forward slash
character ("/") is used to delineate it.
Example:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription host=”myhost.myorg.com”
process=”WMLR_Publish.aspx?id=Sense-898” … >
</subscription>
</subscriptions>
… will result in the URL: http://myhost.myorg.com/WMLR_Publish.aspx?id=Sense-898
In this example, the parameter after the question mark is being used to pass a client assigned
publisher identifier back to the client. When using this technique, the client name should be part
of the identifier.

Page 80 of 147
WITSML Application Programming Interface

5.2.6 idPub attribute - identify the Publisher

If the system that is to receive the published data (the system identified by the host attribute)
requires a userid/password in order to accept POSTs from the Publisher, that userid/password
must be specified in the optional idPub attribute of the Subscription object:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription idPub=”userid:password” … >
</subscription>
</subscriptions>
The value of the idPub attribute must be a valid userid, optionally followed by a valid password. If
a password is present, the userid and password must be separated by a single colon (":")
character (e.g., userid:password).
The userid and password (if present) must be specified as clear, un-encoded text in the
subscription request. The Publisher implementation or its HTTP/S stack will perform the
necessary base64 encoding to comply with the BASIC authentication requirement (see
‘Authentication and Encryption’ section of this document).
5.2.7 retry attribute - the error retry count
A Subscription object can also include the retry attribute to specify the number of retries the
Publisher is to perform before considering a data object to be “undeliverable”:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription retry=”3” … >
</subscription>
</subscriptions>
This example would cause the Publisher to retry a failed HTTP/S POST three times before
treating the data object as undeliverable.
If omitted, the default value of retry is zero (0), meaning that the Publisher does not retry failed
POSTs.

IMPLEMENTATION NOTE

A Publisher is permitted to implement a reasonable upper limit - including zero - on the

number of retries it will attempt. Therefore, while any number of retries can be requested by
the Subscriber, the Publisher can over-ride the request. The Publisher should put the
accepted/overridden value in the returned Subscription object in order to notify the Subscriber
of the actual retry value.
A Publisher is allowed to insert an arbitrary delay interval between performing each of the
retries.

Page 81 of 147
WITSML Application Programming Interface

5.2.8 updateInterval attribute - limit the publication rate

The default frequency for publication of changes to an object matching the Subscription Template
is “as frequently as it is changed”. That is, the Publisher will, by default, publish a data object
matching the Subscription Template each time the object is changed, regardless of how
frequently that might be.
The subscription request can specify an update interval to limit the frequency of the publications
by including the optional updateInterval attribute of the Subscription object. The updateInterval
value specifies the minimum period (in seconds) between publications of a given object.
Regardless of how frequently the object changes, the Publisher will send the changed object to
the Subscriber no more frequently than the specified updateInterval.
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription updateInterval=”60” …>
</subscription>
</subscriptions>

CONCEPT

The Publisher will check for changes to an object no more frequently than the updateInterval,
such that the latest state of the changed object is sent. For example, a channel may get
updated every second, but at the 5 second updateInterval, only the latest channel value will be
published.

The updateInterval does not specify a maximum period. If there have been no changes to the
data objects, no publication will occur (e.g., there is no maximum period).

The updateInterval specified in the subscription request also specifies the default interval for the
realtime object, unless over-ridden by the realtime object’s <interval> element.

Page 82 of 147
WITSML Application Programming Interface

5.2.9 Subscription Object Attribute Summary

Here is a summary of all the XML attributes that can be specified on the Subscription Request
(<subscription>) element.
attribute required values default
action yes add, modify, cancel, verify,
retransmit (none)
retCode yes (1) WITSML-defined codes (none)
idSub yes (2) defined by Publisher (none)
test no true, false true
host yes (6) valid hostname or IP addr (none)
process no name of process on host null string
port no TCP port number 80 or 443 (3)
encrypt no true, false false
idPub no userid:password (4) (none)
retry no 0-n 0
updateInterval no n (seconds) (none) (5)
Notes:
1) required in all Subscription Requests returned from Publisher to Subscriber.
2) except in an initial Subscription request when action=”add” or when action="cancel
(or "verify") and user wishes to delete (or verify) all subscriptions for associated host.
3) port 80 is default if encrypt=”false” (or defaulted); port 443 is default if encrypt="true"
4) or just userid (without the ":" character) if no password is needed.
5) Publisher can send data objects as frequently as they become available.
6) required when adding a new subscription or when canceling or verifying all
subscriptions (i.e., when idSub="")

Page 83 of 147
WITSML Application Programming Interface

5.3 Subscription Templates

The following describes the standard behavior of the Subscription Template. For data
objects that conform to special requirements, special handling has been defined that
extends this standard behavior (see Appendix D - Special Handling).

Now that we’ve described the Subscription Request element and its attributes, let’s now look at
Subscription Templates. A Subscription Template specifies the data object types and data items
within those objects that are to be published for a particular Subscription, much like the Query
Templates used by the STORE interface.
Here is our earlier example showing two Subscription Requests, each with their own Subscription
Templates:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … > ç Subscription Request #1
<wells … /> ß Subscription Template #1a
<wellbores … /> ß Subscription Template #1b
</subscription>
<subscription … > ç Subscription Request #2
<trajectorys … /> ß Subscription Template #2
</subscription>
</subscriptions>
Each Subscription Template specifies both:
 the contents of the published data objects, by including those XML elements/attributes
that are to be sent by the Publisher, but without specifying a value for the
elements/attributes. The following example requests that a well object be published
whenever any well object on the Publisher is changed, and that the published well
objects are to contain only the country data item (and its parent items):
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well><country/></well>
</wells>
</subscription>
</subscriptions>
The published well object might contain:
<wells>
<well>
<country>UK</country>
</well>
…
</wells>

Page 84 of 147
WITSML Application Programming Interface

 The selection of which data objects are to be published, by including a value with the
XML elements and/or attributes. The following example requests that a well object be
published whenever a well object containing a country data item of “Norway” is changed:
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well>
<country>Norway</country>
</well>
</wells>
</subscription>
</subscriptions>
The structural content of the published well object(s) would be the same as in the first
example above. The difference is that in the first example, a change to any well object will
result in a publication, while in the second example only a change to a well with a country
data item of “Norway” will result in a publication.
► The plural data object container provides for more than one Subscription Template for a given
WITSML data object type within one Subscription Request.
<subscriptions xmlns="http://www.witsml.org/api/140">
<subscription … >
<wells namespace="http://www.witsml.org/schemas/140ex">
<well uid="1"/>
<well uid="2"/>
</wells>
</subscription>
</subscriptions>
The plural container is required even if only one instance of a data object type is specified in the
Subscription Template.

Page 85 of 147
WITSML Application Programming Interface

IMPORTANT

The Subscription Template specifies only the data items that are to be published
when/if any data item in the data object is changed.
It does not specify the data items that are to be “monitored” for changes!
There is no relationship between the data item(s) which changed and those requested
to be returned by the Subscription Template. The data items that changed - and thus
triggered the object to be published - will be included in the published objects only if
they were specified in the Subscription Template.

IMPLEMENTATION NOTE

The comparison of Subscription Template values is performed against both the

“before" and "after” update value of the data item. For instance, if a Subscription
Template specified a value of "UK" for the country data item, the object will be eligible
to be published whether the country data item were equal to "UK" before or after the
update.
Only the "after" value is included in the published data object; the "before" value is not
published.
More Examples:
Template Contains Before After Published
Value Value Value
<country>UK</country> UK Norway Norway
<country>Norway</country> UK Norway Norway
<country>US</country> UK Norway object not published

Page 86 of 147
WITSML Application Programming Interface

5.3.1 Realtime Example

The realtime object is designed to permit transmittal of data as it is being acquired (similar to a
demultiplexed log). It has behavior similar to a systematically growing object (See “Appendix E –
Special Handling of Growing Objects”) but the data is defined at the individual cell level rather
than at the row level and it does not have a structural range capability. The realtime header
describes a table structure with each column representing a sensor channel. The channel
element represents one value from one sensor at one index value. Realtime data is commonly
converted to a log in order to make it persistent. The realtime header will exist until the realtime
stream is finished and then the header will normally be deleted. Each individual channel value is
intended to be transient and will normally exist for only a short time.
A common scenario for accessing realtime is to use WMLS_GetFromStore to access the
realtimeHeaders for a particular wellbore in order to determine what channels are available. The
results of the STORE query is then used to create a template for WMLP_Subscribe.
For example, the following WMLS_GetFromStore template requests the mnemonics for each
channel of a particular wellbore.
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<realtimeHeader>
<channelDefinition>
<mnemonic/>
</channelDefinition>
</realtimeHeader>
</realtime>
</realtimes>
This might return the following message. Note that realtime does not contain an index channel.
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<realtimeHeader>
<channelDefinition>
<mnemonic>WOB</mnemonic>
</channelDefinition>
<channelDefinition>
<mnemonic>SPM</mnemonic>
</channelDefinition>
</realtimeHeader>
</realtime>
</realtimes>

Page 87 of 147
WITSML Application Programming Interface

Based on this result a subscription can be submitted using the following template.
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b">
<md uom=””/>
<realtimeHeader>
<channelDefinition>
<mnemonic>WOB</mnemonic>
</channelDefinition>
<channelDefinition>
<mnemonic>SPM</mnemonic>
</channelDefinition>
</realtimeHeader>
<channel>
<mnemonic/>
<value uom=/>
</channel>
</realtime>
</realtimes>

Page 88 of 147
WITSML Application Programming Interface

The realtimeHeader data will be returned with the first data that is published but not with
subsequent data. Thus the following sequence of messages might be published as a result of the
above subscription.
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b" idSub=”12345”>
<md uom=”m”>3598.346</md>
<realtimeHeader>
<channelDefinition>
<mnemonic>WOB</mnemonic>
<channelDefinition>
<channelDefinition>
<mnemonic>SPM</mnemonic>
</channelDefinition>
</realtimeHeader>
<channel>
<mnemonic>SPM</mnemonic>
<value uom=”rpm”>78.160<value>
</channel>
<channel>
<mnemonic>WOB</mnemonic>
<value uom=”t”>5.979<value>
</channel>
</realtime>
</realtimes>
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b" idSub=”12345”>
<md uom=”m”>3578.14</md>
<channel>
<mnemonic>SPM</mnemonic>
<value uom=”rpm”>78.160<value>
</channel>
<channel>
<mnemonic>WOB</mnemonic>
<value uom=”t”>5.979<value>
</channel>
</realtime>
</realtimes>
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b" idSub=”12345”>
<md uom=”m”>3598.346</md>
<channel>
<mnemonic>SPM</mnemonic>
<value uom=”rpm”>78.172<value>
</channel>
</realtime>
</realtimes>
<realtimes xmlns="http://www.witsml.org/schemas/140ex">
<realtime uidWell="w1" uidWellbore="w1b" idSub=”12345”>
<md uom=”m”>3601.285</md>
<channel>
<mnemonic>WOB</mnemonic>
<value uom=”t”>5.967<value>
</channel>
</realtime>
</realtimes>

Page 89 of 147
WITSML Application Programming Interface

And so on. The md element defines the node index and the mnemonic element identifies the
column identifier for each data value.

5.4 Publishing and Maintaining Subscriptions

The Publisher does not specify the nature of the “change” to the object. The object could have
been added, modified or deleted.

When an object is deleted the Publisher should send only the unique identifiers (UID’s) of
the deleted object, regardless of the Subscription Template contents.
Because this manner of indicating a deleted object can be somewhat ambiguous, it is
strongly recommended that a subscriber perform a STORE interface query to the
originating system to verify that the object has in fact been deleted.

Subscriptions are maintained indefinitely - until cancelled by the Subscriber or by the

administrator of the Publisher system. There is no mechanism in WITSML that notifies the
subscriber about a cancellation so the verify action should be periodically utilized to insure that
the subscription is still active. The Subscriber can always modify or cancel a subscription but the
Publisher may allow others to modify or cancel a subscription depending on the user rights in that
system.
A subscription is retained by the Publisher in a non-volatile store, such that no action is required
by the Subscriber upon restart of the Publisher system; the subscription will still be present and
active.
If connectivity is lost for any reason, there is no requirement for the Publisher to retain data
objects for resending; it is expected that Publishers will simply discard documents that cannot be
published.
Failure to publish a document to a Subscriber does not affect the subscription. The subscription
will remain active, and the Publisher will continue publishing when the next document is available
for that Subscriber.

Page 90 of 147
WITSML Application Programming Interface

5.5 POST Request

The Publisher sends data objects to Subscribers using an HTTP/S POST Request.
5.5.1 Syntax
The general syntax is: 6
POST request-uri HTTP/1.1 crlf
Host: host [ ":" port ]
Content-Type: application/xml; charset=utf-8 crlf
Content-Length: length crlf
Authorization: BASIC credentials crlf
crlf
message-body
Where the text shown in italics indicates variable content as follows:
crlf is a US-ASCII CR, carriage return (13)
immediately followed by a
US-ASCII LF, linefeed (10)
request-uri specifies the resource upon which to apply the request
host and port specify the Internet host and optional port number of the
resource being requested:
Host: www.witsml.org
Host: www.other.org:1234
length specifies the length of the message-body, in decimal octets
credentials is the userid and password, separated by a single colon (":")
character as a base64 encoded string
message-body is one or more WITSML data objects within a plural container
element, preceded by an <?xml …> element
► Text not in italics should be specified as-shown.

6
for a more rigorous definition of HTTP syntax, see http://www.w3.org/Protocols/rfc2616/rfc2616.html

Page 91 of 147
WITSML Application Programming Interface

5.5.2 Notes:
 The Publisher places one or more WITSML data objects - in the form of a single XML
document - in the message body of the HTTP/S POST request.
 Multiple WITSML data objects of the same type may be sent in one request.
 The root element of the XML document must be a plural container element of the same
type as the data object(s), such as:
<wells…>
<well … />
<well … />
</wells>
 The plural root element must be included even if there is only one data object.
 The Authorization field may be omitted if no authorization is required by the subscriber.
 Other HTTP Request fields may be included as needed.
5.5.3 Example:
POST /witsml/listener HTTP/1.1
Host: www.witsml.org
Content-Type: application/xml
Content-Length: 182
Authorization: BASIC QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version=“1.0” encoding=“UTF-8”?>

<wells xmlns=“http://www.witsml.org/schemas/140ex”>
<well uid=“W-1”>
<name>6507/7-1</name>
<country>Norway</country>
</well>
</wells>

5.6 Authentication and Encryption

The PUBLISH interface uses HTTP/S Basic Authentication, as described in IETF RFC’s 2616
(HTTP 1.1) and 2617 (Authentication).
The userid and password transported via the HTTP/S Basic Authentication mechanism can be
used by the Publisher and/or Subscriber implementations to perform authorization checking and
control.
The capabilities and implementation of authorization checking, if any, are not specified by
WITSML.
Secure Sockets Layer (SSL) for HTTP (HTTPS) can be used to encrypt the HTTP traffic.

Page 92 of 147
WITSML Application Programming Interface

5.7 Capabilities Objects

The PUBLISH interface uses two special objects to exchange information about the “capabilities”
of the Subscriber and the Publisher. These special objects are called the Capabilities objects.

RESTRICTION

While the Capabilities objects are a type of “WITSML object” they cannot be published. The
Capabilities objects are not persisted as data. They can only be accessed using the
WMLP_GetCap function and the CapabilitiesIn/Out parameters of the various PUBLISH interface
functions.

5.7.1 Subscriber Capabilities (capSubscriber) Object

The Subscriber Capabilities or “capSubscriber” object is used to inform the Publisher of the
Subscriber’s functional capabilities. The capSubscriber object is conveyed as the CapabilitiesIn
parameter of the PUBLISH interface's WMLP_Subscribe function. It must be passed on each call;
the value is not maintained across calls.
The CapabilitiesIn parameter may be set to a null string to indicate that no capSubscriber object
is being provided. When a capSubscriber object is not provided, default values for the various
Subscriber capabilities are assumed by the Publisher.
5.7.2 Publisher Capabilities (capPublisher) Object
The Publisher Capabilities or “capPublisher” object is used to inform the Subscriber of the
Publisher’s functional capabilities. The capPublisher object is returned in the CapabilitiesOut
parameter of the PUBLISH interface’s WMLP_GetCap (Get Capabilities) function.

Page 93 of 147
WITSML Application Programming Interface

5.7.3 Capabilities by Object

These are the presently-defined capabilities that can be exchanged using the capSubscriber
and/or the capPublisher objects:
Capability: version of the API which the Subscriber or Publisher supports
Applies to: capSubscriber and capPublisher objects
Conveyed as: apiVers attribute of the capSubscriber or capPublisher element
Syntax: apiVers=”n.n.n”
Default: 1.4.0
Example: <capSubscriber apiVers=”1.4.0”>
</capSubscriber>
Notes: this is the value to be used if it is necessary to dynamically adapt to
differing implementation levels (do not use the version element below)
Capability: contact information for the Subscriber or Publisher
Applies to: capSubscriber and capPublisher objects
Conveyed as: contact child element of the capPublisher or capSubscriber element
Syntax: <contact>
<name>xxx…xxx</name>
<email>xxx…xxx</email>
<phone>nnn…nnn</phone>
</contact>
Default: none
Example: <contact>
<name>Bob Junior</name>
<email>[email protected]</email>
<phone>1-800-555-1302</phone>
</contact>
Notes: any descriptive text
Capability: description of the Subscriber or Publisher
Applies to: capSubscriber and capPublisher objects
Conveyed as: description child element of the capPublisher or capSubscriber element
Syntax: <description>xxxx…xxxx</description>
Default : none
Example: <capPublisher>
<description>Equip Rm A - Rack</description>
</capPublisher>
Notes: any descriptive text
Capability: name of the Subscriber or Publisher
Applies to: capSubscriber and capPublisher objects
Conveyed as: name child element of the capPublisher or capSubscriber element
Syntax: <name>xxxx…xxxx</name>
Default : none
Example: <capPublisher>
<name>Publisher #1</name>
</capPublisher>
Notes: any descriptive text

Page 94 of 147
WITSML Application Programming Interface

Capability: vendor (producer) of the software

Applies to: capSubscriber and capPublisher objects
Conveyed as: vendor child element of the capPublisher or capSubscriber element
Syntax : <vendor>xxxx…xxxx</vendor>
Default : none
Example: <capPublisher>
<vendor>Acme Downhole Software</vendor>
</capPublisher>
Notes:
Capability: version (build) of the executable program
Applies to: capSubscriber and capPublisher objects
Conveyed as: version child element of the capPublisher or capSubscriber element
Syntax : <version>n.n.n.n</version>
Default : none
Example: <capPublisher>
<version>1.4.0.1451</version>
</capPublisher>
Notes:

Page 95 of 147
WITSML Application Programming Interface

Capability: schema version(s) that are supported

Applies to: capSubscriber and capPublisher objects
Conveyed as: schemaVersion child element of the capPublisher or capSubscriber
element
Syntax : <schemaVersion>n.n.n.n,m.m.m.m</schemaVersion>
Default : none
Example: <capClient>
<schemaVersion>1.1.0,1.2.0,1.4.0.0</schemaVersion>
</capClient>
<capServer>
<schemaVersion>1.4.0.0</schemaVersion>
</capServer>
Notes: The values must match the version attribute in the plural object.
For capClient, the value is a comma separated list of values without
spaces. The oldest version should be listed first.
For Publishers, the value must match a value that is returned
by the WMLP_GetVersion function.
Capability: the PUBLISH functions, versions and data objects that the Publisher
supports for each function
Conveyed as: function element of the capPublisher element
apiVers attribute of the function element
dataObject element of the function element
Syntax : <function name=”xxx” apiVers=”n.n.n”>
<dataObject>xxx</dataObject>
</function>
Default: none (Subscriber should not assume capability exists if not explicitly
listed)
Example: <capPublisher apiVers=”1.4.0”>
<function name=”WMLP_Subscribe”>
<dataObject>well</dataObject>
<dataObject>wellbore</dataObject>
<dataObject>realtime</dataObject>
</function>
<function name=”WMLP_GetVersion”>
</function>
</capPublisher>
Notes: the example shows supports for only the three specified data object types
for WMLP_Subscribe. It supports version 1.4.0 for all functions. It also
supports the WMLP_GetVersion function. The capPublisher object does
not need to specify the WMLP_GetCap function, as this is implied if the
capPublisher object is returned to the Subscriber.

Page 96 of 147
WITSML Application Programming Interface

5.8 PUBLISH Functions

This section describes the PUBLISH interface functions.
The following functions are defined:
WMLP_GetBaseMsg - get the fixed "base" description of a return value
WMLP_GetCap - get the Publisher’s Capabilities object
WMLP_GetVersion - retrieves the data version(s) that are supported
WMLP_Subscribe - to request subscriptions to data objects
These functions are documented on the following pages.
5.8.1 WMLP_GetBaseMsg
Returns a string containing the fixed ("base") message text associated with a return value.
string = WMLP_GetBaseMsg(
[in] integer ReturnValueIn,
);
Parameters (all required):
ReturnValueIn - input integer
- a valid Return Value (see “Appendix C - Defined Values”)
Return Value:
string - the fixed descriptive message text associated with the Return
Value (a null string is returned if ReturnValueIn is invalid)
Notes:
1) This function returns only the fixed description of the specified Return Value.
2) Variable, context-specific "supplemental" message text and diagnostic information, if
any, is returned in the SuppMsgOut parameter of the various PUBLISH functions.

Page 97 of 147
WITSML Application Programming Interface

5.8.2 WMLP_GetCap
Returns the capPublisher object which represents the capabilities of the Publisher for one data
schema. The capPublisher object is returned in the form of an XML document. Multiple calls to
WMLP_GetCap are required in order to determine the capabilities of the server for all data
schemas that it supports.
integer = WMLP_GetCap(
[in] string OptionsIn,
[out] string CapabilitiesOut,
[out] string SuppMsgOut
);

Parameters (all required):

OptionsIn - input string
- The keyword "dataVersion" with a value of a data schema version
specifies that capabilities information is desired for that particular data
version. The returned capabilities object will utilize the namespace that is
appropriate for the data version. For example:
dataVersion=1.4.0.0
requests information about data version 1.4.0.0 utilizing a 1.4.0
capabilities object. The data schemas that are supported by the server
can be determined using WMLP_GetVerson. The version string must
match the value of attribute "version" on the plural object container. The
default is for the server to return information about the oldest data
version that is supported by the server
CapabilitiesOut - output string - case sensitive (an XML document)
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C - Defined Values”)
Notes:
none

Page 98 of 147
WITSML Application Programming Interface

5.8.3 WMLP_GetVersion
Returns a string containing the data version(s) that are supported by the Publisher. A particular
data version can be passed to WMLP_GetCap via its OptionsIn parameter to request information
about the server capabilities with respect to that data version.
string = WMLP_GetVersion();
Parameters:
none
Return Value:
string - A comma separated list of schema versions (without spaces) that
are supported by the server. The oldest version should be listed
first, followed by the next oldest, etc
Example: 1.2.0,1.4.0.0
Notes:
Each version number must match the contents of the version attribute on the plural
container element for each object.
For more information, see the topic on Versioning in the Terminology and Basic Concepts
section of this document.

Page 99 of 147
WITSML Application Programming Interface

5.8.4 WMLP_Subscribe
Receives and processes Subscription Requests from Subscribers.
integer = WMLP_Subscribe(
[in] string SubscriptionIn,
[in] string OptionsIn,
[in] string CapabilitiesIn,
[out] string SubscriptionOut,
[out] string SuppMsgOut
);
Parameters (all required):
SubscriptionIn – input string – case sensitive (an XML document)
- one or more WITSML Subscription Requests containing the object
types names to which a subscription is to be created, the subscriber’s
host and receiving process name and other properties of the
subscription.
OptionsIn - input string
- The keyword of ‘returnElements’ with a value of "all" requests that all
elements and attributes be returned. The template should be treated as if
all elements and attributes had explicitly been specified in the template. A
value of "requested" requests the mode of "you only get what you ask
for". The default is "requested". For example:
returnElements=all
CapabilitiesIn - input string - case sensitive (an XML document)
- the Subscriber’s capabilities object (capSubscriber) to be sent to the
Publisher; may be a null string if no capabilities object is to be provided
to the Publisher.
SubscriptionOut – output string – case sensitive (an XML document)
- the WITSML Subscription Requests returned by the Publisher with
return codes inserted for each subscription request.
SuppMsgOut - output string
- supplemental message text
Return Value:
short (see “Appendix C- Defined Values”)
Notes:
1) output parameters are valid only if Return Value = 1
2) For various reasons, some servers may impose restrictions on subscriptions. For
example:
a) A publisher may not allow more than one subscription (total).
b) A publisher may not allow more than one subscription per subscriber.
c) A publisher may not allow more than one subscription per object per subscriber.
d) When subscribing to realtime, a publisher may require that the subscriber specify a
specific well and/or wellbore and/or mnemonic.
e) A publisher may not allow multiple templates per subscription request.

Page 100 of 147

WITSML Application Programming Interface

5.9 PUBLISH Interface - WSDL File

The Web Service Description Language (WSDL) file used to expose the PUBLISH interface to
SOAP clients is listed below. A narrative describing several key points follows the file listing.

IMPORTANT

In order to ensure interoperability between implementations,

the only part of the WSDL file that should normally be modified is the
location attribute of the SOAP address element.
Other than the location attribute, the WSDL file should be used exactly as
shown in the following file listing.
The WSDL file is also provided in the WITSML distribution media.

Page 101 of 147

WITSML Application Programming Interface

5.9.1 File Listing

<?xml version='1.0' encoding='UTF-8' ?>
<definitions name='WMLP' targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
<documentation>WITSML Version 1.2.0 PUBLISH interface WSDL file
</documentation>
<!-- Abstract Definitions Section - <types>, <message> and <portType> elements -->
<!-- <types> element declares user-defined machine and language independent data types,
and is not needed for the WITSML PUBLISH interface, which uses only W3C-defined data
types -->
<!-- <message> elements define request/response messages and their parameters-->
<message name='Publish.WMLP_GetBaseMsg'>
<part name='ReturnValueIn' type='xsd:short'/>
</message>
<message name='Publish.WMLP_GetBaseMsgResponse'>
<part name='Result' type='xsd:string'/>
</message>

<message name='Publish.WMLP_GetCap'>
<part name='OptionsIn' type='xsd:string'/>
</message>
<message name='Publish.WMLP_GetCapResponse'>
<part name='CapabilitiesOut' type='xsd:string'/>
<part name='SuppMsgOut' type='xsd:string'/>
<part name='Result' type='xsd:short'/>
</message>

<message name='Publish.WMLP_GetVersion'>
</message>
<message name='Publish.WMLP_GetVersionResponse'>
<part name='Result' type='xsd:string'/>
</message>

<message name='Publish.WMLP_Subscribe'>
<part name='SubscriptionIn' type='xsd:string'/>
<part name='OptionsIn' type='xsd:string'/>
<part name='CapabilitiesIn' type='xsd:string'/>
</message>
<message name='Publish.WMLP_SubscribeResponse'>
<part name='Result' type='xsd:short'/>
<part name='SubscriptionOut' type='xsd:string'/>
<part name='SuppMsgOut' type='xsd:string'/>
</message>
<!-- <portType> element groups the functions (operations) into an interface -->

Page 102 of 147

WITSML Application Programming Interface

<portType name='PublishSoapPort'>
<!-- <operation> elements define the function signatures (operation name and parameters)
and associate the input and output messages -->
<!-- parameterOrder attribute values must be separated by a single space -->
<operation name='WMLP_GetBaseMsg' parameterOrder='ReturnValueIn'>
<input message='wsdlns:Publish.WMLP_GetBaseMsg' />
<output message='wsdlns:Publish.WMLP_GetBaseMsgResponse' />
</operation>
<operation name='WMLP_GetCap'
parameterOrder='OptionsIn CapabilitiesOut SuppMsgOut'>
<input message='wsdlns:Publish.WMLP_GetCap' />
<output message='wsdlns:Publish.WMLP_GetCapResponse' />
</operation>
<operation name='WMLP_GetVersion'>
<input message='wsdlns:Publish.WMLP_GetVersion' />
<output message='wsdlns:Publish.WMLP_GetVersionResponse' />
</operation>
<operation name='WMLP_Subscribe'
parameterOrder='SubscriptionIn OptionsIn CapabilitiesIn SubscriptionOut SuppMsgOut'>
<input message='wsdlns:Publish.WMLP_Subscribe' />
<output message='wsdlns:Publish.WMLP_SubscribeResponse' />
</operation>
</portType>
<!-- Concrete Definitions Section - <binding> and <service> elements -->
<!-- <binding> specifies the protocol binding for each operation in the <portType> section
-->
<binding name='PublishSoapBinding' type='wsdlns:PublishSoapPort' >
<soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http' />
<operation name='WMLP_GetBaseMsg' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Publish.WMLP_GetBaseMsg' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLP_GetCap' >
<soap:operation soapAction='http://www.witsml.org/action/120/Publish.WMLP_GetCap' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />

Page 103 of 147

WITSML Application Programming Interface

</output>
</operation>
<operation name='WMLP_GetVersion' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Publish.WMLP_GetVersion' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
<operation name='WMLP_Subscribe' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Publish.WMLP_Subscribe' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
<output>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</output>
</operation>
</binding>
<!-- <service> specifies the portType for each binding and the URL of the service -->
<service name='WMLP' >
<port name='PublishSoapPort' binding='wsdlns:PublishSoapBinding' >
<soap:address location='http://yourorg.com/yourwebservice' />
</port>
</service>
</definitions>

Page 104 of 147

WITSML Application Programming Interface

5.9.2 Narrative
 The only part of the WSDL file that should normally be modified is the location attribute of the
SOAP address element. This should be set to the URL of the Web Service (see
implementation specifics below):
<service name='WMLP' >
<port name='PublishSoapPort' binding='wsdlns:PublishSoapBinding' >
<soap:address location='http://yourorg.com/yourwebservice' />
</port>
</service>
 The WSDL file complies with Version 1.1 of the Web Services Description Language
(www.w3.org/TR/wsdl)
 The target namespace and wsdlns prefix used in the WSDL file are both declared as:
'http://www.witsml.org/wsdl/120
<definitions name='WMLP'
targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
 A default namespace declaration is used to make the document more readable:
<definitions name='WMLP' targetNamespace='http://www.witsml.org/wsdl/120'
xmlns:wsdlns='http://www.witsml.org/wsdl/120'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
 The soapAction attribute of the SOAP operation elements specify a WITSML-related URI:
http://www.witsml.org/action/120/Publish.WMLP_xxxx
The soapAction attribute is used by the HTTP transport as the value of the SOAPAction
HTTP header. Its use is not clear as of this writing; SOAP 1.1 states that it can be used to
identify the “intent” of messages.
<operation name='WMLP_Subscribe' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Publish.WMLP_Subscribe' />
<input>
…
 The namespace attribute of the SOAP body elements also specify a WITSML-related URI:
http://www.witsml.org/message/120
<operation name='WMLP_Subscribe' >
<soap:operation
soapAction='http://www.witsml.org/action/120/Publish.WMLP_Subscribe' />
<input>
<soap:body use='encoded' namespace='http://www.witsml.org/message/120'
encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' />
</input>
</operation>
…

Page 105 of 147

WITSML Application Programming Interface

 Although XML generally ignores white-space, the values of certain XML attributes and
elements may be sensitive to the amount of white-space. For example, the parameterOrder
attribute of the <operation> element must have only a single space between parameters:
<operation name='WMLP_Subscribe' parameterOrder='SubscriptionIn OptionsIn CapabilitiesIn
SubscriptionOut SuppMsgOut'>
For an easy-to-read, understandable introduction to WSDL files, see the article titled “Web
Services Description Language (WSDL) Explained” by Carlos C. Tapang - Infotects (in the
Microsoft MSDN Library and elsewhere).

Page 106 of 147

WITSML Application Programming Interface

6. APPENDIX A - Example Data Object Schema

The schema in this section is a non-normative example that is used to demonstrate server
behavior. The portions of the schema that conform to normative requirements are:
1) The root elements are a plural form of the first child element that is formed by adding an
“s” to the singular child element. The singular child will be called an “object” within the
context of this specification.
2) The object has mandatory uid attributes. In this example, they are named “uid”.
3) An object may have foreign uid keys to a “parent” object. In this example, the attributes
are named by suffixing “uid” with the parent object name. For example, the parent object
of wellbore is well. The foreign key from wellbore to well is uidWell.
4) Recurring nodes that are intended to be updatable via WMLS_UpdateInStore must have
a uid attribute. An update of a recurring element that does not have a uid attribute will
result in all existing instances of the element being replaced.
Objects well and wellbore are general objects that demonstrate a parent object – child object
relationship.
The mudLog object represents a randomly growing object. It has two recurring child elements that
both contain “index” values (i.e., mdTop and mdBot). The mudLog contains corresponding “index”
values (i.e., startMd and endMd) that represent the range of the child index values in that
mudLog.
The trajectory object is similar to the mudLog object except that its recurring child element
represents a point rather than an interval. The relevant indexes are mdMx, mdMn and md.
The log object represents a systematically growing “table” where the data is added as “the next
row”. The table has an index column and index range values (i.e., startIndex, endIndex,
startDateTimeIndex and endDateTimeIndex) for the overall table (in logHeader) and for individual
columns of the table (in logCurveInfo).
The realtime object represents a transient stream of data. There will be one header for each
wellbore.
The actual form of these objects in a data model is not critical to the behavior described in this
specification. It is the servers responsibility to adjust to variations in the schemas and to support
the relevant behavior. Inherent to this behavior is that the server must understand underlying
concepts such as units of measure, data types, index columns, etc.

Page 107 of 147

WITSML Application Programming Interface

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema
elementFormDefault="qualified"
attributeFormDefault="unqualified"
targetNamespace="http://www.witsml.org/schemas/140ex"
xmlns= "http://www.witsml.org/schemas/140ex"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!-- -->
<!-- ENERGISTICS License Agreement
This file is distributed under the ENERGISTICS License Agreement at
http://www.energistics.org/posc/Product_License_Agreement.asp.
Use of this file constitutes agreement with the ENERGISTICS License Agreement.
-->
<!-- -->
<xsd:annotation>
<xsd:documentation>Example non-normative schemas to describe API behavior.
</xsd:documentation>
</xsd:annotation>
<!-- -->
<!-- -->
<xsd:element name="wells">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="well" maxOccurs="unbounded"> <!—well object à
<xsd:complexType>
<xsd:sequence>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="nameLegal" type="xsd:string" minOccurs="0"/>
<xsd:element name="country" type="xsd:string" minOccurs="0"/>
<xsd:element name="itemState" type="xsd:string" minOccurs="0"/>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<!-- -->
<xsd:element name="wellbores">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="wellbore" maxOccurs="unbounded"> <!—wellbore object à
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nameWell" type="xsd:string"/>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="numGovt" type="xsd:string" minOccurs="0"/>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uidWell" type="xsd:string" use="required"/>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<!-- -->
<xsd:element name="mudLogs">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mudLog" maxOccurs="unbounded"> <!—mudLog object à
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nameWell" type="xsd:string"/>
<xsd:element name="nameWellbore" type="xsd:string"/>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="objectGrowing" type="xsd:string" minOccurs="0"/>
<xsd:element name="startMd" type="measure" minOccurs="0"/>
<xsd:element name="endMd" type="measure" minOccurs="0"/>
<xsd:element name="parameter" minOccurs="0" maxOccurs="unbounded">

Page 108 of 147

WITSML Application Programming Interface

<xsd:complexType>
<xsd:sequence>
<xsd:element name="mdTop" type="measure" minOccurs="0"/>
<xsd:element name="mdBottom" type="measure" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="geologyInterval" minOccurs="0"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="typeLithology" type="xsd:string”/>
<xsd:element name="mdTop" type="measure>
<xsd:element name="mdBottom" type="measure" minOccurs="0"/>
<xsd:element name="lithology" minOccurs="0"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="type" type="xsd:string”/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uidWell" type="xsd:string" use="required"/>
<xsd:attribute name="uidWellbore" type="xsd:string" use="required"/>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<!-- -->
<xsd:element name="trajectorys">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="trajectory" maxOccurs="unbounded"> <!—trajectory object à
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nameWell" type="xsd:string"/>
<xsd:element name="nameWellbore" type="xsd:string"/>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="objectGrowing" type="xsd:string" minOccurs="0"/>
<xsd:element name="mdMn" type="measure" minOccurs="0"/>
<xsd:element name="mdMx" type="measure" minOccurs="0"/>
<xsd:element name="trajectoryStation" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="md" type="measure" minOccurs="0"/>
<xsd:element name="mdDelta" type="measure" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uidWell" type="xsd:string" use="required"/>
<xsd:attribute name="uidWellbore" type="xsd:string" use="required"/>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
<!-- -->
<xsd:element name="logs">

Page 109 of 147

WITSML Application Programming Interface

<xsd:complexType>
<xsd:sequence>
<xsd:element name="log" maxOccurs="unbounded"> <!—log object à
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nameWell" type="xsd:string"/>
<xsd:element name="nameWellbore" type="xsd:string"/>
<xsd:element name="name" type="xsd:string"/>
<xsd:element name="objectGrowing" type="xsd:string" minOccurs="0"/>
<xsd:element name="logHeader" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="dataRowCount" type="xsd:double"
minOccurs="0"/>
<xsd:element name="indexType" type="xsd:string"
minOccurs="0"/>
<xsd:element name="startIndex" type="xsd:double"
minOccurs="0"/>
<xsd:element name="endIndex" type="xsd:double"
minOccurs="0"/>
<xsd:element name="indexUnits" type="xsd:string"
minOccurs="0"/>
<xsd:element name="startDateTimeIndex" type="xsd:dateTime"
minOccurs="0"/>
<xsd:element name="endDateTimeIndex" type="xsd:dateTime"
minOccurs="0"/>
<xsd:element name="direction" type="xsd:string"
minOccurs="0"/>
<xsd:element name="indexCurve" type="xsd:string"
minOccurs="0"/>
<xsd:element name="logCurveInfo" minOccurs="0"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mnemonic" type="xsd:string"
minOccurs="0"/>
<xsd:element name="nullValue" type="xsd:string"
minOccurs="0"/>
<xsd:element name="startIndex" type="xsd:double"
minOccurs="0"/>
<xsd:element name="endIndex" type="xsd:double"
minOccurs="0"/>
<xsd:element name="startDateTimeIndex"
type="xsd:dateTime" minOccurs="0"/>
<xsd:element name="endDateTimeIndex"
type="xsd:dateTime" minOccurs="0"/>
<xsd:element name="columnIndex" type="xsd:integer"
minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="logData" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="data" type="xsd:string" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uidWell" type="xsd:string" use="required"/>
<xsd:attribute name="uidWellbore" type="xsd:string" use="required"/>
<xsd:attribute name="uid" type="xsd:string" use="required"/>
</xsd:complexType>

Page 110 of 147

WITSML Application Programming Interface

</xsd:element>
<!-- -->
<xsd:element name="realtimes">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="realtime" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="dTim" type="xsd:dateTime" minOccurs="0"/>
<xsd:element name="md" type="measure"/>
<xsd:element name="realtimeHeader" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nameWell" type="xsd:string"/>
<xsd:element name="nameWellbore" type="xsd:string"/>
<xsd:element name="channelDefinition" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mnemonic" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="channel" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mnemonic" type="xsd:string"
minOccurs="0"/>
<xsd:element name="md" type="measure" minOccurs="0"/>
<xsd:element name="dTim" type="xsd:dateTime"
minOccurs="0"/>
<xsd:element name="value" type="measure"/>
<xsd:element name="qualData" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="commonData" type="cs_commonData" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="uidWell" type="xsd:string" use="required"/>
<xsd:attribute name="uidWellbore" type="xsd:string" use="required"/>
<xsd:attribute name="idSub" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<!-- -->
<xsd:complexType name="measure">
<xsd:simpleContent>
<xsd:extension base="xsd:double">
<xsd:attribute name="uom" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<!-- -->
<xsd:complexType name="cs_commonData">
<xsd:sequence>
<xsd:element name="dTimCreation" type="xsd:dateTime" minOccurs="0"/>
<xsd:element name="dTimLastChange" type="xsd:dateTime" minOccurs="0"/>
<xsd:element name="serviceCategory" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<!-- -->

</xsd:schema>

Page 111 of 147

WITSML Application Programming Interface

7. APPENDIX B - Unit of Measure

7.1 Overview
Numeric measure values exchanged using WITSML have an associated "uom" attribute that
describes the Unit of Measure for that value. This is a flexible approach that allows data to be
exchanged with the minimum of constraints or assumptions.

7.2 Basics
The "uom" attribute is mandatory for all numeric values that need to be qualified with a unit of
measure indicator to provide the full context of an element value. The value of the uom attribute is
expected to match an ‘annotation’ attribute from the WITSML Units Dictionary XML file that is
included with the Data Schema.
For example, a WITSML document may contain the fragment:
<ropAv uom="ft/h">80.00</ropAv>
This specifies that the value for ropAv is measured in feet per hour ("ft/h").
The "uom" value of "ft/h" is the annotation for a UnitOfMeasure in the WITSML Units Dictionary
reference file as:
<UnitOfMeasure id="ftPh" annotation="ft/h">
<Name>feet/hour</Name>
<CatalogName>POSC</CatalogName>
<CatalogSymbol isExplicit="true">ft/h</CatalogSymbol>
<ConversionToBaseUnit baseUnit="m/s">
<Fraction>
<Numerator>0.3048</Numerator>
<Denominator>3600</Denominator>
</Fraction>
</ConversionToBaseUnit>
</UnitOfMeasure>
This gives a link to the base SI unit of meters per second and a suggested conversion to this
base unit.
In this way, any WITSML compliant document can be decoded by any application that can work
with SI units.

Page 112 of 147

WITSML Application Programming Interface

7.3 Process interaction with ‘uom’

A provider and consumer of WITSML documents can work with units in a number of ways:
1) No preference of units expressed by the consumer (i.e. ‘uom’ in a query template is
empty or absent, or the document has been generated as a result of a non-SOAP
request). The provider will provide the data in a mutually agreed or default set of units of
measure.
For example, a request for <ropAv uom=““/> gives
<ropAv uom=“ft/h”>80.00</ropAv>
2) The consumer requests an element in a particular unit of measure that is recognized by
the provider as compliant with WITSML. The provider will supply the element converted
to the requested unit of measure and with the ‘uom’ attribute populated appropriately.
For example, a request for <ropAv uom=“ft/min”/> gives
<ropAv uom=“ft/min”>1.3333</ropAv>
3) The consumer requests an element in a particular unit of measure that is NOT
recognized by the provider as compliant with WITSML. The provider will supply the
element converted to the server default unit of measure and with the ‘uom’ attribute
populated appropriately.
For example, <ropAv uom=“furlong/fortnight”/> gives
<ropAv uom=“ft/h”>80.00</ropAv>
4) The provider does not support requests for units of measure other than the server
default.
For example, a request for <ropAv uom=“ft/min”/> gives
<ropAv uom=“ft/h”>80.00</ropAv>
Notes:
It is server dependent as to which options are supported.

7.4 Server defaults

A server must have a default set of units. This might be as simple as returning whatever unit is
defined for the value in the persistent store and the unit may or may not be the original unit.
Another default might be to return the values in a preferred unit system. The preferred system will
commonly be defined in a contract.

Page 113 of 147

WITSML Application Programming Interface

7.5 Responsibilities
If a unit is requested, a server / publisher will always populate the ‘uom’ attribute of an element
with an entry that describes the units of the element value. The ‘uom’ will align with the WITSML
units dictionary.
The source of the data should use consistent units within an object. For example, all length
measures in the same unit and all coordinates of the same type (e.g., measured depth) in the
same unit. The unit system should also be consistent (e.g., metric). The source might be a server
or it might be a client that adds data to a server.
A uom attribute is not part of the selection criteria. Specifying a particular uom value in a query
template is a request for the element value to be returned in those units But, the client /
subscriber should verify that the ‘uom’ in the returned document matches that requested and if
not, handle any mismatch as it sees fit.
If an empty uom attribute is specified in a query then a default unit will be returned.
The unit should not change in validated data but, since we are trying to support realtime
conditions, a server must be allowed to "fix" the data. If a unit element or uom attribute changes
then the client should retrieve the "modified" value because the unit is an integral part of the data
value. For a curve, the whole curve should be retrieved.

7.6 Updating
The WITSML Units Dictionary file) is included in the WITSML distribution media for each WITML
Data Schema version.
Updates to the Units Dictionary are made as part of the WITSML Data Schema revision process.

Page 114 of 147

WITSML Application Programming Interface

8. APPENDIX C - Defined Values

8.1 Return Values
The values returned in intReturn by the WITSML API functions are shown below, along with the
string returned by the WMLx_GetBaseMsg function.
The WITSML-defined Return Values are in the range of -999 thru -1 (to indicate exception
conditions) and 1 (to indicate no exception occurred).
Implementers are encouraged to use values from this list whenever possible.
It is recognized that this list is incomplete, however, and additional values will need to be defined
over time.
If no Return Value is presently defined for an error condition, implementers are free to assign their
own proprietary Return Values less than -1000 (i.e., -1001, -1002, etc).
It is hoped that proprietary Return Values will be contributed to the WITSML community for
possible inclusion in this standard list.
Value String returned by WMLx_GetBaseMsg
1 Function completed successfully
-1nn: Parameter errors
-101 Parameter error: Invalid/missing WITSML object type
-102 Parameter error: Invalid/missing XML
-103 Parameter error: Invalid/missing selection criteria
-104 Parameter error: Invalid/missing server name
-105 Parameter error: Invalid/missing publisher name
-106 Parameter error: Invalid/missing subscriber name
-107 Parameter error: Invalid/missing real-time data type name
-108 Parameter error: Invalid/missing real-time data
-109 Parameter error: Invalid/missing XML Schema (XSD) path/filename
-110 Parameter error: Invalid option
-111 Parameter error: Invalid/missing subscriber process location
-112 Parameter error: Invalid/missing subscriber secure indicator
-113 Parameter error: Unsupported compression method requested.
-199 Parameter error: unknown cause

Page 115 of 147

WITSML Application Programming Interface

-2nn: Persistent Store errors

-201 Persistent Store error: Duplicate key
-202 Persistent Store error: Could not parse XML
-203 Persistent Store error: Could not map XML
-204 Persistent Store error: No data matched selection criteria
-205 Persistent Store error: The query results are too large
-206 Persistent Store error: Access denied for requested operation.
-207 Persistent Store error: Requested deletion requires cascaded deletes.
-208 Persistent Store error: Systematically growing object index duplicates existing index.
-209 Persistent Store error: Append requested but indices are within current index range
of systematically growing object.
-299 Persistent Store error: unknown cause
-3nn: XML Schema errors
-301 XML Schema error: Error while parsing the specified XML Schema (XSD) file
-302 XML Schema error: specified XML Schema (XSD) has invalid content
-303 XML Schema error: no base attribute present below data type definition element
-304 XML Schema error: nesting of data types exceeds maximum - check for circular
reference in definitions
-305 XML Schema error: unrecognized XML Schema data type
-306 XML Schema error: circular reference (loop) in included schemas
-399 XML Schema error: unknown cause
-9nn: program logic/exception errors
-901 Program Error: problem loading internal program or component
-902 Program Error: XML Schema data type is not presently supported by the
WITSML API
-999 Program Error: unknown cause

Page 116 of 147

WITSML Application Programming Interface

9. APPENDIX D – Special Handling of Change

Information
There are four mechanisms which assist in understanding the change process in a WITSML
server.
1) The element dTimCreation is contained in the commonData structure that exists in all
objects. It is intended to define when the data was first created in the server.
2) The element dTimLastChange is contained in the commonData structure that exists in all
objects. It is intended to reflect when most the recent change has happened to any data
in a particular object.
3) The element objectGrowing is contained in all growing objects. It provides the current
status of that object with respect to its growing behavior.
a. A value of “growing” means that the object is actively growing.
b. A value of “closed” means that the object is not growing and is not expected to
grow any further.
c. A value of “idle” means that the object is not currently growing but is not yet
closed.
4) The changeLog object is intended to expose knowledge of any changes in the server. It
provides a central point to discover which objects have changed and when.
This section outlines the behavior expected of the server with respect to updating these
mechanisms. For the purpose of this section, “append” means to add new data whose index is
greater than the current maximum index.
1) dTimCreation is a server parameter and cannot be set by a Client. It represents the time
that the data was loaded into the server. That is, an aggregating server would reset it at
the time the data was loaded from a source. If acquisition related timestamps are
relevant, an object will have specific elements for that information.
2) For a rapidly growing object, the statistical data (e.g., start/end, min/max, row count) may
be updated at a slower frequency than the data itself. Thus, if a client needs accurate
statistics while an object is growing, it will need to derive them itself.
3) Any appendages to a growing object will not be reflected in dTimLastChange as long as
objectGrowing is set to "growing". This excludes an add within the current min/max
indices of the growing part
4) If something is appended to a growable object (objectGrowing="idle"), objectGrowing
should be set to "growing" which will trigger an update to dTimLastChange.
5) All updates should be reflected in dTimLastChange within a "detection period" defined by
the server (normally under contractual control). This would normally be expected to be an
order of magnitude of minutes. For example, a "detection period" of 10 minutes would
mean that a server is expected to update the "exposed" server contents within 10
minutes of the actual real world change. A second object-kind specific (e.g., log versus
mudLog) detection period may be defined for the special case of determining when an
object has become "idle". This is to prevent thrashing of the toggle between "growing"
and "idle".
6) When objectGrowing="growing", if nothing is appended within the "detection period", the
value of objectGrowing should be set to "idle".

Page 117 of 147

WITSML Application Programming Interface

7) Any update to an existing part of a growing object will be reflected in dTimLastChange.

a) This excludes query parameters and statistical data which are inherently changed as
a result of growth.
b) This includes any changes to previously added parts of the growing area.
c) This includes any changes to the non-growing part of an object (including
objectGrowing).
d) This includes an insertion within the current min/max indices of the growing part.
e) This includes any changes in commonData such as dTimCreation but obviously
excludes dTimLastChange itself.
8) If something is appended to a non-growable object (objectGrowing="closed"),
dTimLastChange should be updated.
9) Once objectGrowing="closed" it is not expected that it will be changed. However, since it
is not a perfect world, the value may change from "closed" to "growing" with a
corresponding change to dTimLastChange.
10) Changes to element objectGrowing should be immediately reflected in dTimLastChange.
This does not mean that new recorded data will immediately result in a change to
objectGrowing because they are subject to the "detection period".
11) The value of dTimLastChange should reflect the time of detection. In an aggregating
server, this is the time when the aggregating server updated the data from the source.
This is necessary in order to allow a client to query for new data since the last time it
checked.
12) All changes to dTimLastChange should immediately trigger a corresponding update to
changeLog.
13) When data is added by a client, the server should set the dTimCreation and
dTimLastChange to the time when the operation was detected
14) Only the server can set dTimLastChange. A client can only indirectly change the
dTimLastChange by modifying the data.

When objectGrowing is set to "growing", a client can monitor for appendages by polling for any
new growth since the previously known index. It is suggested that the client polling rate adapt to
the historical append rate for that object.

Page 118 of 147

WITSML Application Programming Interface

10. APPENDIX E – Special Handling of Growing

Objects
Several WITSML data objects contain recurring groups of data items organized into structures.
For example, the mudLog object can contain multiple occurrences of the group of data items
related to a geologyInterval:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
…
<geologyInterval>
<mdTop uom="ft">5000</mdTop>
<mdBottom uom="ft">5030</mdBottom>
…
</geologyInterval> mudLog data object with multiple
<geologyInterval> geologyInterval structures
<mdTop uom="ft">5030</mdTop>
<mdBottom uom="ft">5060</mdBottom>
…
</geologyInterval>
…
</mudLog>
Using the standard behavior of the Query and Subscription templates, the above mudLog object
could be retrieved or subscribed by specifying:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
<geologyInterval>
…
template requesting all
</geologyInterval> geologyIntervals
</mudLog>
This template will retrieve - or cause to be published - all occurrences of the geologyInterval
structure within the mudLog object.
If, however, one wished to retrieve only a particular range of geologyIntervals, then special
handling - above and beyond the standard behavior - is required by the Server and Publisher.

Page 119 of 147

WITSML Application Programming Interface

To accommodate the need to selectively retrieve or have published only a range of occurrences
of a structure, special handling rules have been defined for some types of data objects.
Generally, the data objects with special handling rules are those that:
1) have a relatively large number of occurrences of recurring data that is indexed in depth or
time
and
2) have additional occurrences of recurring data that are inserted (or updated) over time
(e.g., the object grows)
There are two types of these growing objects that are supported with special behavior: randomly
growing and systematically growing. For randomly growing object the indexes in the
substructures are unrelated and they may overlap or coexist in the index space. These
substructures must be assigned a uid attribute. For systematically growing objects, the equivalent
of a “table” is described and data is added one “row” at a time. It is assumed that the data does
not overlap in index space. These “row” structures are not assigned a uid attribute.

When this specification was issued, the following WITSML data objects were categorized
as growing objects
 trajectory (random)
 mudLog (random
 log (systematic)
 wellLog (systematic)
The special handling rules modify the standard behavior of Query and Subscription
templates, as well as the rules which determine what portions of these objects are eligible
for publication.

Page 120 of 147

WITSML Application Programming Interface

10.1 Randomly growing objects

In order for an object to qualify for special server behavior as a randomly growing object the
object must have the following characteristics.
1) In a non-recurring portion of the object (e.g., in a header) there must be one or more
pairs of elements that each represent a range of index values. Each pair must represent
a measure, a coordinate or a date-time value. These elements must represent the range
(i.e., minimum and maximum) of index values that exist in the substructures. That is, they
represent a structural range. Each individual element may represent concepts such as
start, end, minimum, maximum, top or bottom but the content of the pair must be able to
represent a minimum and maximum. For example, startMd and mdTop in mudLogs,
mdMn and mdMx in trajectory represent structural range elements.
2) Each recurring substructure(s) must contain element(s) representing a particular index
point or index interval that locates the each node in the index space. These index(es)
represent the node index More that one index space may be represented but, if so,
corresponding structural range elements must exist in the non-recurring area. This
substructure represents the data nodes. Example node indexes are, mdTop and
mdBottom in the mudLog’s parameter and geologyInterval, md in trajectoryStation, and
the index curve in log data. Example data nodes are (mudLog) parameter,
geologyInterval, trajectoryStation and (log) data.
3) The recurring substructure(s) must have a uid attribute to uniquely identify each node.
4) The schema must categorize the object as a randomly growing object and document the
above elements accordingly.
If an object conforms to the above characteristics, the behavior listed in the following subsections
must be supported by the server. It is the servers responsibility to under stand how a particular
schema fits the above characteristics.

Page 121 of 147

WITSML Application Programming Interface

10.2 Systematically Growing Objects

In order for an object to qualify for special server behavior as a systematically growing object the
object must have the following characteristics.
1) The object must represent a table or a set of tables.
2) In a non-recurring portion of the object (e.g., in a header) there must be one or more
pairs of elements that each represent a range of index values. Each pair must represent
a measure, a coordinate or a date-time value. These elements must represent the range
(i.e., minimum and maximum) of index values that exist in a single table. That is, they
represent a structural range. Each individual element may represent concepts such as
start, end, minimum, maximum, top or bottom but the content of the pair must be able to
represent a minimum and maximum. For example, startIndex and endIndex in logHeader
represent structural range elements.
3) If the object represents a set of (i.e., multiple) tables:
a. The above structural range elements must exist in the recurring structure that
describes each individual table. The recurring table definition structure must have
a uid attribute to uniquely identify each table.
b. In a non-recurring portion of the object (e.g., in a header) there may be one or
more pairs of elements that each represent an overall range of index values for
all tables. The overall range values represent the range of rows that actually exist
in the tables.
4) Each table must be assigned a recurring structure that represents a row in that table. This
structure represents the data nodes (i.e., rows). This recurring structure should not have
a uid attribute. The recurring row structure must contain a point value (i.e., not to a pair
representing an interval) in each indexing space. This value represents the node index.
Note that this value may be implicitly defined (e.g., via start and increment) or be
explicitly defined as a column. An example node index is the data value representing the
index curve in log data. An example data node is data in logData.
5) Each table definition structure must be assigned a recurring structure to describe each
column in the table. Each column should have a contextual column identifier (not a uid).
For example, mnemonic in logCurveInfo represents a column identifier. Each column may
have one or more pairs of elements that each represent an informative range of index
values for that column. The range values represent the range where values of that
column actually exist in the table. Null or empty values would be excluded from this
range. For example, startIndex and endIndex in logCurveInfo represents informative
range elements.
6) Each table may have an element to define the row count (number of rows) in the
persistent store. For example, dataRowCount in logHeader represents a row count
element.
7) The schema must categorize the object as a systematically growing object and document
the above elements accordingly.
If an object conforms to the above characteristics, the behavior listed in the following
subsections must be supported by the server. It is the servers responsibility to understand
how a particular schema fits the above characteristics.

Page 122 of 147

WITSML Application Programming Interface

10.3 STORE and PUBLISH behavior

The following STORE and PUBLISH behavior is available to qualified growing objects:
1) In a WMLS_GetFromStore template or a WMLP_Subscribe template:
a. For PUBLISH, information in the non-recurring header portion of a growing object
is eligible for publication if anything in the object has changed. Data nodes that
are new or have changed are eligible for publication but data nodes that have not
changed are not eligible for publication. The subscription template is only applied
to data that is eligible for publication.
b. If a structural range value is specified and data nodes are requested, the range
values are interpreted as meaning to include in the returned object all data nodes
where the node index values are at or within the index range.
i. For a point index, the data node will be included if the node index is
greater than or equal to the minimum range value and less than or equal
to the maximum range value.
ii. For an interval index, the data node will be included if the minimum node
index value is greater than or equal to the minimum range value and the
maximum node index value is less than or equal to the maximum range
value.
iii. If a minimum range value is specified and not a maximum range value,
all data nodes with a minimum or point node index value greater than or
equal to that minimum range value will be returned.
iv. If a maximum range value is specified and not a minimum range value,
all data nodes with a maximum or point node index value less than or
equal to that maximum range value will be returned.
v. The returned range values will match the range of the node index values
in the returned data nodes.
vi. If there are no data nodes within the specified index range, then nothing
will be returned for that query because not all criteria will have been met.
vii. As is true for all queries, if a node index value is to be returned then it
must be explicitly specified in the query. The selection of which data
nodes are to be returned is performed against the persisted index values
whether the index is specified in the query or not.
viii. For a randomly growing object, if a value is specified for a node index
element and a structural range value is also specified, the node index
value will be ignored. The node index element will be interpreted as a
normal query request for a value of that element.
ix. The structural range and column identifiers represent Cellular selection
criteria (i.e., which cells from a table) and they are AND’ed together. Any
other Cellular selection criteria (e.g., a specific data value or header
value) will also be AND’ed. The returned result set will contain only the
cells where all the Cellular Selection criteria are true. A row will not be
returned with all null values. If there are no non-null values for a column
within the specified range then nothing about that column will be
returned. The Cellular selection criteria are AND’ed with any Object
selection criteria.

Page 123 of 147

WITSML Application Programming Interface

c. If a structural range value is specified and data nodes are not requested, the
range values are interpreted as meaning to include in the returned object only
information about those columns which have non-null data within that range. That
is, no (header) information will be returned about columns which do not have
non-null data in that range. The result will be the same as when data nodes are
requested except that data nodes will not be returned.
d. If a structural range element is specified and data nodes are not returned
(whether data nodes are requested or not), the range values that are returned
will reflect the values in the persistent store.
e. If no structural range value is specified, standard query rules apply and all nodes
– regardless of index – will be returned assuming that they match any other
specified selection criteria.
f. For a systematically growing object, if an informative range element is specified:
i. If a value is specified, then it will be ignored.
ii. If no data nodes are returned then the server will return a value that
reflects the persistent data in the server.
iii. If data nodes are returned then the server will return a value that reflects
the returned nodes.
g. For a systematically growing object, if a value for the row count is specified then
the server will limit the resultant number of data nodes to a maximum of that
value. The returned value for the row count will be the number of rows in the
persistent store.
h. For a systematically growing object, if no column identifier is specified then the
server will interpret it as a request for all columns.
2) In a WMLS_UpdateInStore template for a systematically growing object:
a. If a structural range value is not specified the server will interpret it as a request
to append the data nodes. For the purpose of this section, “append” means to
add new data whose index is greater than the current maximum index.
b. If a structural range value is specified, the server will interpret it as a request to
replace any data nodes within that range. This is logically an “insert” if no data
exists within the specified range. The structural range value must match the
index range in the new data. This allows the server to replace the same data
regardless of whether it uses the structural range or the range in the data.
c. If a new column identifier and data nodes with values are specified then the
values will be added to existing data nodes and new data nodes will be added if
required. The only other column identifier that can be specified is the index
column. A structural range must not be specified with this option but its absence
does not imply append.
d. If informative range values are specified, they will be ignored.

Page 124 of 147

WITSML Application Programming Interface

3) In a WMLS_DeleteFromStore template,
a. For a randomly growing object, specifying the uid of data node will delete that
node. This is consistent with normal behavior.
b. For a systematically growing object , if a structural range value is specified
i. The server will interpret it as a request to delete all data nodes with a
node index that is greater than or equal to the minimum range value and
less than or equal to the maximum range value.
ii. Specifying only the minimum range value will delete all data nodes with a
node index value that is greater than or equal to the range value.
iii. Specifying only the maximum range value will delete all data nodes with
a data index value that is less than or equal to the range value.
c. For a systematically growing object , if a column identifier is specified then all
information associated with that column will be deleted. A structural range can be
specified with this option in order to delete a subset of a column.
4) The structural range, overall range, informative range and row count elements are
considered to be read-only elements and any request to update them will be ignored by
the server without an error being issued.
For all other functions the normal STORE rules apply. For example, use WMLS_UpdateInStore to
add a data node in a randomly growing object by specifying a node with a new uid value.

Page 125 of 147

WITSML Application Programming Interface

10.4 STORE Interface Examples

The special handling in the STORE interface for the trajectory, mudLog and log objects allows a
Query template to specify a range of recurring structures to be returned.
For all three objects, the range of recurring structures to be returned is indicated by specifying
values for specific, pre-determined index range data element(s) in the non-recurring ("header")
portion of the object. These values are then compared against specific, pre-determined index
data element(s) in the recurring portion of the object. If the data element(s) in the recurring
portion fall within the specified index range, that occurrence of the recurring structure is included
in the returned data object.
Object Range Specified By Recurring Compared To Field
Element(s) in Header Structure in Recurring Structure
example (see below) begin/end xxx index
mudLog startMd/endMd geologyInterval mdTop/mdBottom
log startIndex/endIndex (1) data (2) data value of the index
trajectory mdMn/mdMx trajectoryStation md
Notes:
1) startIndex/endIndex elements are in the logHeader. The elements
startDateTimeIndex and endDateTimeIndex are alternative indexes which are treated
similarly to startIndex and endIndex but have a different underlying type.
2) data structure is in the logData container
Example:
Persisted Data Object Query Template Returned Data Object
<example…> <example…> <example…>
<header_elements> <begin>950</begin> <begin>1000</begin>
… <end>4000</end> <end>3000</end>
<xxx> <xxx> <xxx>
<index>500</index> <index/> <index>1000</index>
… </xxx> </xxx>
</xxx> </example> <xxx>
<xxx> <index>3000</index>
<index>1000</index> </xxx>
… </example>
</xxx>
<xxx>
<index>3000</index>
…
</xxx>
</example>

Page 126 of 147

WITSML Application Programming Interface

10.4.1 trajectory Data Object Example

The trajectory data object contains recurring trajectoryStation structures:
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
…
<trajectoryStation … uid="34ht5">
…
</trajectoryStation> trajectory data object with
<trajectoryStation … uid="34ht6"> multiple trajectoryStation
… structures
</trajectoryStation>
…
</trajectory>
A Query can retrieve a range of trajectoryStations by specifying values for the minimum and
maximum measured-depth elements (mdMn and mdMx) of the trajectory object and by specifying
a single trajectoryStation element in the Query template, such as:
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<mdMn>3000</mdMn>
<mdMx>4000</mdMx>
… query template specifying a
<trajectoryStation … > depth range and a single
… trajectoryStation structure
</trajectoryStation>
</trajectory>

SPECIAL HANDLING SUMMARY - trajectory Data Object

The values for mdMn and mdMx are interpreted as meaning to include in the returned
trajectory object(s) all instances of the trajectoryStation structure where the measured
depth element (md) of the trajectoryStation structure is greater than or equal to mdMn and
less than or equal to mdMx.

Page 127 of 147

WITSML Application Programming Interface

If no value is specified for both the mdMn or mdMx elements, "standard" Query template handling
rules will apply, and all trajectory stations - regardless of depth - will be returned (assuming they
match any other specified selection criteria).
If a value is specified for mdMn and not for mdMx, all trajectoryStation occurrences with an md
value greater than or equal to mdMn will be returned. Likewise, if a value is specified for mdMx
and not for mdMn, all trajectoryStation occurrences with an md value less than or equal to mdMx
will be returned.
If there are no trajectoryStations with md values within the specified range of value(s) for
mdMn/mdMx, nothing will be returned because not all criteria will have been met
► As is true for Query templates in general, if the md element of the trajectoryStation structure is
to be returned, it must be explicitly specified in the Query:
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<mdMn>3000</mdMn>
<mdMx>4000</mdMx>
…
<trajectoryStation … > query template requesting that the md
<md/> data item be returned in the
</trajectoryStation> trajectoryStation structure(s)
…
</trajectory>
The selection of which trajectoryStation(s) are to be returned is performed against the persisted
md value(s), whether the md item is specified in the Query template or not.
If a value is specified in the trajectory for mdMn or mdMx, and a value is also specified in the
trajectoryStation for md, the value of md in the trajectoryStation will be ignored:
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<mdMn>3000</mdMn>
<mdMx>4000</mdMx>
…
<trajectoryStation …>
<md>5000</md> this value will be ignored
</trajectoryStation>
…
</trajectory>
The above query would return all trajectoryStation instances between 3000 and 4000 (inclusive).
The md element of the returned trajectoryStations will contain the persisted value for each.
Any values specified for an attribute or element of the trajectoryStation structure - other than the
md child element - are combined with the selection criteria specified by mdMn and mdMx. The
following example would return all trajectoryStations with mdDelta value of 10 within the 3000-
4000 depth range:
<trajectory uidWell="W-12" uidWellbore="B-01" uid="pe84e">
<mdMn>3000</mdMn>
<mdMx>4000</mdMx>
…
<trajectoryStation> criteria are combined
<mdDelta>10</mdDelta>
</trajectoryStation>
…
</trajectory>

Page 128 of 147

WITSML Application Programming Interface

10.4.2 mudLog Data Object Example

The mudLog data object contains recurring geologyInterval structures:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
…
<parameter>
…
</parameter >
<parameter>
…
</parameter > mudLog data object with
<geologyInterval> multiple parameter and
… geologyInterval structures
</geologyInterval>
<geologyInterval>
…
</geologyInterval>
…
</mudLog>
A Query template can retrieve a range of parameters and/or geologyIntervals by specifying
values for the start and end measured-depth elements (startMd and endMd) of the mudLog
object:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
<startMd>5010</startMd>
<endMd>5020</endMd>
… query template specifying a
<geologyInterval> depth range and a single
…
geologyInterval structure
</geologyInterval>
…
</mudLog>

SPECIAL HANDLING SUMMARY - mudLog Data Object

The values for startMd and endMd are interpreted as meaning to include in the returned
mudLog object(s) all instances of the parameter and geologyInterval structures where the
measured depth top element (mdTop) of the parameter or geologyInterval is greater than or
equal to startMd of the mudLog and the measured depth bottom element (mdBottom) of the
parameter or geologyInterval is less than or equal to endMd of the mudLog.

Page 129 of 147

WITSML Application Programming Interface

If no value is specified for both the startMd or endMd elements, "standard" Query template
handling rules will apply, and all parameter or geologyIntervals - regardless of depth - will be
returned (assuming they match any other specified selection criteria).
If a value is specified for startMd and not for endMd, all parameter or geologyInterval occurrences
with an mdTop value greater than or equal to startMd will be returned. Likewise, if a value is
specified for endMd and not for startMd, all parameter or geologyInterval occurrences with an
mdBottom value less than or equal to endMd will be returned.
If there are no parameter or geologyIntervals with mdTop/Bottom values within the specified
range of value(s) for startMd/endMd, nothing will be returned because not all criteria will have
been met.
► As is true for Query templates in general, if the mdTop and/or mdBottom elements of the
parameter or geologyInterval structure are to be returned, they must be specified:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
<startMd>5010</startMd>
<endMd>5020</endMd>
…
<geologyInterval> query template requesting that the mdTop
<mdTop/> and mdBottom data items are to be
<mdBottom/> returned in the geologyInterval structure(s)
</geologyInterval>
</mudLog>
The selection of which parameter(s) or geologyInterval(s) are to be returned is performed against
the persisted mdTop/mdBottom value(s), whether the mdTop/mdBottom item is specified in the
Query template or not.
If a value is specified in the mudLog for startMd or endMd, and a value is also specified in the
parameter or geologyInterval for mdTop/mdBottom, the value of mdTop/mdBottom in the
geologyInterval will be ignored:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
<startMd>5010</startMd>
<endMd>5520</endMd>
…
< parameter >
<mdTop>4000</mdTop> this value will be ignored
</parameter >
</mudLog>
The above query will return all the parameters between 5010 and 5520 (inclusive). The mdTop
element of the returned parameters will contain the persisted value for each.
Any values specified for an attribute or element of the parameter or geologyInterval structure -
other than the mdTop/mdBottom element described above - are combined with the selection
criteria specified by startMd and endMd. The following query would return the geologyIntervals
between 5010 and 5510 which have a dolomite value of 1:
<mudLog uidWell="W-12" uidWellbore="B-01" uid="h45a">
<startMd>5010</startMd>
<endMd>5510</endMd>
… criteria are combined
<geologyInterval>
<dolomite>1</dolomite>
</geologyInterval>
</mudLog>

Page 130 of 147

WITSML Application Programming Interface

10.4.3 log Data Object Example

Because the special handling required by the log object is somewhat more complex than the
other objects, we should first review the structure of the log object.
The log object can be logically divided into two sections: metadata about the log (logHeader
section) and the data for the curves (logData section).
XML Element Description
<log …>
<logHeader …> metadata section
<dataRowCount …> The number of data rows in the persistent log.
<indexType …> The kind of index curve.
<startIndex …> starting time/depth index for entire log
<endIndex …> ending time/depth index for entire log
<indexCurve …> name of curve which serves as index value
… additional child elements of logHeader
<logCurveInfo …> metadata about a curve
<startIndex …> starting time/depth index for this curve
<endIndex …> ending time/depth index for this curve
… additional child elements of logCurveInfo
</logCurveInfo>
… additional occurrences of logCurveInfo structure
</logHeader>
<logData …> data section
<data> data for all curves at this time/depth index
… additional occurrences of data element
</logData>
</log>

The logHeader section defines:

 How many data intervals are in the persistent store.
 How the log is indexed. Typically some sort of depth or a timestamp: the indexType element
 the start and end depth/time values for the entire log: startIndex and endIndex
 information about the log curves: one or more logCurveInfo elements, which in turn contain
start and end depth/time values for this particular curve (the startIndex and endIndex
elements), and, optionally, the string to be used to represent a null value for this log curve
 which curve serves as the indexing curve: indexCurve (the name of the curve that contains
the time or depth value with which the other data points are associated)
The logData section of the log object contains one or more <data> elements, each containing a
comma-delimited string value that contains the data points at a particular depth or time for all the
curves in the log.

Page 131 of 147

WITSML Application Programming Interface

Here is an example of a simplified log object containing four log curves: Mdepth, ROP, Bit RPM
and ECD.
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<dataRowCount>5</dataRowCount>
<indexType>measured depth</indexType> Metadata about
<startIndex>4050</startIndex> the entire log
<endIndex>4090</endIndex> (table)
<indexCurve>Mdepth</indexCurve>
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<startIndex>4050</startIndex>
<endIndex>4090</endIndex>
<columnIndex>1</columnIndex>
</logCurveInfo>
<logCurveInfo>
<mnemonic>ROP</mnemonic>
<startIndex>4050</startIndex>
<endIndex>4090</endIndex>
<columnIndex>2</columnIndex>
</logCurveInfo> Metadata about
<logCurveInfo> individual curves
<mnemonic>Bit RPM</mnemonic> (column heading)
<nullValue>-99999</nullValue>
<startIndex>4050</startIndex>
<endIndex>4070</endIndex>
<columnIndex>3</columnIndex>
</logCurveInfo>
<logCurveInfo>
<mnemonic>ECD</mnemonic>
<startIndex>4060</startIndex>
<endIndex>4090</endIndex>
<columnIndex>4</columnIndex>
</logCurveInfo>
</logHeader>
<logData>
<data>4050, 37.11, 93.74, </data>
<data>4060, 9.85, 95, 1.33</data>
Intervals
<data>4070, 32.44, 89.19, 1.31</data>
(rows)
<data>4080, 29.03, -99999, 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>
</logData>
</log>
Curves
(columns)

Page 132 of 147

WITSML Application Programming Interface

From dataRowCount we learn that the log has 5 data intervals. From the startIndex and endIndex
elements of the logHeader we can see that the entire log covers the range of 4050 thru 4090.
From the startIndex/endIndex elements of the four logCurveInfo elements, we see that the
Mdepth and ROP curves cover this same range. The Bit RPM curve, however, contains non-null
data only for 4050-4070 and the ECD curve contains non-null data only for 4060-4090.
The values for the four curves are stored in the log as four data points within each <data>
element - one data point for each curve. 7
…
<logData>
<data>4050, 37.11, 93.74, </data>
<data>4060, 9.85 95, 1.33</data>
<data>4070, 32.44, 89.19, 1.31</data> Intervals
<data>4080, 29.03, -99999, 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>
</logData>
</log>
Curves

Our four curves happen to have ascending <columnIndex> values (Mdepth =1, ROP = 2, etc),
and so the first “column” in the <data> element contains the Mdepth values (4050, 4060, etc)
followed by the ROP values in column 2 (37.11, 9.85, etc), the Bit RPM values in column 3 and
the ECD values in column 4.
If a log curve has no value at a particular depth or time, the value for that column in that <data>
element will be the value of the nullValue element specified for that curve or - if no nullValue is
specified, a null string.
For example, the Bit RPM curve specifies a value of -99999 for its nullValue element. Therefore,
the Bit RPM (3rd) column of the <data> element uses a value of -99999 for the fourth and fifth
intervals to indicate null values. However, since the nullValue element was not specified for the
other log curves, a null string (consecutive commas) will be used to indicate null values for all
other curves. This is the case with the ECD (4th) column, in which a null string is used to indicate
a null value for the first interval.
Viewed another way, the five example <data> elements convey the following data points for our
four curves:
Interval
#1 #2 #3 #4 #5
Mdepth 4050 4060 4070 4080 4090
ROP 37.11 9.85 32.44 29.03 13.09
Bit RPM 93.74 95 89.19 -99999 -99999
ECD null-string 1.33 1.31 1.32 1.34
One of the curves in a log must be designated as the “Index Curve”. If the log is depth-based, the
Index Curve will be the curve containing the depth at which the values were taken. If it is a time-
based log, the Index Curve will be the curve containing the time of the measurement.
Our example is a depth-based log, and Mdepth (curve/column #1) is the Index Curve, in feet.
Therefore, the data points represent values taken every ten feet from 4050 through 4090 feet.

7
additional spaces have been inserted into the example <data> elements to make the example more easily readable.

Spaces would not be present between numeric values in actual <data> elements.

Page 133 of 147

WITSML Application Programming Interface

10.4.3.1 Querying for Rows in a Systematically Growing Object

Now let us look at the special handling that allows a range of one or more rows to be queried in a
systematically growing object.
First, the column(s) to be returned are specified by including one or more column identifiers. For
the log object, this is the logCurveInfo elements, along with its child element <mnemonic>.
Second, at least one data node must be included. For the log object, this is the logData element
with its child element <data>. Specifying an empty data node will return all data nodes within the
structural range.
Third, the rows to be returned are specified by including a structural range. For the log object, this
is the elements startIndex and endIndex. If a row count value is specified then the server will limit
the resultant interval count to a maximum of that value. For the log object, the row count is
represented by the dataRowCount element.
► The structural range applies to all the columns specified in the query.
If there are no rows with node index values within the specified range of values for start index and
end index, nothing will be returned because not all criteria will have been met..

SPECIAL HANDLING SUMMARY - log Object (logData element present)

When a Query Template is received by the STORE interface for a log object, and if it contains
values for the startIndex and endIndex elements in the logHeader and the <logData> and
<data> elements are present, STORE will interpret this as meaning to return the data values
for all the specified log curves in the specified range(s). If a value for dataRowCount is
specified then the server will limit the resultant interval count to a maximum of that value.

Page 134 of 147

WITSML Application Programming Interface

To query the ROP and the Bit RPM curves in our example log object for data in the range of 4050
thru 4080 one would specify:
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<startIndex>4050</startIndex>
<endIndex>4080</endIndex>8 query template requesting
<logCurveInfo> the ROP and Bit RPM
<mnemonic>ROP</mnemonic> curves from 4050 through
</logCurveInfo> 4080
<logCurveInfo>
<mnemonic>Bit RPM</mnemonic>
</logCurveInfo>
</logHeader>
<logData>
<data/>
</logData>
</log>
If a query specifies values for the start/endIndex elements in the logCurveInfo element, those
values will be ignored:
<logHeader>
<startIndex>4050</startIndex> query template specifying
<endIndex>4080</endIndex> extraneous start/endIndex values
<logCurveInfo>
under logCurveInfo
<mnemonic>ROP</mnemonic>
<startIndex>4060</startIndex> [ignored]
<endIndex>4070</endIndex> [ignored]
</logCurveInfo>
…
The above query will be interpreted as if it had specified:
<logHeader>
<startIndex>4050</startIndex>
<endIndex>4080</endIndex>
<logCurveInfo>
<mnemonic>ROP</mnemonic>
<startIndex></startIndex>
<endIndex></endIndex>
</logCurveInfo>
…
Therefore, the server will return its persisted start/endIndex values for the ROP curve.

8
Since the Bit RPM curve in the example contains data only up to interval 4070, this query will
result in null values being returned for the Bit RPM curve in the intervals above 4070.

Page 135 of 147

WITSML Application Programming Interface

Here is another example query requesting the data for our example ROP and Bit RPM curves for
the interval range 4060-4100 (inclusive):
<log>
<logHeader>
<dataRowCount>3</dataRowCount>
<startIndex>4060</startIndex>
<endIndex>4100</endIndex>
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<startIndex></startIndex>
<endIndex></endIndex>
<columnIndex></columnIndex>
<nullValue></nullValue>
</logCurveInfo>
<logCurveInfo>
<mnemonic>Bit RPM</mnemonic>
<startIndex></startIndex>
<endIndex></endIndex>
<columnIndex></columnIndex>
<nullValue></nullValue>
</logCurveInfo>
</logCurveInfo>
<mnemonic>ECD</mnemonic>
<startIndex></startIndex>
<endIndex></endIndex>
<columnIndex></columnIndex>
<nullValue></nullValue>
</logCurveInfo>
</logHeader>
<logData>
<data>
</logData>
</log>
Let us now look at what would be returned by this query.
Recalling that our stored log object contains:
Mdepth Bit
RPM ECD
¯ ¯ ¯
<data>4050, 37.11, 93.74, </data>
<data>4060, 9.85, 95, 1.33</data>
<data>4070, 32.44, 89.19, 1.31</data>
<data>4080, 29.03, -99999, 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>
And we specified the range 4060 through 4100 for these three curves:
Mdepth RPM (curve/column #1 in the stored data)
Bit RPM (curve/column #3 in the stored data)
ECD (curve/column #4 in the stored data)

Page 136 of 147

WITSML Application Programming Interface

The returned document will contain:

<log>
<logHeader>
<dataRowCount>5</dataRowCount>
<startIndex>4060</startIndex>
<endIndex>4080</endIndex> A
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<nullValue/>
<startIndex>4060</startIndex>
<endIndex>4090</endIndex>
<columnIndex>1</columnIndex> B
</logCurveInfo>
<logCurveInfo>
<mnemonic>Bit RPM</mnemonic>
<nullValue>-99999</nullValue>
<startIndex>4060</startIndex>
<endIndex>4070</endIndex>
<columnIndex>2</columnIndex> B
</logCurveInfo>
<logCurveInfo>
<mnemonic>ECD</mnemonic>
<nullValue/>
<startIndex>4060</startIndex>
<endIndex>4090</endIndex>
<columnIndex>3</columnIndex> B
</logCurveInfo>
</logHeader>
<logData>
<data>4060, 95, 1.33</data>
<data>4070, 89.19, 1.31</data>
<data>4080, -99999, 1.32</data> A
</logData>
</log>
(the letters refer to the narrative on the next page)

Page 137 of 147

WITSML Application Programming Interface

Here is a discussion that explains why the query returned the results it did…
A - The start/endIndex values returned in the logHeader will encompass the range of values in
the returned curves (not necessarily the entire range of values in the persisted log, nor the range
of values that was requested in the query). In our example, we requested the range of 4060-
4100. However, none of the requested non-index curves contained data greater than interval
4090. Therefore, the values returned in the logHeader were adjusted to reflect the range actually
returned in the curves, in order to maintain the internal consistency of the returned log object.
Note also that the interval for index 4090 was not returned because a maximum of three intervals
was requested.
queried for: <logHeader>
<startIndex>4060</startIndex>
<endIndex>4100</endIndex>
returned: <logHeader>
<startIndex>4060</startIndex>
<endIndex>4080</endIndex> [adjusted]
B - While the Bit RPM curve data was persisted by the server as curve #3, and ECD data as
curve #4, these index values are only relative to the other curves stored with the log. They are
not absolute, unchanging values. For example, when the Bit RPM and ECD curves’ data values
are returned to the client, the curves will have been assigned new index numbers relative to the
other curves returned by that particular query. In our example, while the Bit RPM curve data was
originally stored as curve #3, it is returned as curve #2. Likewise, the ECD data was stored as
curve #4, but is returned as curve #3. The server adjusts the index values (<columnIndex>
element in the logCurveInfo headers) of the returned objects to reflect the column index within
the returned <data> elements. The client must use the returned columnIndex value in the
logCurveInfo from that particular query in order to properly interpret the returned <data>
elements.
The logCurveInfo section of the returned log object will also have been adjusted by the server to
reflect the actual position of the Index Curve in the returned <data> elements. Although shown as
columnIndex 1 in our examples, the Index Curve does not necessarily occupy columnIndex 1 in
the stored log or in the returned <data> elements.
We could request all curves by using an empty mnemonic. The following query would return the
entire contents of the log.
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<dataRowCount></dataRowCount>
<indexType></indexType>
<startIndex></startIndex>
<endIndex></endIndex>
<indexCurve></indexCurve>
<logCurveInfo>
<mnemonic></mnemonic>
<startIndex></startIndex>
<endIndex></endIndex>
<columnIndex></columnIndex>
</logCurveInfo>
</logHeader>
<logData>
<data></data>
</logData>
</log>

Page 138 of 147

WITSML Application Programming Interface

10.4.3.2 Updating Rows in a Systematically Growing Object

The general behavior for updating recurring elements that do not have a uid attribute is to replace
all occurrences with the elements in the query. However, an exception is made when updating
systematically growing components (e.g., logData). The behavior for updating rows in a
systematically growing object is to append the rows when start and end indexes are not specified
and to replace the rows when start or end index values are specified.
Thus, the following template:
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<columnIndex>1</columnIndex>
</logCurveInfo>
<logCurveInfo> Update adding one
<mnemonic>ROP</mnemonic> row in a particular
<columnIndex>2</columnIndex> log.
</logCurveInfo>
<logCurveInfo>
<mnemonic>ECD</mnemonic>
<columnIndex>3</columnIndex>
</logCurveInfo>
</logHeader>
<logData>
<data>5000,22.59,1.36</data>
</logData >
</log>
would result in the following data in the server: Note that mnemonic ‘Bit RPM’ was not specified in
the above template which resulted in an empty value being defined in the third column on the
server. An empty value is equivalent to a null value.
<data>4050, 37.11, 93.74, </data>
<data>4060, 9.85, 95, 1.33</data>
<data>4070, 32.44, 89.19, 1.31</data>
<data>4080, 29.03, -99999, 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>
<data>5000, 22.59, , 1.36</data>

Page 139 of 147

WITSML Application Programming Interface

While, the following template:

<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<startIndex>4075<startIndex>
<endIndex>4080<endIndex>
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<columnIndex>1</columnIndex>
</logCurveInfo>
<logCurveInfo>
<mnemonic>ROP</mnemonic>
<columnIndex>2</columnIndex>
</logCurveInfo> Update replacing
<logCurveInfo> one row in a
<mnemonic>Bit RPM</mnemonic> particular log.
<columnIndex>3</columnIndex>
</logCurveInfo>
<logCurveInfo>
<mnemonic>ECD</mnemonic>
<columnIndex>4</columnIndex>
</logCurveInfo>
</logHeader>
<logData>
<data>4080,29.03,87.4,1.32</data>
</logData >
</log>
will replace the row with an index of 4080 to result in the following data in the server:
<data>4050, 37.11, 93.74, </data>
<data>4060, 9.85, 95, 1.33</data>
<data>4070, 32.44, 89.19, 1.31</data>
<data>4080, 29.03, 87.4, 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>

SPECIAL HANDLING SUMMARY - Updating Rows

Updating rows in a systematically growing object without specifying start index or end index
will result in the rows being appended to the existing rows in the object.
Updating rows in a systematically growing object while specifying start index or end index will
result in the specified rows being replaced. A start index will request replacement of any row
with an index value greater than or equal to start index. An end index will request
replacement of any row with an index value less than or equal to end index.

Page 140 of 147

WITSML Application Programming Interface

10.4.3.3 Deleting Rows in a Systematically Growing Object

For a systematically growing object, special handling is allowed. Specifying a start index or an
end index in the header will result in the corresponding rows being deleted.
For example, the following template will delete all rows where the indexCurve value is greater
than or equal to 4060 and the indexCurve value is less than or equal to 4080.
<logs xmlns="http://www.witsml.org/schemas/120">
<log uidWell="W-12" uidWellbore="B-01" uid="f34a">
<logHeader>
<startIndex>4060</startIndex>
<endIndex>4080</endIndex>
</logHeader>
</log>
</logs>
And would result in the following being left on the server.
<data>4050, 37.11, 93.74, </data>
<data>4090, 13.09, -99999, 1.34</data>
The above example could be modified to only delete data for specific mnemonics. Thus,
<logs xmlns="http://www.witsml.org/schemas/120">
<log uidWell="W-12" uidWellbore="B-01" uid="f34a">
<logHeader>
<startIndex>4060</startIndex>
<endIndex>4080</endIndex>
<logCurveInfo>
<mnemonic>ROP</mnemonic>
</logCurveInfo>
<logCurveInfo>
<mnemonic>Bit RPM</mnemonic>
</logCurveInfo>
</logHeader>
</log>
</logs>
Would result in the following being left on the server.
<data>4050, 37.11, 93.74, </data>
<data>4060, , , 1.33</data>
<data>4070, , , 1.31</data>
<data>4080, , , 1.32</data>
<data>4090, 13.09, -99999, 1.34</data>
The index curve cannot be deleted unless the whole row is deleted. As shown in the first
example, if specific mnemonics had not been specified then the whole row would have been
deleted.
Specifying only startIndex will delete from (and including) that point to the end of the log.
Specifying only endIndex will delete from the beginning of the log to (and including) endIndex.
The startIndex and endIndex will be updated after the delete for all affected curves.

SPECIAL HANDLING SUMMARY - Deleting Rows

Specifying a start index or an end index in a systematically growing object will delete the
corresponding data.

Page 141 of 147

WITSML Application Programming Interface

10.4.3.4 Adding Columns in a Systematically Growing Object

The general behavior for updating an object with data that does not yet exist is to add the data.
Updating a systematically growing object with a new column also results in the data being added.
That is, there is no special behavior except that the row index must also be specified.
Thus, the following template:
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<logCurveInfo>
<mnemonic>Mdepth</mnemonic>
<columnIndex>1</columnIndex>
</logCurveInfo>
<logCurveInfo>
Update adding one
<mnemonic>HKLD</mnemonic>
<columnIndex>2</columnIndex> column to a
</logCurveInfo> particular log.
</logHeader>
<logData>
<data>4050,187.66</data>
<data>4060,185.74</data>
<data>4070,184.23</data>
<data>4080,185.49</data>
<data>4090,185.55</data>
</logData >
</log>
would result in the following data in the server
<data>4050, 37.11, 93.74, , 187.66</data>
<data>4060, 9.85, 95, 1.33, 185.74</data>
<data>4070, 32.44, 89.19, 1.31, 184.23</data>
<data>4080, 29.03, -99999, 1.32, 185.49</data>
<data>4090, 13.09, -99999, 1.34, 185.55</data>

SPECIAL HANDLING SUMMARY – Adding Columns

Updating a systematically growing object with a new column will result in the column
values being added in the appropriate rows.

Page 142 of 147

WITSML Application Programming Interface

10.4.3.5 Deleting Columns in a Systematically Growing Object

For a systematically growing object, special handling is allowed. Specifying a column identifier in
the header will result in the corresponding column being deleted.
Thus, the following template:
<log uidWell="W-12" uidWellbore="B-01" uid="L001">
<logHeader>
<logCurveInfo>
<mnemonic>ECD</mnemonic>
</logCurveInfo>
</logHeader>
</log>
would result in the following data in the server:
<data>4050, 37.11, 93.74</data>
<data>4060, 9.85, 95</data>
<data>4070, 32.44, 89.19</data>
<data>4080, 29.03, -99999</data>
<data>4090, 13.09, -99999</data>

SPECIAL HANDLING SUMMARY – Deleting Columns

Specifying a column identifier in the header will result in the corresponding column being
deleted.

Page 143 of 147

WITSML Application Programming Interface

10.5 PUBLISH Interface Example

Just as the STORE interface has special handling of Query Templates for the growing objects,
the PUBLISH interface also has special handling of Subscription Templates for these objects.
That is, a Subscription Template can - like a Query Template - specify a range of values that
determine which occurrences of a recurring structure are to be returned. A Subscription Template
for the log object, for example, can specify a begin and end depth and only the log data points
falling within that range will be published.
Both Query and Subscription Templates specify the type of object to be returned (well, wellbore,
etc), the data items to be returned (elements and attributes), which objects are to be returned (by
specifying a value of one or more data items) and - for those objects having special handling - the
range of recurring structure occurrences to be returned.
For the STORE interface, that is the extent of the "selection" process; the Query Template fully
specifies the object types, instances and contents to be returned.
And, for most data objects, the Subscription Template also fully specifies the object types and
contents to be sent to a Subscriber by the Publisher.
►However, for the growing objects, the PUBLISH interface also performs additional "eligibility"
processing prior to applying the Subscription Template.
As described in the section on Publishing, a Publisher considers an object to be "eligible" to be
sent to a Subscriber only when that object has changed (or been newly-added).
But some objects "grow" over time as additional occurrences of their recurring structures are
added (as additional trajectoryStations are added to a trajectory object, for instance), and thus the
Publisher might publish the entire object each time a new recurring structure was inserted!
To prevent this needless retransmission of data, the Publisher always considers the non-recurring
("header") data items of the log, mudLog and trajectory objects to be eligible for publication, but
only considers those instances of the recurring structure that are new or have been changed to
be eligible for publication.

Page 144 of 147

 WITSML Application Programming Interface

Here's a summary of the parts of growing objects that are eligible to be published, based on the
type of change:
Type of Change Eligible for Publication
new object all non-recurring data
and
all instances of recurring structure
update of non-recurring data all non-recurring data
add of new recurring data all non-recurring data
and
new instance(s) of recurring structure
update of existing recurring data all non-recurring data
and
updated instance(s) of recurring structure
Once the Publisher has determined which part of these objects are eligible for publication, it then
applies the Subscription Template to determine whether the Subscriber has requested this
particular object (and which portions of the object).

Parts
Changed Eligible for Parts to be
Object Publication Published

STEP 1 STEP 2

Based on type of change to Apply Subscription

the object, include only Template to determine
those portions that are what is to be sent to
eligible to be published. Subscriber(s)

Figure 8: Publishing Steps

►The Subscription Template is applied to the parts of the object that are eligible to be published
in the same way as a Query Template - including special handling.

Page 145 of 147

WITSML Application Programming Interface

11. APPENDIX F - Service Agreement

Whenever a WITSML service is setup between a WITSML service provider (provider) and a
WITSML service consumer (consumer) there are several aspects of the service that needs to be
further specified and agreed upon.
The WITSML standard only contains specifications about the data transport media, format,
protocol, data objects and their elements, and so the issues below are not part of the standard
itself.
In order for a WITSML service to be successfully setup, the provider and consumer also needs to
agree on these subjects:
 What WITSML interfaces should the provider supply?
 What WITSML API version is the server supporting?
 What version of the provider’s WITSML server should be provided?
 What character sets and encodings is the WITSML server able to handle in the incoming
WITSML requests (XML documents), and what kind of characters sets and encodings will
the server use in its answers to the WITSML clients?
 What data objects and data elements should the provider supply (not all WITSML data
elements are mandatory)?
 How should the mapping between provider and consumer names on curves etc be done?
 What default unit of measures should be used for the various data elements?
 What unit of measure conversions should be available for the various data elements?
 Security
o Should authentication be used?
o What protocol should be used, HTTP or HTTPS?
o Over what network should the service be run: Internet, VPN, or some other
closed network?
o If firewalls need to be opened for the service to run the IP addresses and ports of
the participating machines as well as the direction of connection initiation
between them should be specified.
 For how long should the service run?
 Quality of service
o For what period is the service available? 24/7?
o Is the service supported in that same period?
o E-mail and phone number of the provider support personnel or contact person.
o Is the service kept under surveillance? At what times?
 What is the IP address and URL to the WITSML server?

Page 146 of 147

Standards Document Title and Version

12. APPENDIX G - Custom Data

All the WITSML data objects include a container element named <customData> which can be used to extend
the WITSML data object definitions. While this is a useful feature, it can lead to the very interoperability
problems that WITSML was intended to prevent.
For the special case of <customData>, all sub-nodes will be returned if only the customData element is
specified. Querying sub-nodes of customData is server dependent.
The following recommendations are made in order to minimize problems across different implementations of
custom data.

12.1 Namespace
Custom data definitions should use a namespace URI different from the one used by WITSML
(http://www.witsml.org/schemas/nnn).
Here is a WITSML well object that uses the xmlns attribute to declare a custom namespace prefix of "cns"
associated with the URI http://www.my.org/schemas/100.
The object includes two custom data elements (cd1 and cd2) defined in that custom data namespace.
<?xml version="1.0" encoding="UTF-8"?>
<wells xmlns="http://www.witsml.org/schemas/140ex"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cns="http://www.my.org/schemas/100"> ç custom ns declaration
<well uid="W-1">
… WITSML-defined elements and attributes …
<customData>
<cns:cd1>value of cd1</cns:cd1>
<cns:cd2>value of cd2</cns:cd2>
</customData>
</well>
</wells>
Note that in this example the WITSML-defined elements and attributes do not require a namespace prefix,
since they use the default namespace declaration.

Page 147 of 147