ERCOT Participant Interface: XML
May 21, 2003
Revision 1.154
Transmittal No.:
Revision History
Revision / Transmittal # / Date / Comments1.0 / 551E0022 / June, 2000 / Original [Phil Hystad]
1.1 / 551E0034 / July, 2000 / Revision [Phil Hystad] Incorporating suggested changes and missing information resulting from review discussion of June 28th, 2000.
1.2 / 551E0049 / July, 2000 / Revision [Phil Hystad] Incorporating changes from review discussions on July 13th and updating to make XML interface coincident with MUI where applicable for common and shared data.
1.3 / 551E0061 / July, 2000 / Revision [Phil Hystad] Incorporating changes reported by Sam Brattini during phone conversation on July 25th, 2000. Also added Query request for congestion notices and market-clearing prices query per the request by David Cantrell (AC) on behalf of ERCOT reviewers who noticed this particular difference between the Web U/I and the XML interface.
1.4 / August, 2000 / Revision [Phil Hystad] Changes to add description of participant user identification as requested by design closure issues list.
1.5 / 551Exxxx / December, 2000 / Revision [Phil Hystad] Incorporating changes reflecting as-built of pre-fat testing. This revision contains many fixes to minor problems as well as new items not previously documented but required. Also, description and usage notes have been significantly expanded.
1.6 / 551E0210 / March 16, 2001 / Revision [ Phil Hystad] AS-BUILT for post-SAT update reflecting changes resulting from variance discovery and agreed upon enhancements and design changes. This is a preliminary release and reflects SIR fixes submitted by March 14th.
1.7 / 551E0218 / June 4, 2001 / Revision [Phil Hystad] AS-BUILT for post Mock Market update reflecting changes made during and immediately following mock market. These changes are operational for Market Pilot beginning June 6th, 2001.
1.8 / 551E0229 / September 21, 2001 / Revision [Phil Hystad]. Project completion AS-BUILT revision inclusive of all approved changes post market testing and acceptance as per the start of warranty.
1.9 / 551E0291 / November 28, 2001 / Revision [Phil Hystad]. Start of Phase II work. The changes in this revision incorporate the changes due to PIP 279.
1.91 / Internal Document / October 8, 2002 / Revision [Tom Barton] Added queries and examples for Area Load Forecasts, Total Transfer Capability, and Weather Assumptions.
1.92 / Internal Document / October 16, 2002 / Revision [Tom Barton] Added queries and examples from 10/8 revision to internal list; minor edits and punctuation review.
1.10 / April 29, 2002 / Revision [Phil Hystad]. Update to reflect the changes for BUILD 3 that is inclusive of the functions identified in PIP 147, PIP 148+X4, and X5.
1.11 / November 1, 2002 / Revision [Avnaesh Jayantilal]. Update to reflect the changes for PR 20142.
1.12 / December 22, 2002 / Merged versions 1.92 and 1.11 [Gary Barlich} & PIP 150
1.13 / January 21, 2003 / Changed Adjusted Schedule to Schedule Adjustment [Gary Barlich]
1.14 / February 7, 2003 / Minor corrections in Schedule Adjustment Notification. Corrected Balancing Bid example. [Jim Rector & Gary Barlich]
1.15 / April 17, 2003 / Updated Balancing Bid and Balancing deployment to include BULBES and LAARBES specific features. Added page numbers to the bottom of pages. Removed Outage Schedules as they were never implemented. Fixed Balancing Bid example.
Table of Contents
ERCOT Participant Interface: XML
1 Introduction
1.1 Purpose
1.2 Related Documents and Technology Prerequisite Knowledge
1.3 Document Description
1.4 Terminology
2 Common Principles
2.1 Public and Private Data
2.2 Participant Authentication and Identifiers
2.2.1 Participant Registration......
2.2.2 Participant Authentication......
2.2.3 Participant Identifiers......
2.3 Request/Reply and Push (Asynchronous Messages)
2.4 XML
2.4.1 About XML......
2.4.2 XML Coding Conventions......
2.5 Message Partitioning and MIME
2.6 Message Header
2.6.1 Header Description......
2.6.2 Header DTD......
2.7 URL
2.8 Message Transport
2.9 Data Payload
2.9.1 Data Payload DTD......
2.9.2 Data Description......
2.9.3 Data Payload Example......
2.10 Optional and Default Data Handling
2.11 Replacing and Deleting Data
2.12 Response and Acknowledgement Messages
2.12.1 RESPONSE-ACK......
2.12.2 RESPONSE-NAK......
2.12.3 RESPONSE-ACK-DATA......
2.13 Constructing Message for Sending
2.14 Interpretation of Message Received
3 Service Bid Submittal
3.1 Common Principles of Service Bids
3.1.1 URL, Command, and Subject......
3.1.2 Data Payload DTD......
3.1.3 Response Message......
3.2 Ancillary Service (A/S) Bid
3.2.1 Description......
3.2.2 Data Payload DTD......
3.2.3 Data Description......
3.2.4 Example......
3.3 Balancing-Energy Service Bid
3.3.1 Description......
3.3.2 Data Payload DTD......
3.3.3 Data Description......
3.3.4 Examples......
3.3.4.2 BULBES Bid
3.4 Replacement Capacity Service Bid
3.4.1 Description......
3.4.2 Data Payload DTD......
3.4.3 Data Description......
3.4.4 Example......
4 Submitting Schedules and Plans
4.1 Common Principles of Schedules and Plans
4.1.1 URL, Command, and Subject......
4.1.2 Data Payload DTD......
4.1.3 Response Message......
4.2 Balanced Bilateral Schedule
4.2.1 Description......
4.2.2 Data Payload DTD......
4.2.3 Data Description......
4.2.4 Example......
4.3 Resource Plan
4.3.1 Description......
4.3.2 Data Payload DTD......
4.3.3 Data Description......
4.3.4 Example......
5 Notifications and A/S Deployment Instructions
5.1 Common Principles of Notifications and A/S Deployment Instructions
5.1.1 URL, Command, and Subject......
5.1.2 Data Payload DTD......
5.1.3 Response Message......
5.2 Deployment Instruction
5.2.1 Description......
Regulation Deployment
Responsive Reserve Deployment
Non-spinning Reserve Deployment
Replacement Capacity Deployment
Balancing-Energy Deployment
RMR energy Deployment
OOME Deployment
OOMC Deployment
5.2.2 Data Payload DTD......
5.2.3 Data Description......
5.2.4 Example......
5.3 Ancillary Service (A/S) Obligation Notification
5.3.1 Description......
5.3.2 Data Payload DTD......
5.3.3 Data Description......
5.3.4 Example......
5.4 Congestion Notification
5.4.1 Description......
5.4.2 Data Payload DTD......
5.4.3 Data Description......
5.4.4 Example......
5.5 Emergency Condition Notification
5.5.1 Description......
5.5.2 Data Payload DTD......
5.5.3 Data Description......
5.5.4 Example......
5.6 Down-Balancing Energy Percent Requirement Notification
5.6.1 Description......
5.6.2 Data Payload DTD......
5.6.3 Data Description......
5.6.4 Example......
5.7 Resource Plan Invalid Notification
5.7.1 Description......
5.7.2 Data Payload DTD......
5.7.3 Data Description......
5.7.4 Example......
5.8 Market A/S Capacity Clearing Price Notification
5.8.1 Description......
5.8.2 Data Payload DTD......
5.8.3 Data Description......
5.8.4 Example......
5.9 Market Schedule Notification
5.9.1 Description......
5.9.2 Data Payload DTD......
5.9.3 Data Description......
5.9.4 Example......
5.10 Schedule Mismatch Notification
5.10.1 Description......
5.10.2 Data Payload DTD......
5.10.3 Data Description......
5.10.4 Example......
5.11 Selected A/S Bids Notification
5.11.1 Description......
5.11.2 Data Payload DTD......
5.11.3 Data Description......
5.11.4 Example......
5.12 Selected Replacement Capacity Bids Notification
5.12.1 Description......
5.12.2 Data Payload DTD......
5.12.3 Data Description......
5.12.4 Example......
5.13 Schedule Adjustment Notification
5.13.1 Description......
5.13.2 Data Payload DTD......
5.13.3 Data Description......
5.13.4 Example......
6 Query Messages
6.1 Common Principles of Query Messages
6.1.1 Description......
6.1.2 URL, Command, and Subject......
6.1.3 Query Request Data Payload DTD......
6.1.4 Query Request Data Description......
6.1.5 Response DTD......
6.2 Query for A/S Requests
6.2.1 Description......
6.2.2 Response DTD......
6.2.3 Response Data Description......
6.2.4 Example......
6.3 Query for A/S Obligations
6.3.1 Description......
6.3.2 Response DTD......
6.3.3 Response Data Description......
6.3.4 Example......
6.4 Query for Area Load Forecasts (ALF)
6.4.1 Description......
6.4.2 Response DTD......
6.4.3 Response Data Description......
6.4.4 Example......
6.5 Query for Commercially Significant Constraints (CSC)
6.5.1 Description......
6.5.2 Response DTD......
6.5.3 Response Data Description......
6.5.4 Example......
6.6 Query for Congestion Notices
6.6.1 Description......
6.6.2 Response DTD......
6.6.3 Response Data Description......
6.6.4 Example......
6.7 Query for Emergency Notifications
6.7.1 Description......
6.7.2 Response DTD......
6.7.3 Response Data Description......
6.7.4 Example......
6.8 Query for Down-Balancing Energy Percent Requirement
6.8.1 Description......
6.8.2 Response DTD......
6.8.3 Response Data Description......
6.8.4 Example......
6.9 Query for Frequency Control Data
6.9.1 Description......
6.9.2 Response DTD......
6.9.3 Response Data Description......
6.9.4 Example......
6.10 Query for Generation Outages
6.10.1 Description......
6.10.2 Response DTD......
6.10.3 Response Data Description......
6.10.4 Example......
6.11 Query for Market Schedule
6.11.1 Description......
6.11.2 Response Data Payload DTD......
6.11.3 Data Description......
6.11.4 Example......
6.12 Query for A/S Capacity Market-clearing Prices
6.12.1 Description......
6.12.2 Response Data Payload DTD......
6.12.3 Data Description......
6.12.4 Example......
6.13 Query for Replacement Capacity and Balancing-Energy Market-clearing Prices
6.13.1 Description......
6.13.2 Response Data Payload DTD......
6.13.3 Data Description......
6.13.4 Example......
6.14 Query for Midterm-Load Forecast
6.14.1 Description......
6.14.2 Response Data Payload DTD......
6.14.3 Response Data Description......
6.14.4 Example......
6.15 Query for Schedule Mismatch Messages
6.15.1 Description......
6.15.2 Response Data Payload DTD......
6.15.3 Response Data Description......
6.15.4 Example......
6.16 Query for Short-term Load Forecast
6.17 Query for System Losses
6.17.1 Description......
6.17.2 Response Data Payload DTD......
6.17.3 Response Data Description......
6.17.4 Example......
6.18 Query for Total Transfer Capability (TTC)
6.18.1 Description......
6.18.2 Response Data Payload DTD......
6.18.3 Response Data Description......
6.18.4 Example......
6.19 Query for Approved Transmission Outages
6.19.1 Description......
6.19.2 Response DTD......
6.19.3 Response Data Description......
6.19.4 Example......
6.20 Query for Weather Assumptions
6.20.1 Description......
6.20.2 Response Data Payload DTD......
6.20.3 Response Data Description......
6.20.4 Example......
6.21 Query for Weather Forecast
6.21.1 Description......
6.21.2 Response Data Payload DTD......
6.21.3 Response Data Description......
6.21.4 Example......
7 Appendix: DTD Notation
8 Appendix: Data-types
8.1 About Data-types and Semantic-types
8.2 Semantic-types
8.2.1 Participant ID......
8.2.2 Resource ID......
8.2.3 Zone ID......
8.2.4 Time Interval......
8.2.5 Price......
8.3 Basic Data-types
8.3.1 Null......
8.3.2 Character String......
8.3.3 Integer......
8.3.4 Floating-point......
8.3.5 Numeric......
8.3.6 Boolean......
8.3.7 Date......
8.3.8 Time......
9 Appendix: Errors
1
1 Introduction
1.1 Purpose
This document describes the participant’s XML-based programmatic interface to the ERCOT Market System.
The participant uses this document for guidance in the formulation of messages to be sent to the market system, and the interpretation of messages received from the market system. This document describes the addressing, exchange protocol, data, and XML formulation for all defined MOS messages.
The reader of this document is assumed to be a software engineer whose intent is to understand the requirements of the participant’s interface to the market system, and to implement the software necessary to exchange data with the market system. Data exchange requirements vary from one participant to another but examples include the following:
- Query market database for operational data such as load forecast, weather forecast, balancing-energy clearing prices, etc.
- Submit balanced schedules.
- Submit bids into one or more of the markets opened by ERCOT.
- Receive deployment instructions from ERCOT.
1.2 Related Documents and Technology Prerequisite Knowledge
In order to design and implement the participant software interface to ERCOT using the programmatic API, the reader should be familiar with:
- ERCOT Programmatic Interface Specification.
- ERCOT Security Interface Specification.
- Using XML for data description, DTD interpretation, and XML parsing and validation.
- Protocols HTTP, HTTPS, and TCP/IP.
- Security and authentication technologies: encryption, use of digital certificates, authentication, and SSL (secure sockets layer).
- General network communication software methodology.
1.3 Document Description
This document is divided into Chapters specific to the kinds of messages that are sent and received. Participants do not need to implement support for all message-types – only those message-types that are required.
Each chapter is organized in a similar fashion, describing required addressing, commands, and other required data according to the following template:
- Description of message.
- URL that receives the message.
- Header command that describes the action to be performed.
- Message data payload DTD.
- Message data description.
- Response acknowledgement message.
- Message example.
1.4 Terminology
The following terms and acronyms are used by this document.
ACK – acronym for acknowledgement, indicating a normal and successful acknowledgement message. Contrast with NAK.
Asynchronous –operation independent of any timing mechanism or sequence of events, such as an ordered sequence of messages. In this specification, the term ‘asynchronous’ is synonymous with push-style messaging where the message is pushed by ERCOT to the participant, who is actively listening for asynchronous messages. The term ‘asynchronous’ assumes that the receiver is a participant. Contrast asynchronous with ‘request/reply’.
CRLF – acronym meaning Carriage Return Line Feed; the definition of a line terminator. A line is a contiguous set of octets (8-bit characters) that is terminated by a CRLF character. The CRLF character is often platform-dependent, and may be defined as the hex codes 0x0D, 0x0A or simply as the hex code 0x0A. The usage of 0x0D, 0x0A two-character couplet is standard for Windows platforms (e.g. Windows NT). The usage of 0x0D, single-character, is standard for many Unix platforms. The CRLF can be created using language features for generating a new-line character such as the C escape character \n.
Character Data –the XML term that defines the non-markup data that exists between an XML start and end tag. For example, given a start and end tag of UNITMW, the character data in the following example is the number 400.0: <UNITMW>400.0</UNITMW>.
DTD – acronym meaning Document Type Definition, defined by the XML specification as the statements that describe the elements, attributes, and entities that comprise an XML document. The XML specification defines three distinct types of DTDs: internal, external, and public. An internal DTD is embedded as part of the XML document. An external DTD is declared by the SYSTEM keyword and is located using a URL. A public DTD is declared by the PUBLIC keyword, and is located by a URI describing a public resource. This specification uses the external DTD only.
Digital Certificate –packet encoding that defines a public key to be used with public key encryption, detailed information about the owner of the digital certificate, expiration date of digital certificate, and other optional data. Digital certificates are used to authenticate all parties (ERCOT and participants) that use the programmatic interface. Digital certificates are also used to establish the secure connection between the participant and ERCOT. The secure connection is made using the SSL protocol. Encryption and digital certificates and how they are used by the programmatic interface are described in the document ERCOT Programmatic Interface Specification.
First-Normal-Form –the specification that character data defined by XML start and end tags (see definition of character data in this terminology section) represents a single data item. Data that does not fit the First-Normal-Form definition is data that includes sets of information, repeating groups, or structured elements. For the purposes of this specification, Date and Time data is considered to be First-Normal-Form data, even though it defines sets of information (e.g. month, day, year, hour, minute).
HTTP – acronym meaning Hyper-text Transfer Protocol. HTTP is an application-level protocol for distributed, collaborative, hypermedia, information systems. More simply, HTTP is a network communications protocol used to send and receive data over the Internet. The version of HTTP used by this specification is 1.1, often referred to as HTTP/1.1. The HTTP/1.1 protocol is defined by RFC 2616.
HTTPS – acronym meaning Hyper-text Transfer Protocol Secure. HTTPS is a secure protocol where the security is established by SSL (see terminology entry). HTTPS does not define nor does it add new communications features to HTTP; it is merely a secure version of HTTP. The HTTPS name is used to specify the protocol in the URL declaration to identify it as being secured by SSL.
IETF – acronym meaning Internet Engineering Task Force, the body whose members work together to define, specify, and regulate the various standards used for Internet network communications. The RFCs referenced by this specification are defined and maintained by the IETF. The IETF web site can be consulted for more information:
ISO – acronym with two different, unrelated, meanings used in this specification. ISO, on one hand, means Independent System Operator; this usage of the term represents the kind of organization and operations center established by ERCOT. The other definition for ISO is International Standards Organization, the standards body responsible for a number of international standards used implicitly and explicitly in this document. Explicit ISO standards cited by this specification include ISO-8601, used to define Date and Time standards and conventions; and, ISO-8859-1, used to define the XML operative character set.
MIME – acronym meaning Multipurpose Internet Mail Extensions. MIME is a standard originally developed for sending multi-part data using textual e-mail. However, MIME is used in the broader Internet community for sending multi-part data in other text message systems such as HTTP. MIME allows a single message to be divided into multiple parts so that the parts can either be treated separately or together as dictated by the MIME application type. MIME is a very flexible standard and is used in just a restricted fashion by this specification to define a multi-part related message so that multiple XML documents can be sent and received using a single message. MIME, as used in this specification, is defined by RFCs: 2045, 2046, 2047, and 2112.
MOS – acronym meaning Market Operations System, which is the ERCOT application system that establishes and operates various markets of electricity-born products. All messages and data specified by this document interface to the MOS only.
Multipart-Related –the MIME application type used by this interface specification to encode multiple XML documents into a single message. The Multipart-Related MIME application type is defined by RFC 2112.
NAK –the acronym meaning ‘Negative AcKnowledgement’, the opposite of the ACK acronym. NAK is given when a network communications message is rejected or not processed completely. Push Messaging –a messaging style where a message is sent, asynchronously, to a receiver, who must be actively listening for such messages. ERCOT uses push messaging to send deployment instructions and market notification messages to participants. Contrast this with request/reply messaging. In this specification, push messaging is synonymous with asynchronous messaging – see asynchronous in this terminology section.
RFC – acronym meaning Request For Comments. The RFC is the documentation method used by the IETF for developing and documenting network communications standards for the Internet community. Several network communications standards cited by this specification are defined by RFCs. Each RFC is numbered. For a complete list of RFCs, and to obtain copies of RFCs, see the information located at the IETF web site:
Request/Reply –a messaging style in which a client sends a request message to a server and the server responds with a reply message. Request/Reply is also sometimes called ‘Client-Server’ messaging. For purposes of this document, the participant is always the client who initiates the request, and ERCOT is the server that responds with a reply. Contrast ‘Request/Reply’ with ‘Push Messaging’ (a/k/a asynchronous).
SSL – acronym meaning Secure Sockets Layer. SSL is a protocol standard used to establish a secure, encrypted connection between a given client and server. SSL Version 3.0 is the protocol used for establishing the secure communications between participants and ERCOT. SSL is an industry de-facto standard developed originally by the Netscape Corporation. More information on the definition and use of SSL by ERCOT can be found in the document ERCOT Programmatic Interface Specification.