RFC: A Little IDL
A Little IDL
I've been staring with incomprehension at various Interface Definition Languages (or IDLs) for XML-over-HTTP protocols, and wondering why they're so complicated. I thought it might have something to do with the kinds of languages and editing environments they're designed for. To find out where the disconnect is, I decided to define a simple interface definition language in XML that's suitable for scripting environments, and see if people find holes in its functionality, or if it's useful, or something we want to do. That's why I called this ALIDL, so no one could confuse it with the efforts of a standards body. It's little and human-readable. The goal is to have it work with scripting systems that are wired up to XML-RPC or SOAP 1.1.
Here's an example of an ALIDL file for an XML-RPC interface.
Here's an example of an ALIDL file for a SOAP 1.1 interface.
For reference, example SOAP and XML-RPC calls. These are the what ALIDL files describe, lots of calls that, at the TCP level, are HTTP requests encoded in XML.
What is an <alidl>?
<alidl> is an XML element, with one required attribute, version; an optional attribute, whenLastUpdated; and two required elements, <head> and <body>.
version is a string like 1.0.
whenLastUpdated is a string, like Mon, 05 Mar 2001 21:37:54 GMT.
What is a <head>?
<head> contains the elements described below. All elements are required.
<server> is a string, it's the domain name or IP address of the server whose interface is being described.
<port> is a number, it's the port that the server is running on.
<path> is a string, it's the path that an HTTP request is sent to to call a procedure described in the ALIDL document.
<protocol> is a string, either xml-rpc or soap, case-sensitive. It has an optional attribute, version, which indicates which version of the protocol is to be used to call the procedures. For xml-rpc, if version is specified it must be 1.0. For soap, the attribute is required and must be 1.1.
What is a <body>?
<body> contains zero or more <procedure>s.
What is a <procedure>?
<procedure> has two required attributes: name and ctParams; and one optional attribute, SOAPAction.
name is a string, it's the identifier for the procedure.
ctParams is a number, it says how many parameters the procedure takes.
SOAPAction is a string, used for SOAP 1.1 procedures, it provides the value for the SOAPAction header on the HTTP request.
A <procedure> may have <param> sub-elements, providing names and/or types for each of the parameters. If it has sub-elements it must have the exact number specified by the ctParams attribute.
What is a <param>?
<param> has two optional attributes, name and optional.
name is a string, it provides an identifier for the parameter.
optional is a string, either true or false, case-senstitive. If true the parameter is optional. If it's not specified the <param> is required.
3/6/01: Drop the returnedValueType attribute for <procedure>. Rename path attribute to SOAPAction. Drop the type attribute for <param>.
3/5/01: I considered a returnedValueType attribute for <procedure> and a type attribute for <param>, but there seems little in common in the type systems of XML-RPC and SOAP, so this remains an open question.
3/4/01: I considered allowing an optional <head> sub-element to specify the server software, but decided against it. That would make it possible for implementations to only work with a specific (set of) server(s). The goal is to have a format that hides implementation details and makes selective interop impossible.
Please post comments in this discussion group or on the XML-RPC mail list.