FOUNDATION FOR INTELLIGENT PHYSICAL AGENTS

 

 

FIPA Agent Message Transport Envelope Representation in XML Specification

 

Document title

FIPA Agent Message Transport Envelope Representation in XML Specification

Document number

SC00085J

Document source

FIPA TC Agent Management

Document status

Standard

Date of this status

2002/12/03

Supersedes

None

Contact

fab@fipa.org

Change history

See Informative Annex C — ChangeLog

 

 

 

 

 

 

 

 

 

 

© 1996-2002 Foundation for Intelligent Physical Agents
http://www.fipa.org/
Geneva, Switzerland     

Notice

Use of the technologies described in this specification may infringe patents, copyrights or other intellectual property rights of FIPA Members and non-members. Nothing in this specification should be construed as granting permission to use any of the technologies described. Anyone planning to make use of technology covered by the intellectual property rights of others should first obtain permission from the holder(s) of the rights. FIPA strongly encourages anyone implementing any part of this specification to determine first whether part(s) sought to be implemented are covered by the intellectual property of others, and, if so, to obtain appropriate licenses or other permission from the holder(s) of such intellectual property prior to implementation. This specification is subject to change without notice. Neither FIPA nor any of its Members accept any responsibility whatsoever for damages or liability, direct or consequential, which may result from the use of this specification.

Foreword

The Foundation for Intelligent Physical Agents (FIPA) is an international organisation that is dedicated to promoting the industry of intelligent agents by openly developing specifications supporting interoperability among agents and agent-based applications. This occurs through open collaboration among its member organisations, which are companies and universities that are active in the field of agents. FIPA makes the results of its activities available to all interested parties and intends to contribute its results to the appropriate formal standards bodies where appropriate.

The members of FIPA are individually and collectively committed to open competition in the development of agent-based applications, services and equipment. Membership in FIPA is open to any corporation and individual firm, partnership, governmental body or international organisation without restriction. In particular, members are not bound to implement or use specific agent-based standards, recommendations and FIPA specifications by virtue of their participation in FIPA.

The FIPA specifications are developed through direct involvement of the FIPA membership. The status of a specification can be either Preliminary, Experimental, Standard, Deprecated or Obsolete. More detail about the process of specification may be found in the FIPA Document Policy [f-out-00000] and the FIPA Specifications Policy [f-out-00003]. A complete overview of the FIPA specifications and their current status may be found on the FIPA Web site.

FIPA is a non-profit association registered in Geneva, Switzerland. As of June 2002, the 56 members of FIPA represented many countries worldwide. Further information about FIPA as an organisation, membership information, FIPA specifications and upcoming meetings may be found on the FIPA Web site at http://www.fipa.org/.

Contents

1     Scope. 1

2     XML Envelope Representation. 2

2.1      Component Name. 2

2.2      Mime Type. 2

2.3      Syntax. 2

2.4      Additional Syntax Rules. 3

2.5      Representation of Time. 4

3     References. 5

4     Informative Annex A — Examples. 6

5     Informative Annex B — Notes. 10

6     Informative Annex C — ChangeLog. 11

6.1      2002/11/01 - version I by TC X2S. 11

6.2      2002/12/03 - version J by FIPA Architecture Board. 11


1         Scope

This document deals with message transportation between inter-operating agents and also forms part of the FIPA Agent Management Specification [FIPA00023]. It contains specifications for:

 

·         Syntactic representations of a message envelope in XML form (see [W3Cxml]).

 


2         XML Envelope Representation

This section gives the concrete syntax for the message envelope specification that must be used to transport messages over a Message Transport Protocol (MTP - see [FIPA00067]). This concrete syntax is designed to complement [FIPA00071] and [FIPA00084].

 

2.1        Component Name

The name assigned to this component is:

 

fipa.mts.env.rep.xml.std

 

2.2        Mime Type

Where required, the MIME type (see [RFC2046]) of items generated according to this specification is taken to be application/xml. The charset encoding used in this section must conform to [W3Cxml].

 

2.3        Syntax

The following DTD specifies the encoding of the abstract FIPA specification as an XML message:

 

<!--

Document Type: XML DTD

Document Purpose: Encoding of FIPA ACL message envelopes (as in [FIPA0067]).

See http://www.fipa.org

Last Revised: 2000-08-16

-->

 

<!ELEMENT     envelope               ( params+ )>

 

