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. |