All information from a KBMS to the WFB is in the form of XML-like statements. Data from the WFB to the KBMS may be in XML or LISP format, as described below.
Please send comments on the protocol to Micheal Hewett (hewett@cs.utexas.edu).
1. Definition of a WFB Server 2. WFB Data Formats 3. Contacting a WFB server 3.1 WFB Services Protocol 4. WFB Request Protocol 5. KBMS Response Protocol 6. Default port numbers 7. Reference Implementations 7.1 WFB 7.1.1 Common LISP 7.2 KBMS backend 7.2.1 Common LISP A.1 Summary of Tokens
A WFB server also has a pass-through mode where it can simply pass on the response from the KR server without generating HTML. In this mode, the WFB can act as an "object broker" or, more appropriately, a "frame broker" among various systems.
<GET-SLOT-VALUE FRAME="DOGS" SLOT="NUMBER-OF-LEGS">
In LISP mode, a GET-SLOT-VALUE command is formatted as shown below:
(:GET-SLOT-VALUE :FRAME "DOGS" :SLOT "NUMBER-OF-LEGS")All symbols are uppercase keywords to avoid package problems. All values are strings.
In order to be compatible with both Common LISP and Scheme back-ends, the WFB will never send the symbols T or NIL. Boolean values will instead be the strings "true" and "false".
<BEGIN-SERVICE name="service-name" type="service-type" host="hostname" port="port-number" description="Text description of the service" supported="WFB-operation" ... unsupported="WFB-operation" ... protocol="XML"|"LISP" public="true"|"false" >What about multiple KBs supported over the same port?
In response, the WFB returns either a PASSWORD
message (indicating success) or a WFB-ERROR
message with a description of the problem.
3.1.2. PASSWORD
<PASSWORD value="some-password"> or (:PASSWORD :VALUE "some-password")In response to a BEGIN-SERVICE message, the WFB will normally return a PASSWORD message (indicating success). The KBMS must use the password to terminate the service. In addition, if the KB is not public the password must be used to access the KB for the duration of the current session.
<END-SERVICE name="service-name" password="password">The KBMS sends the END-SERVICE message to indicate that the service is no longer available. The message must contain the same service-name sent in the original message, as well as password returned by the WFB when the service was initiated.
The WFB will also end the service whenever it detects that the connection to the KBMS has been lost.
<GET-ALL-FRAMES> or (:GET-ALL-FRAMES)The WFB sends this message to request a list of every frame in the KB. The KBMS should return a LIST of FRAME tokens, such as:
<RESPONSE> <FRAME name="Dog"></FRAME> <FRAME name="Cat"></FRAME> <FRAME name="Turtle"></FRAME> </RESPONSE>
<GET-KB-STATISTICS> or (:GET-KB-STATISTICS)The WFB sends this message to request a set of statistics about the KB. The KBMS should reply with a set of VALUE tokens. The values contain the number of instances of different types, such as frames, slots, relations, rules, etc. For example:
<RESPONSE> <VALUE name="Frames">42614</VALUE> <VALUE name="Slots">57</VALUE> <VALUE name="Relations">1141910</VALUE> </RESPONSE>
<SEARCH value="text" exact="true"|"false" > or (:SEARCH :VALUE "text" :EXACT "true"|"false")The WFB sends this message to request that a search of the KB be performed for the given text string. If EXACT is true, only components which exactly match the string should be returned. Otherwise, the KBMS may perform a partial match of the text string against the component names. Matching is assumed to be case-insensitive.
Normally, this message is used to retrieve a set of frame names that match the given string. The KBMS may return the names of frames, or other components.
An example:
<SEARCH value="horse" exact="false"> <RESPONSE> <FRAME name="Horses"></FRAME> <FRAME name="Seahorses"></FRAME> <SLOT name="Jockey-of-Horse"></SLOT> </RESPONSE>
<GET-FACET name="facet-name"> or (:GET-FACET :NAME "facet-name")The WFB sends this message to request a meta-level description of a facet. In response, the KBMS should return a FACET-INFO message, i.e.:
<RESPONSE> <FACET-INFO name="facet-name"> <STRING>The facet Bar is used internally to store rules.</STRING> </FACET-INFO> </RESPONSE>
<GET-FRAME name="frame-name"> or (:GET-FRAME :NAME "frame-name")The WFB sends this message to request fairly complete information about a frame. Normally, the KBMS returns the set of slots and values that comprise the frame. Depending on the setting of various parameters, the KBMS may choose not to display some slots (i.e. those that contain internal KBMS information).
<GET-FRAME-SLOTS frame="frame-name"> or (:GET-FRAME-SLOTS :FRAME "frame-name")The WFB sends this message to request a list of the slots belonging to a specific frame. The KBMS returns the requested slot names, without values.
<RESPONSE> <SLOT name="NAME"></SLOT> <SLOT name="BIRTH-DATE"></SLOT> <SLOT name="HEIGHT"></SLOT> <SLOT name="WEIGHT"></SLOT> </RESPONSE>
<GET-SLOT name="slot-name"> or (:GET-SLOT :NAME "slot-name")The WFB sends this message to request a meta-level description of a slot. In response, the KBMS should return a SLOT-INFO message, i.e.:
<RESPONSE> <SLOT-INFO name="slot-name"><STRING>The slot Foo has domains (Dogs, Food, Time).</STRING></SLOT-INFO> </RESPONSE>
<GET-SLOT-VALUE frame="frame-name" slot="slot-name" [facet="facet-name"]> or (:GET-SLOT-VALUE :FRAME "frame-name" :SLOT "slot-name" [:FACET "facet-name"])The WFB sends this message to request the value of a specific slot of a frame. If the KBMS supports facets, the message should contain a facet-name. If it doesn't, the KBMS should assume the default facet, one which normally indicates a positive value. The KBMS should respond with the value or values (if the slot has multiple cardinality):
<RESPONSE> <VALUE>7.33</VALUE> <VALUE>5.17</VALUE> <VALUE>6.07</VALUE> </RESPONSE> or <RESPONSE> <VALUE> <LIST> "Animals" 3.5 "Zanzibar"</LIST> </VALUE> </RESPONSE>
<NEW-FRAME name="frame-name"> or (:NEW-FRAME :NAME "frame-name")The WFB sends this message to request that a new frame be created with the given name. Note that subtype or subclass information for the frame must be sent separately in the form of slot information.
<NEW-SLOT name="slot-name" domains="domain1 domain2 domain3 ..." cardinality="number"> or (:NEW-SLOT :NAME "slot-name" :DOMAINS "domain1 domain2 domain3 ..." :CARDINALITY "number")The WFB sends this message to request that a new slot be created. This is a slot class or slot type, not a specific instance of a slot on a frame. Example:
<NEW-SLOT name="birth-date" domains="Living-Things Calendar-Dates" cardinality="1">
<NEW-FACET name="facet-name"> or (:NEW-FACET :NAME "facet-name")The WFB sends this message to request that a new facet be created. This is a facet class or facet type, not a specific instance of a facet on a slot.
<SET-SLOT-VALUE frame="frame-name" slot="slot-name" [facet="facet-name"] value="value"> or (:SET-SLOT-VALUE :FRAME "frame-name" :SLOT "slot-name" :FACET "facet-name" :VALUE "value")The WFB sends this message to store a value on a slot. If the KBMS supports facets, a facet name will also be included.
<IS-FRAME name="frame-name"> or (:IS-FRAME :NAME "frame-name")The WFB sends this message to query whether a frame with the given name exists in the KB. The KBMS should respond with either a true or false VALUE
<RESPONSE> <VALUE>true</VALUE> </RESPONSE>
<IS-SLOT name="slot-name"> or (:IS-SLOT :NAME "slot-name")The WFB sends this message to query whether a slot with the given name exists in the KB. The KBMS should respond with either a true or false VALUE
<RESPONSE> <VALUE>true</VALUE> </RESPONSE>
<IS-FACET name="facet-name"> or (:IS-FACET :NAME "facet-name")The WFB sends this message to query whether a facet with the given name exists in the KB. The KBMS should respond with either a true or false VALUE
<RESPONSE> <VALUE>true</VALUE> </RESPONSE>
<IS-RULE name="rule-name"> or (:IS-RULE :NAME "rule-name")The WFB sends this message to query whether a rule with the given name exists in the KB. The KBMS should respond with either a true or false VALUE
<RESPONSE> <VALUE>true</VALUE> </RESPONSE>
<GET-PARAMETER parameter="parameter-name"> or (:GET-PARAMETER :PARAMETER "parameter-name")The WFB will not send this message, but it may be sent by another system using the pass-through port on the WFB. It retrieves a parameter value from the KBMS.
<RESPONSE> <PARAMETER name="parameter" value="value"> </RESPONSE>
<PARAMETER name="parameter-name" value="value">The KBMS sends this message in response to a GET-PARAMETER message from a third-party source. Example:
<RESPONSE> <PARAMETER name="parameter" value="value"> </RESPONSE>
<SET-PARAMETER parameter="parameter-name" value="value"> or (:SET-PARAMETER :PARAMETER "parameter-name" :VALUE "value")The KBMS sends this message to set a parameter in the WFB.
<KB any-parameter="value" ...> or (:KB :ANY-PARAMETER "value")The WFB will never generate this message, but it may be passed along by another program through the pass-through port. The KBMS must interpret this command - the WFB has no idea of its semantic meaning. This can be used to pass information outside of the WFB frame-slot model. Example:
<KB use-partition="snail-taxonomy">
<WFB-ERROR value="error description"> or (:WFB-ERROR :VALUE "error description")The WFB sends this message to request a list
<RESPONSE> ... </RESPONSE>Each response from the KBMS must be enclosed in a <RESPONSE> </RESPONSE> pair.
<FACET name="facet-name"> ... </FACET>The KBMS sends this to indicate that FACET information follows. If the KBMS uses facets, this usually indicates that VALUE tokens will follow.
<FACET-INFO name="facet-name"> ... </FACET-INFO>The KBMS uses this form in response to a GET-FACET message. The contents are used to display a message to the user regarding the facet.
<FRAME name="frame-name"> ... </FRAME>The KBMS uses this form to indicate that information about a frame follows. The KBMS usually presents SLOT and VALUE information between the opening and closing FRAME tokens.
<RULE> ... </RULE>The KBMS uses this form to indicate that information about a frame follows. The KBMS usually presents SLOT and VALUE information between the opening and closing RULE tokens. The WFB will give a special interpretation to the slots DIRECTION, ANTECEDENT, CONSEQUENT and DESCRIPTION. Other slots will be displayed as for a normal frame.
DIRECTION can be "forward" or "backward".
5.1.5. SLOT
<SLOT name="slot-name"> ... </SLOT>The KBMS uses this form to indicate that slot information follows. THE KBMS usually sends FACET and/or VALUE information between the opening and closing SLOT tokens.
<SLOT-INFO> ... </SLOT-INFO>The KBMS uses this form to indicate that informational text describing a slot is to follow. This describes the slot at a meta-level, perhaps including its domains, a descriptive string, or its cardinality. It does not normally describe the contents of the slot on a specific frame.
<VALUE [name="value-name"]> ... </VALUE>The KBMS uses this form to indicate that a value, usually the value of a slot, is to follow. The VALUE form is also used to return a value in response to a predicate such as IS-FRAME.
<ARRAY [length="array-length"]> ... </ARRAY>This form indicates that an array is being transmitted. The contents of the array may be all of one type, or of different types, as in a LISP list. Specifying the array length is optional.
<BOOLEAN> ... </BOOLEAN>This form indicates that a boolean value is being transmitted. The contents should be either the string
true
or false
. Character case is
not important.
<FLOAT> ... </FLOAT>This form indicates that a floating-point number is being transmitted. The value of the number may be of any precision, and may be in scientific notation.
<HTML> ... </HTML>This form indicates that HTML code is being sent. The HTML code should be inserted into the output at the point in the output stream corresponding to this point in the input stream.
A KBMS may use this to send an active link as
the value of a frame-slot.
5.2.5. INTEGER
<INTEGER [base="base"]> ... </INTEGER>This form indicates that an integral number is being transmitted. The value of the integer may be of any precision, and may be in scientific notation.
Using the base
parameter allows
hex strings to be passed, for example to transmit
color values. The base
value is always
in base 10.
5.2.6. LIST
<LIST> ... </LIST>This form indicates that a LIST is being sent. The internal construction of a LIST is exactly the same as defined in Common LISP.
<NOTE> ... </NOTE>This form indicates a notation that should be displayed on the screen in addition to the other information being sent. Notes are usually displayed at the bottom of the screen (like a footnote) or in a separate display. The text between the NOTE and /NOTE tokens forms the note.
<OBJECT> ... </OBJECT>This form indicates that an OBJECT (which may correspond to a structure, record or class instance in a regular programming language) is being transmitted. The receiver must be able to interpret the meaning of the object contents, which are undefined.
<STRING> ... </STRING>This form indicates that a text string is being transmitted. The text may contain any characters. The < and " characters may be escaped with a backslash ("\"), although HTML character escape sequences are preferred.
<URL> ... </URL>This form indicates that a special kind of string, namely a URL, is being transmitted.
<KB-ERROR command="command" value="error description">The KBMS uses this form to indicate that an error occurred during execution of a request. If the WFB receives this message, the error description will be displayed on the screen in an appropriate format.
<UNSUPPORTED command="command">The KBMS uses this form to indicate that it can not perform the requested command.
Message | From | Format(s) | Section | Description | |
---|---|---|---|---|---|
ARRAY | KBMS | <ARRAY [length="array-length"]> ... </ARRAY> |
Data Types | Values between the open and close ARRAY tokens specify the contents of the array. Specifying the array length is optional. | |
BEGIN-SERVICE | KBMS | <BEGIN-SERVICE name="service-name" type="service-type" host="hostname" port="port-number" description="Text description of the service" supported="WFB-operation" ... unsupported="WFB-operation" ... protocol="XML"|"LISP" public="true"|"false" > |
Services | Initiates a session between a KBMS and a WFB server. | |
BOOLEAN | KBMS | <BOOLEAN> |
Data Types | Case-insensitive. | |
END-SERVICE | KBMS |
<END-SERVICE name="service-name" password="password"> |
Services | Ends a session between a KBMS and a WFB server. | |
FACET | KBMS | <FACET name="facet-name"> ... <FACET> |
Responses | Usually contains VALUE forms between the open and close FACET tokens. | |
FACET-INFO | KBMS | <FACET-INFO name="facet-name"> ... </FACET-INFO> |
Responses | A user-oriented description of a facet. This is produced in response to a GET-FACET message. | |
FLOAT | KBMS | <FLOAT> ... </FLOAT> |
Data Types | Transmits a floating-point number in decimal or scientific notation. | |
FRAME | KBMS | <FRAME name="frame-name"> ... </FRAME> |
Responses | The contents contain information about a specific frame, usually using SLOT forms. | |
GET-ALL-FRAMES | WFB | <GET-ALL-FRAMES> |
Requests | Requests that the KBMS return a list of every frame in the KB. This usually means frame names only, not frame contents. | |
GET-FACET | WFB | <GET-FACET name="facet-name"> |
Requests | Requests meta-level information about a facet, usually for display to a human user. | |
GET-FRAME | WFB | <GET-FRAME name="frame-name"> |
Requests | This message requests the contents of a frame. | |
GET-FRAME-SLOTS | WFB | <GET-FRAME-SLOTS frame="frame-name"> |
Requests | This message requests a list of every slot currently instantiated on the given frame instance. | |
GET-KB-STATISTICS | WFB | <GET-KB-STATISTICS> |
Requests | Requests a count of various components in the KB, such as frames, relations (slot-values), etc. The KBMS can return any message, although VALUE forms are suggested. | |
GET-PARAMETER | External | <GET-PARAMETER parameter="parameter-name"> |
Requests | The WFB may forward this through a pass-through port. The requestor is asking for the value of a specific parameter in the KBMS. | |
GET-SLOT | WFB | <GET-SLOT name="slot-name"> |
Requests | Requests meta-level information about a slot, usually for display to a human user. | |
GET-SLOT-VALUE | WFB | <GET-SLOT-VALUE frame="frame-name" slot="slot-name" [facet="facet-name"]> |
Requests | This message requests the value of a specific slot (and facet, if supported). | |
HTML | KBMS | <HTML> ... </HTML> |
Data Types | The contents contain HTML code, which the receiver will normally use without modification. | |
INTEGER | KBMS | <INTEGER [base="base"]> ... </INTEGER> |
Data Types | Transmits an integer value in any base. Default base is 10. The value may be in scientific notation. | |
IS-FACET | WFB | <IS-FACET name="facet-name"> |
Requests | This message requests a boolean response indicating whether the given name is the name of a defined facet in the KBMS. | |
IS-FRAME | WFB | <IS-FRAME name="frame-name"> |
Requests | This message requests a boolean response indicating whether the given name is the name of a defined frame in the KBMS. | |
IS-RULE | WFB | <IS-rule name="rule-name"> |
Requests | This message requests a boolean response indicating whether the given name is the name of a defined rule in the KBMS. | |
IS-SLOT | WFB | <IS-SLOT name="slot-name"> |
Requests | This message requests a boolean response indicating whether the given name is the name of a defined slot in the KBMS. | |
KB | external | <KB parameter="value"> |
Requests | This message passes some undefined information to the KBMS. The sender and receiver must define the contents. The WFB will never generate this message and will not understand the contents. | |
KB-ERROR | KBMS | <KB-ERROR command="command" value="error description"> |
Responses | The KBMS generates this message to indicate that an error was generated while processing the given command. | |
LIST | KBMS | <LIST> ... </LIST> |
Data Types | This message indicates that the contents of a LIST (corresponding to
the Common LISP LIST data structure) are being
transmitted. | |
NEW-FACET | WFB | <NEW-FACET name="facet-name"> |
Requests | This message requests the KBMS to create a new facet with the given name. | |
NEW-FRAME | WFB | <NEW-FRAME name="frame-name"> |
Requests | This message requests the KBMS to create a new frame with the given name. | |
NEW-SLOT | WFB | <NEW-SLOT name="slot-name"> |
Requests | This message requests the KBMS to create a new slot with the given name. | |
NOTE | KBMS | <NOTE> ... </NOTE> |
Data Types | This message indicates a note, or ancillary information, that is attached to a response. The receiver should display the NOTE in a footnote position, or in a special display. | |
OBJECT | KBMS | <OBJECT> ... </OBJECT> |
Data Types | Transmits an object (structure, record, class instance, ...). The receiver must understand the contents. | xyz|
PARAMETER | KBMS | <PARAMETER name="parameter-name" value="value"> |
Responses | This message is transmitted in response to a GET-PARAMETER message. | |
PASSWORD | WFB | <PASSWORD value="some-password"> or (:PASSWORD :VALUE "some-password") |
Services | Used by the KBMS to end a service or by the user to access a private KB. | |
RESPONSE | KBMS | <RESPONSE> ... </RESPONSE> |
Responses | The KBMS must begin and end any response to a message with the RESPONSE token. This is so the receiving agent can know when the message begins and ends. | |
RULE | KBMS | <RULE name="rule-name"> ... </RULE> |
Responses | The contents contain information about a specific rule, usually using SLOT forms. The slots antecedent, consequent, direction and description are given special handling by the WFB. | |
SEARCH | WFB | <SEARCH value="text" exact="true"|"false"> |
Requests | The KBMS is requested to perform a search for items containing the given string. The items may be frames, slots, facets, values or other forms. | |
SET-PARAMETER | WFB | <SET-PARAMETER |
Requests | The WFB may forward this through a pass-through port. The requestor is asking the KBMS to set the value of a specific parameter in the KBMS. The KBMS should reply with an appropriate NOTE or KB-ERROR. | |
SET-SLOT-VALUE | WFB | <SET-SLOT-VALUE |
Requests | The KBMS is requested to set the value of the frame-slot to the specified value. If the KBMS supports facets, the message should contain a facet parameter. If it doesn't, the KBMS should use its default facet, usually the one corresponding to a positive value. | |
SLOT | KBMS | <SLOT name="slot-name"> ... </SLOT> |
Responses | The contents contain information about a slot, usually FACET and/or VALUE forms. | |
SLOT-INFO | KBMS | <SLOT-INFO name="slot-name"> ... </SLOT-INFO> |
Responses | A user-oriented description of a slot. This is produced in response to a GET-SLOT message. | |
STRING | KBMS | <STRING> ... </STRING> |
Data Types | Indicates that a text string is being transmitted. | |
UNSUPPORTED | KBMS | <UNSUPPORTED command="command"> |
Responses | Indicates that the KBMS does not support the command indicated in the command parameter. This message is sent in response to a specific command. Use the BEGIN-SERVICE command to indicate that a KBMS does not generally support a command. | |
URL | KBMS | <URL> ... </URL> |
Data Types | Indicates that a URL is being transmitted. | |
VALUE | KBMS | <VALUE [name="value-name"]> ... </VALUE> |
Responses | Transmitted in response to a GET-SLOT-VALUE or a GET-KB-STATISTICS message. | |
WFB-ERROR | WFB | <WFB-ERROR value="error description"> |
Responses | Transmitted by the WFB, usually to indicate that it could not understand a given message. The receiver should understand the message and make appropriate changes. When this message is transmitted in reply to a specific response from a KBMS, such as in response to a GET-SLOT-VALUE message, the original message will be repeated, up to three times total. The KBMS should not send a new value in response to the error message, but should wait for the new request from the WFB. |