<!ELEMENT     params                 ( to?,

                                      from?,

                                      comments?,

                                      acl-representation?,

                                      payload-length?,

                                      payload-encoding?,

                                      date?,

                                      encrypted?,

                                      intended-receiver?,

                                      received?,

                                      user-defined* )>

 

<!ATTLIST     params                  index CDATA #REQUIRED>

 

<!ELEMENT     to                     ( agent-identifier+ )>

 

<!ELEMENT     from                   ( agent-identifier )>

 

<!ELEMENT     acl-representation     ( #PCDATA )>

 

<!ELEMENT     comments               ( #PCDATA )>

 

<!ELEMENT     payload-length         ( #PCDATA )>

 

<!ELEMENT     payload-encoding       ( #PCDATA )>

 

<!ELEMENT     date                   ( #PCDATA )>

 

<!ELEMENT     intended-receiver      ( agent-identifier+ )>

 

 

<!ELEMENT     agent-identifier       ( name,

                                      addresses?,

                                      resolvers?,

                                      user-defined* )>

 

<!ELEMENT     name                   ( #PCDATA )>

 

<!ELEMENT     addresses              ( url+ )>

 

<!ELEMENT     url                    ( #PCDATA )>

 

<!ELEMENT     resolvers              ( agent-identifier+ )>

 

<!ELEMENT     received               ( received-by,

                                      received-from?,

                                      received-date,

                                      received-id?,

                                      received-via?,

                                      user-defined* )>

 

<!ELEMENT     received-by            ( url )>

 

<!ELEMENT     received-from          ( url )>

 

<!ELEMENT     received-date           EMPTY>

<!ATTLIST     received-date           value CDATA #IMPLIED>

 

<!ELEMENT     received-id             EMPTY>

<!ATTLIST     received-id             value CDATA #IMPLIED>

 

<!ELEMENT     received-via            EMPTY>

<!ATTLIST     received-via            value CDATA #IMPLIED>

 

<!ELEMENT     user-defined           ( #PCDATA )>

<!ATTLIST     user-defined            href CDATA #IMPLIED>

 

2.4        Additional Syntax Rules

The following additional rules not specified in the DTD also apply:

 

1.       [FIPA00067] requires that all changes made to a message envelope by one message processing step (for example, handling of the message by a single ACC) be attributable to the message processor that made the changes. This is achieved in the XML envelope by grouping all changes made by one message processor (ACC) at one point in time into a single PARAMS element.

 

2.       There is no need to add envelope parameter values to a new PARAMS element if the values of these parameters is not being updated. Only parameters whose value is being changed need be included. The meaning of a PARAMS statement containing two elements defining new values for the same envelope parameter is undefined.

 

3.       This specification permits multiple occurrences of unique message envelope-level parameters (to, from, intended-receiver, date, acl-representation, payload-length, received transport-behaviour, etc.) in order to handle field value overwriting as specified in [FIPA00067]. To help obtain the latest (and currently valid) value of any parameter, the INDEX attribute of the PARAMS element is used to establish an order of the different occurrences of elements (and hence envelope parameters). The first and oldest occurrence of the element will have an INDEX value of 1, the next value of the field will have INDEX value of 2 and so on.

 

4.       When adding a new PARAMS element, the INDEX attribute will have a value with 1 higher than the largest existing INDEX of any PARAMS element currently in the envelope. The first PARAMS element will have the INDEX value of 1.

 

5.       The current value of any envelope-level field will be given by the value of the field as it appears in the newest PARAMS element that contains that field.

 

6.       The following pseudo code algorithm may be used to obtain the latest values for each of the envelope parameters:

 

EnvelopeWithAllFields := new empty Envelope;

 

while ((EnvelopeWithAllFields does not contain values for all its fields)

        OR (all PARAMS elements in the sequence have been processed)) {

 // the processor gets the next envelope in the sequence starting with the one

 // with the highest index

 tempEnvelope = getNextEnvelope; 

 

 foreach field in an envelope {

   if ((this field has no value in envelopeWithAllFields)

       AND (this field has a value in tempEnvelope))

   then copy the value of this field from tempEnvelope to envelopeWithAllFields;

 }

}

 

EnvelopeWithAllFields contains now the latest values for all its fields set in the envelope.

 

7.       User-defined fields in the params, agent-identifier and received parameters must be prefixed with “X-”.

 

2.5        Representation of Time

Time tokens are based on [ISO8601], with extension for relative time and millisecond durations. Time expressions may be absolute, or relative. Relative times are distinguished by the sign character + or - appearing as the first character in the token. If no type designator is given, the local time zone is then used. The type designator for UTC is the character Z; UTC is preferred to prevent time zone ambiguities. Note that years must be encoded in four digits. As an example, 8:30 am on 15th April, 1996 local time would be encoded as:

 

19960415T083000000

 

The same time in UTC would be:

 

19960415T083000000Z

 

while one hour, 15 minutes and 35 milliseconds from now would be:

              
+00000000T011500035

 


3         References

[FIPA00023]      FIPA Agent Management Specification. Foundation for Intelligent Physical Agents, 2000. http://www.fipa.org/specs/fipa00023/

[FIPA00067]      FIPA Agent Message Transport Service Specification. Foundation for Intelligent Physical Agents, 2000. http://www.fipa.org/specs/fipa00067/

[FIPA00069]      FIPA ACL Message Representation in Bit-Efficient Encoding Specification. Foundation for Intelligent Physical Agents, 2000.

                        http://www.fipa.org/specs/fipa00069/

[FIPA00070]      FIPA ACL Message Representation in String Specification. Foundation for Intelligent Physical Agents, 2000.

                         http://www.fipa.org/specs/fipa00070/

[FIPA00071]      FIPA ACL Message Representation in XML Specification. Foundation for Intelligent Physical Agents, 2000.
http://www.fipa.org/specs/fipa00071/

[FIPA00075]      Agent Message Transport Protocol for IIOP. Foundation for Intelligent Physical Agents, 2000.
http://www.fipa.org/specs/fipa00075/

[FIPA00084]      FIPA Agent Message Transport Protocol for HTTP Specification. Foundation for Intelligent Physical Agents, 2000.
http://www.fipa.org/specs/fipa00084/

[ISO8601]         Date Elements and Interchange Formats, Information Interchange-Representation of Dates and Times. International Standards Organisation, 1998.
http://www.iso.ch/cate/d15903.html

[RFC2046]         Multipurpose Internet Mail Extensions (MIME) Part Two:  Media Types, Freed and Borenstein, November 1996.

                        http://www.rfc-editor.org/rfc/rfc2046.txt 

[W3Cxml]          Extensible Mark-up Language (XML) 1.0 Specification (Recommendation). World Wide Web Consortium, 1998.
http://www.w3c.org/TR/REC-xml/

 


4         Informative Annex A — Examples

1.       Here is a simple example of an envelope conforming to the DTD described in Section 2.3:

 

<?xml version="1.0"?>

<envelope>

  <params index="1">

    <to>

      <agent-identifier>

        <name>receiver@foo.com</name>

        <addresses>

          <url>http://foo.com/acc</url>

        </addresses>

      </agent-identifier>

    </to>

    <from>

      <agent-identifier>

        <name>sender@bar.com</name>

        <addresses>

          <url>http://bar.com/acc</url>

        </addresses>

      </agent-identifier>

    </from>

 

    <acl-representation>fipa.acl.rep.xml.std</acl-representation>

 

    <date>20000508T042651481</date>

 

    <received >

      <received-by value="http://foo.com/acc" />

      <received-date value="20000508T042651481" />

      <received-id value="123456789" />

    </received>

  </params>

</envelope>

 

2.       Here is an example which covers all the aspects described in Section 2.3:

 

<?xml version="1.0"?>

<envelope>

  <params index="1">

  <to>

    <agent-identifier>

      <name>receiver@foo.com</name>

      <addresses>

        <url>http://foo.com/acc</url>

      </addresses>

      <resolvers>

        <agent-identifier>

          <name>resolver@bar.com</name>

          <addresses>

            <url>http://bar.com/acc1</url>

            <url>http://://bar.com/acc2</url>

            <url>http://bar.com/acc3</url>

          </addresses>

        </agent-identifier>

      </resolvers>

    </agent-identifier>

  </to>

 

  <from>

    <agent-identifier>

      <name>sender@bar.com</name>

      <addresses>

        <url>http://bar.com/acc</url>

      </addresses>

      <resolvers>

        <agent-identifier>

          <name>resolver@foobar.com</name>

          <addresses>

            <url>http://foobar.com/acc1</url>

            <url>http://foobar.com/acc2</url>

            <url>http://foobar.com/acc3</url>

          </addresses>

        </agent-identifier>

      </resolvers>

    </agent-identifier>

  </from>

 

  <comments>No comments!</comments>

 

  <acl-representation>fipa.acl.rep.xml.std</acl-representation>

 

  <payload-encoding>US-ASCII</payload-encoding>

 

  <date>20000508T042651481</date>

 

  <intended-receiver>

    <agent-identifier>

      <name>intendedreceiver@foobar.com</name>

      <addresses>

        <url>http://foobar.com/acc1</url>

        <url>http://foobar.com/acc2</url>

        <url>http://foobar.com/acc3</url>

      </addresses>

      <resolvers>

        <agent-identifier>

          <name>resolver@foobar.com</name>

          <addresses>

            <url>http://foobar.com/acc1</url>

            <url>http://foobar.com/acc2</url>

            <url>http://foobar.com/acc3</url>

          </addresses>

          <resolvers>

            <agent-identifier>

              <name>resolver@foobar.com</name>

              <addresses>

                <url>http://foobar.com/acc1</url>

                <url>http://foobar.com/acc2</url>

                <url>http://foobar.com/acc3</url>

              </addresses>      

            </agent-identifier>

          </resolvers>

        </agent-identifier>

      </resolvers>

    </agent-identifier>

  </intended-receiver>

 

  <received>

    <received-by value="http://foo.com/acc" />

    <received-from value="http://foobar.com/acc" />

    <received-date value="20000508T042651481" />

    <received-id value="123456789" />

    <received-via value="http://bar.com/acc" />

  </received>

  </params>

</envelope>

 

3.       Here is an example which also includes the MIME multipart encapsulation which might be used over HTTP (see [FIPA00084]):

 

MIME-Version: 1.0

Content-Type: multipart-mixed ;

boundary=”--251D738450A171593A1583EB”

 

This is not part of the MIME multipart encoded  message.

--251D738450A171593A1583EB

Content-Type: application/xml

 

<?xml version="1.0"?>

<envelope>

  <params index="1">

    <to>

      <agent-identifier>

        <name>receiver@foo.com</name>

        <addresses>

          <url>http://foo.com/acc</url>

        </addresses>

      </agent-identifier>

    </to>

    <from>

      <agent-identifier>

        <name>sender@bar.com</name>

        <addresses>

          <url>http://bar.com/acc</url>

        </addresses>

      </agent-identifier>

    </from>

 

    <acl-representation>fipa.acl.rep.string.std</acl-representation>

 

    <payload-encoding>US-ASCII</payload-encoding>

 

    <date>20000508T042651481</date>

 

    <received >

      <received-by value="http://foo.com/acc" />

      <received-date value="20000508T042651481" />

      <received-id value="123456789" />

    </received>

  </params>

</envelope>[1]

[2]

--251D738450A171593A1583EB

Content-Type: application/text; charset=US-ASCII

 

(inform

  :sender

    (agent-identifier

      :name sender@bar.com

      :addresses (sequence http://bar.com:80/acc))

  :receiver

    (set (agent-identifier

      :name receiver@foo.com

      :addresses (sequence http://foo.com:80/acc ))))

  :content-length 12

  :reply-with task1-003

  :language fipa-sl0

  :ontology planning-ontology-1

  :content “
    (done task1)”)

--251D738450A171593A1583EB—

 


5         Informative Annex B — Notes

1.       Referencing

There is no specific reference in the FIPA XML envelope reference to the DTD specified in the in Section 2.3. This is due to the fact that tests have shown that there is no consistent behaviour of most common parser in handling a DOCTYPE specification. The most inconvenient fact is that even in the case of non-validation the parsers are trying to download the DTD from the specified URI.

 


6         Informative Annex C — ChangeLog

6.1        2002/11/01 - version I by TC X2S

Entire document:              Removed all : from parameter names

Entire document:              Corrected examples

Entire document:            Removed all references to the encrypted parameter

Page 2, line 90:               Extended params definition to allow user-defined fields

Page 3, line 115:             Extended agent-identifier definition to allow user-defined fields

Page 3, line 130:             Extended received definition to allow user-defined fields

Page 3, lines 132-133:     Changed type of received-by to url

Page 3, lines 135-136:     Changed type of received-from to url

Page 4, line 190:              Added a rule for prefix string for user-defined fields

Page 4, line 191:             Fixed the definition of relative time

 

6.2        2002/12/03 - version J by FIPA Architecture Board

Entire document:              Promoted to Standard status

 



[1] CRLF at the end of the XML Envelope.

[2] CRLF included in the boundary delimiter at the beginning.