7 XML Schema Evolution

Introducing XML Schema Evolution

Oracle XML DB supports the W3C XML Schema recommendation. XML instances that conform to an XML schema can be stored and retrieved using SQL and protocols such as FTP, HTTP, and WebDAV. In addition to specifying the structure of XML documents, XML schemas determine the mapping between XML and object-relational storage.

In prior releases an XML schema, once registered with Oracle XML DB at a particular URL, could not be modified or evolved because there may be XMLType tables that depend on the XML schema. There was no standard procedure for schema evolution. This release supports XML schema evolution by providing a PL/SQL procedure CopyEvolve() a part of the DBMS_XMLSCHEMA package. CopyEvolve() involves copying existing instance documents to temporary tables, dropping and re-registering the XML schema, and copying the instance documents to the new XMLType tables.

With copyevolve() you can evolve your registered XML schema in such a way that existing XML instance documents continue to be valid. If you do not care about the existing documents, you can simply drop the XMLType tables dependent on the XML schema, delete the old XML schema, and register the new XML schema at the same URL.

CopyEvolve() has certain limitations. These are described in the section, "Limitations of CopyEvolve()".

Example XML Schema

The following is an example of an XML schema along with typical changes you may want to make. Changes to be made are shown in bold. For changes to attributes, the old value is shown in italics, followed by the new value:

<schema targetNamespace="http://www.oracle.com/po.xsd"
         xmlns="http://www.w3.org/2001/XMLSchema"
         xmlns:po="http://www.oracle.com/po.xsd"
  elementFormDefault="qualified">
  <annotation>
   <documentation xml:lang="en">
     Purchase Order schema for US PO's.
   </documentation>
  </annotation>
<complexType name="Address">
 <sequence>
  <element name="name" type="string"/>
  <element name="street" type="string"/>
  <element name="city" type="string"/>
 </sequence>
</complexType>
<!-- A type representing US States -->
 <simpleType name="USState">
  <restriction base="string">
   <enumeration value="NY"/>
   <enumeration value="TX"/>
   <enumeration value="CA"/>
   <enumeration value="FL"/>
  </restriction>
 </simpleType>
<complexType name="USAddress">
 <complexContent>
 <extension base="po:Address">
   <sequence>
     <element name="STATE" name="State" type="po:USState"/>
     <element name="zip" type="positiveInteger"/>
   </sequence>
 </extension>
 </complexContent>
</complexType>
<element name="PurchaseOrder">
   <complexType>
     <sequence>
        <element name="PO-Number" type="string"/>
        <element name="LineItems" maxOccurs="unbounded">
            <complexType>
              <sequence>
                <element name="part-num" type="string" maxLength="20"/>
                <element name="unit-price" type="float"/>
                <element name="quantity" type="integer"/>
             </sequence>
            </complexType>
           </element>
        <element name="shipTo" type="po:Address"/>
     </sequence>
   </complexType>

The next section describes steps for accomplishing copy-based schema evolution.

Guidelines for Using DBMS_XMLSCHEMA.CopyEvolve()

Here are some guidelines for using DBMS_XMLSCHEMA.CopyEvolve():

1. First identify the XML schemas that are dependent on the XML schema to be evolved. You can acquire the URLs of the dependent XML schemas using the following query:

   SELECT dxs.schema_url
       FROM dba_dependencies dd, dba_xml_schemas dxs
       WHERE dd.referenced_name=(SELECT int_objname
             FROM dba_xml_schemas WHERE schema_url=<EVOL_SCH_URL>
             AND owner=<EVOL_SCH_OWNER>)
             AND dxs.owner = <EVOL_SCH_OWNER>
             AND dxs.int_objname=dd.name;

   In many cases, no changes may be necessary in the dependent XML schemas. But if the dependent XML schemas need to be changed, you must also prepare new versions of those XML schemas.

2. If the existing instance documents do not conform to the new XML schema, you must provide an XSL style sheet that, when applied to an instance document, will transform it to conform to the new schema. This needs to be done for each XML schema identified in Step 1. The transformation must handle documents that conform to all top-level elements in the new XML schema.

3. Call CopyEvolve(), specifying the XML schema URLs, new schemas, and transformations.

SELECT table_name FROM user_tables 
   WHERE table_name LIKE 'XDB$MAPTAB%';

DBMS_XMLSCHEMA.CopyEvolve() Syntax

Here is the DBMS_XMLSCHEMA.CopyEvolve() syntax:

