Chapter 9 - Cisco CRS-1 Series XML Schema Versioning

Table Of Contents

Cisco CRS-1 Series XML Schema Versioning

Major and Minor Version Numbers

Run-Time Use of Version Information

Placement of Version Information

Version Lag

Version Creep

Retrieving Version Information

Cisco CRS-1 Series XML Schema Versioning

Before the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) can carry out a client application request, it must verify version compatibility between the client request and router component versions.

A major and minor version number are carried on the <Request> and <Response> elements to indicate the overall Cisco CRS-1 Series extensible markup language (XML) application programming interface (API) version in use by the client application and router. In addition, each component XML schema exposed through the Cisco CRS-1 Series XML API has a major and minor version number associated with it.

Note The XML API code is available for use on any Cisco platform that runs Cisco IOS XR software.

This chapter describes the format of the version information exchanged between the client application and the Cisco CRS-1 Series router, and how the Cisco CRS-1 Series router uses this information at run time to check version compatibility.

The following sections are included:

• Major and Minor Version Numbers

• Run-Time Use of Version Information

• Retrieving Version Information

Major and Minor Version Numbers

The top-level or root object (that is, element) in each component XML schema carries the major and minor version numbers for that schema. A minor version change is defined as an addition to the XML schema. All other changes, including deletions and semantic changes, are considered major version changes.

The version numbers are documented in the header comment contained in the XML schema file. They are also available as <xsd:appinfo> annotations included as part of the complex type definition for the top-level schema element. This enables you to programmatically extract the version numbers from the XML schema file to include in XML request instances sent to the router. The version numbers are carried in the XML instances using the MajorVersion and MinorVersion attributes.

The following example shows the relevant portion of the complex type definition for an element that carries version information:

<xsd:complexType name="ipv4_bgp_cfg_BGP_type">
  <xsd:annotation>
    <xsd:documentation>Global BGP config</xsd:documentation>
    <xsd:appinfo>
      <MajorVersion>1</MajorVersion>
      <MinorVersion>0</MinorVersion>
      <TaskIdInfo TaskGrouping="Single">
        <TaskName>bgp</TaskName>
      </TaskIdInfo>
    </xsd:appinfo>
  </xsd:annotation>
            .
            .
            .
  <xsd:attributeGroup ref="VersionAttributeGroup"/>
            .
            .
            ..
</xsd:complexType>

The attribute group VersionAttributeGroup is defined as follows:

<xsd:attributeGroup name="VersionAttributeGroup">
  <xsd:annotation>
    <xsd:documentation>
      Common version information attributes
    </xsd:documentation>
  </xsd:annotation>
  <xsd:attribute name="MajorVersion" type="xsd:unsignedInt" use="required"/>
  <xsd:attribute name="MinorVersion" type="xsd:unsignedInt" use="required"/>
</xsd:attributeGroup>

Run-Time Use of Version Information

Each XML request must contain the client's major and minor version numbers at the appropriate locations in the XML. These version numbers are compared to the version numbers running on the router. The request is then accepted or rejected based on the following rules:

•If there is a major version discrepancy, then the request fails.

•If there is a minor version lag, that is, the client minor version is behind that of the router, then the request is attempted.

•If there is a minor version creep, that is, the client minor version is ahead of that of the router, then the request fails.

•If the version information has not been included in the request, then the request fails.

Each XML response can also contain the version numbers at the appropriate locations in the XML.

Note If the client minor version is behind that of the router, then the response may contain elements that are not recognized by the client application. The client application must be able to handle these additional elements.

Placement of Version Information

The following example shows the placement of the MajorVersion and MinorVersion attributes within a client request to retrieve the global BGP configuration data for a specified autonomous system:

Sample Client Request Showing Placement of Version Information

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global/>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Request>
Sample Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            .
            .
            .
              data returned here
            .
            .
            .
          </Global>
        <AS>
      </BGP>
    </Configuration>
  <Get>
</Response>
Version Lag

The following example shows a request and response with a version mismatch. In this case, the client minor version is behind that of the router, so the request is attempted.

Note The version number, which is returned in the response, is the version number running on the router.

Sample XML Client Request with a Version Mismatch

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global/>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0" IteratorID="1">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="1">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            .
            .
            .
              data returned here
            .
            .
            .
          </Global>
        <AS>
      </BGP>
    </Configuration>
  <Get>
</Response>
Version Creep

The following example shows a request and response with a version mismatch. In this case, the client minor version is ahead of that of the router minor version, resulting in an error response.

Sample XML Request with a Minor Version Mismatch Ahead of the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="1"/>
    </Configuration>
   </Get>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0" IteratorID="12345678">
  <Get xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ErrorCode="0x43679000"
       ErrorMsg="'XML Service Library' detected the 'warning'
       condition 'An error was encountered in the XML beneath this operation        tag'" >
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0" ErrorCode="0x4368ac00"
           ErrorMsg="' XMLMDA' detected the 'warning' condition
           ' The XML version specified in the XML request is not compatible
           with the version running on the router'"/>
    </Configuration>
  <Get>
</Response>

Retrieving Version Information

The version of the XML schemas running on the Cisco CRS-1 Series router can be retrieved using the <GetVersionInfo> tag followed by the appropriate tags identifying the names of the desired components.

In the following example, the <GetVersionInfo> tag is used to retrieve the major and minor version numbers for the BGP component configuration schema:

Sample XML Request to Retrieve Major and Minor Version Numbers

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <GetVersionInfo>
    <Configuration>
      <BGP/>
    </Configuration>
  </GetVersionInfo>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <GetVersionInfo>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0"/>
   </Configuration>
  </GetVersionInfo>
</Response>

The following example shows how to retrieve the version information for all configuration schemas available on the router:

Sample XML Request to Retrieve Version Information for All Configuration Schemas

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <GetVersionInfo>
    <Configuration/>
  </GetVersionInfo>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <GetVersionInfo>
    <Configuration>
            .
            .
            .
      <MPLS_LSD MajorVersion="1" MinorVersion="0"/>
      <MPLS_TE MajorVersion="1" MinorVersion="0"/>
      <OUNI MajorVersion="1" MinorVersion="0"/>
      <OLM MajorVersion="1" MinorVersion="0"/>
      <BGP MajorVersion="1" MinorVersion="0"/>
      <CDP MajorVersion="1" MinorVersion="1"/>
      <RSVP MajorVersion="1" MinorVersion="0"/>
            .
            .
            .
      <InterfaceConfiguration>
        <CDP MajorVersion="1" MinorVersion="0"/>
        <SONET MajorVersion="1" MinorVersion="2"/>
        <PPP MajorVersion="1" MinorVersion="0">
          <IPCP MajorVersion="1" MinorVersion="0"/>
        </PPP>
            .
            .
            .
      </InterfaceConfiguration>
            .
            .
            .
    </Configuration>
  </GetVersionInfo>
</Response>