procedure CopyEvolve(schemaURLs       IN XDB$STRING_LIST_T,
                      newSchemas       IN XMLSequenceType,
                      transforms       IN XMLSequenceType := NULL,
                      preserveOldDocs  IN BOOLEAN := FALSE,
                      mapTabName       IN VARCHAR2 := NULL,
                      generateTables   IN BOOLEAN := TRUE,
                      force            IN BOOLEAN := FALSE,
                      schemaOwners     IN XDB$STRING_LIST_T := NULL);

declare
  newaddr    XMLType;
  transform  XMLType;
begin
  newaddr := xmltype(
   '<schema targetNamespace="http://www.example.com/IPO"
          xmlns="http://www.w3.org/2001/XMLSchema"
          xmlns:ipo="http://www.example.com/IPO"
          xmlns:xdb="http://xmlns.oracle.com/xdb"
          elementFormDefault="qualified">
  
  <element name="Address" xdb:defaultTable="ADDR_TAB">
    <complexType>
      <sequence>
        <element name="Name"   type="string"/>
        <element name="Street" type="string"/>
        <element name="City"   type="string" />
        <element name="State"   type="string" />
      </sequence>
    </complexType>
  </element>
  </schema>');
 
transform := xmltype(
  '<xsl:stylesheet  version="1.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns="http://www.example.com/IPO"
 xmlns:ipo="http://www.example.com/IPO">
   <xsl:template match="@*|node()">
      <xsl:copy>
        <xsl:apply-templates select="@*|node()"/>
      </xsl:copy>
   </xsl:template>
   <xsl:template match="/ipo:Address/ipo:STREET">
    <Street>
      <xsl:for-each select="@*|node()">
         <xsl:copy-of select="."/>
      </xsl:for-each>
    </Street>
  </xsl:template>
 </xsl:stylesheet>');
 
dbms_xmlschema.CopyEvolve(xdb$string_list_t('address.xsd'), 
      XMLSequenceType(newaddr), XMLSequenceType(transform));
end;

How DBMS_XMLSCHEMA.CopyEvolve() Works

The DBMS_XMLSCHEMA.CopyEvolve() procedure is used to evolve registered XML schemas such that existing XML instances continue to remain valid.

First CopyEvolve() copies the data in schema based XMLType tables and columns to temporary tables. It then drops the tables and columns and deletes the old XML schemas. After registering the new XML schemas, it creates XMLType tables and columns and populates them with data (unless the genTables parameter is FALSE) but it does not create any auxiliary structures such as indexes, constraints, triggers, and row-level security (RLS) policies. CopyEvolve() creates the tables and columns in the following way:

• It creates default tables while registering the new schemas.

• It creates nondefault tables by a statement of the following form:

  CREATE TABLE <TABLE_NAME> OF XMLType OID '<OID>'   XMLSCHEMA <SCHEMA_URL> ELEMENT <ELEMENT_NAME>

  where <OID> is the original OID of the table, before it was dropped.

• XMLType columns are added using a statement of the following form:

  ALTER TABLE <Table_Name> ADD (<Column_Name> XMLType) XMLType column
    <Column_Name> xmlschema <Schema_Url> ELEMENT <Element_Name>

When a new schema is registered, types or beans are generated if the registration of the corresponding old schema had generated types or beans. If an XML schema was global before the evolution it will be global after the evolution. Similarly if an XML schema was local before the evolution it will be local (owned by the same user) after the evolution.You have the option to preserve the temporary tables that contain the old documents by passing in TRUE for the preserveOldDocs parameter. In this case, the procedure does not drop the temporary tables at the end. All temporary tables are created in the current user's database schema. For XMLType tables the temp table will have the following columns:

For XMLType columns the temp table will have the following columns:

The CopyEvolve() procedure stores information about the mapping from the old table or column name to the corresponding temporary table name in a separate table specified by the mapTabName parameter. If preserveOldDocs is TRUE, the mapTabName parameter must be non-null and must not be the name of any existing table in the current user's schema. Each row in the mapping table has information about one of the old tables/columns. Table 7-5 shows the mapping table columns.

You can also avoid generating any tables or columns after registering the new XML schema, by using FALSE as the genTables parameter. If genTables is FALSE, the preserveOldDocs parameter must be TRUE and the mapTabName parameter must be non-null. This ensures that the data in the old tables is not lost. This is useful if you do not want the tables to be created by the procedure, as described in section "DBMS_XMLSCHEMA.CopyEvolve() Syntax".

By default it is assumed that all XML schemas are owned by the current user. If this is not true, you must specify the owner of each XML schema in the schemaOwners parameter.