An evolved version of a purchase-order XML schema is shown. It is used in examples that illustrate the use of copy-based XML schema evolution.

Example 20-1 shows a partial listing of a revised version of the purchase-order XML schema of Example A-2. See Example A-3 for the complete revised schema listing. Text that is in bold here is new or different from that in the original schema.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xdb="http://xmlns.oracle.com/xdb"
           version="1.0">
  <xs:element
    name="PurchaseOrder" type="PurchaseOrderType"
    xdb:defaultTable="PURCHASEORDER"
    xdb:columnProps=
      "CONSTRAINT purchaseorder_pkey PRIMARY KEY (XMLDATA.reference),
       CONSTRAINT valid_email_address FOREIGN KEY (XMLDATA.userid)
         REFERENCES hr.employees (EMAIL)"
    xdb:tableProps=
      "VARRAY XMLDATA.ACTIONS.ACTION STORE AS TABLE ACTION_TABLE
        ((CONSTRAINT action_pkey PRIMARY KEY (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$)))
       VARRAY XMLDATA.LINEITEMS.LINEITEM STORE AS TABLE LINEITEM_TABLE
        ((constraint LINEITEM_PKEY primary key (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$)))
       lob (XMLDATA.NOTES) STORE AS (ENABLE STORAGE IN ROW STORAGE(INITIAL 4K NEXT 32K))"/>
  <xs:complexType name="PurchaseOrderType" xdb:SQLType="PURCHASEORDER_T">
    <xs:sequence>
      <xs:element name="Actions" type="ActionsType" xdb:SQLName="ACTIONS"/>
      <xs:element name="Reject" type="RejectionType" minOccurs="0" xdb:SQLName="REJECTION"/>
      <xs:element name="Requestor" type="RequestorType" xdb:SQLName="REQUESTOR"/>
      <xs:element name="User" type="UserType" xdb:SQLName="USERID"/>
      <xs:element name="CostCenter" type="CostCenterType" xdb:SQLName="COST_CENTER"/> 
      <xs:element name="BillingAddress" type="AddressType" minOccurs="0"
                  xdb:SQLName="BILLING_ADDRESS"/> 
      <xs:element name="ShippingInstructions" type="ShippingInstructionsType"
                  xdb:SQLName="SHIPPING_INSTRUCTIONS"/> 
      <xs:element name="SpecialInstructions" type="SpecialInstructionsType"
                  xdb:SQLName="SPECIAL_INSTRUCTIONS"/> 
      <xs:element name="LineItems" type="LineItemsType" xdb:SQLName="LINEITEMS"/>
      <xs:element name="Notes" type="NotesType" minOccurs="0" xdb:SQLType="CLOB"
                  xdb:SQLName="NOTES"/> 
    </xs:sequence>
    <xs:attribute name="Reference" type="ReferenceType" use="required" xdb:SQLName="REFERENCE"/>
    <xs:attribute name="DateCreated" type="xs:dateTime" use="required"
                  xdb:SQLType="TIMESTAMP WITH TIME ZONE"/>
  </xs:complexType>
  <xs:complexType name="LineItemsType" xdb:SQLType="LINEITEMS_T">
    <xs:sequence>
      <xs:element name="LineItem" type="LineItemType" maxOccurs="unbounded" xdb:SQLName="LINEITEM"
                  xdb:SQLCollType="LINEITEM_V"/>  
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="LineItemType" xdb:SQLType="LINEITEM_T">
    <xs:sequence>
      <xs:element name="Part" type="PartType" xdb:SQLName="PART"/>
      <xs:element name="Quantity" type="quantityType"/>
    </xs:sequence>
    <xs:attribute name="ItemNumber" type="xs:integer" xdb:SQLName="ITEMNUMBER"
                  xdb:SQLType="NUMBER"/> 
  </xs:complexType>
  <xs:complexType name="PartType" xdb:SQLType="PART_T">
    <xs:simpleContent>
      <xs:extension base="UPCCodeType">
        <xs:attribute name="Description" type="DescriptionType" use="required"
                      xdb:SQLName="DESCRIPTION"/> 
        <xs:attribute name="UnitCost" type="moneyType" use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:simpleType name="ReferenceType">
    <xs:restriction base="xs:string">
      <xs:minLength value="18"/>
      <xs:maxLength value="30"/>
    </xs:restriction>
  </xs:simpleType>

. . .

  <xs:complexType name="RejectionType" xdb:SQLType="REJECTION_T">
    <xs:all>
      <xs:element name="User" type="UserType" minOccurs="0" xdb:SQLName="REJECTED_BY"/>
      <xs:element name="Date" type="DateType" minOccurs="0" xdb:SQLName="DATE_REJECTED"/>
      <xs:element name="Comments" type="CommentsType" minOccurs="0" xdb:SQLName="REASON_REJECTED"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="ShippingInstructionsType" xdb:SQLType="SHIPPING_INSTRUCTIONS_T">
    <xs:sequence>
      <xs:element name="name" type="NameType" minOccurs="0" xdb:SQLName="SHIP_TO_NAME"/>
      <xs:choice>
        <xs:element name="address" type="AddressType" minOccurs="0"/>
        <xs:element name="fullAddress" type="FullAddressType" minOccurs="0"
                    xdb:SQLName="SHIP_TO_ADDRESS"/> 
      </xs:choice>
      <xs:element name="telephone" type="TelephoneType" minOccurs="0" xdb:SQLName="SHIP_TO_PHONE"/>
    </xs:sequence>
  </xs:complexType>

. . .

  <xs:simpleType name="NameType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="20"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="FullAddressType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="256"/>
    </xs:restriction>
  </xs:simpleType>

. . .

  <xs:simpleType name="DescriptionType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="256"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="AddressType" xdb:SQLType="ADDRESS_T">
    <xs:sequence>
      <xs:element name="StreetLine1" type="StreetType"/>
      <xs:element name="StreetLine2" type="StreetType" minOccurs="0"/>
      <xs:element name="City" type="CityType"/>
      <xs:choice>
        <xs:sequence>
          <xs:element name="State" type="StateType"/>
          <xs:element name="ZipCode" type="ZipCodeType"/>
        </xs:sequence>
        <xs:sequence>
          <xs:element name="Province" type="ProvinceType"/>
          <xs:element name="PostCode" type="PostCodeType"/>
        </xs:sequence>
        <xs:sequence>
          <xs:element name="County" type="CountyType"/>
          <xs:element name="Postcode" type="PostCodeType"/>
        </xs:sequence>
      </xs:choice>
      <xs:element name="Country" type="CountryType"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="StreetType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="128"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CityType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="64"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="StateType">
    <xs:restriction base="xs:string">
      <xs:minLength value="2"/>
      <xs:maxLength value="2"/>
      <xs:enumeration value="AK"/>
      <xs:enumeration value="AL"/>
      <xs:enumeration value="AR"/>

 . . . -- A value for each US state abbreviation

      <xs:enumeration value="WY"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="ZipCodeType">
    <xs:restriction base="xs:string">
      <xs:pattern value="\d{5}"/>
      <xs:pattern value="\d{5}-\d{4}"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CountryType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="64"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="CountyType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="32"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="PostCodeType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="12"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="ProvinceType">
    <xs:restriction base="xs:string">
      <xs:minLength value="2"/>
      <xs:maxLength value="2"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="NotesType">
    <xs:restriction base="xs:string">
      <xs:maxLength value="32767"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="UPCCodeType">
    <xs:restriction base="xs:string">
      <xs:minLength value="11"/>
      <xs:maxLength value="14"/>
      <xs:pattern value="\d{11}"/>
      <xs:pattern value="\d{12}"/>
      <xs:pattern value="\d{13}"/>
      <xs:pattern value="\d{14}"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

The parameters of PL/SQL procedure DBMS_XMLSCHEMA.copyEvolve are described, as are the errors associated with this procedure.

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
                     parallelDegree   IN PLS_INTEGER := 0,
                     options          IN PLS_INTEGER := 0);

The use of PL/SQL procedure DBMS_XMLSCHEMA.copyEvolve involves certain limitations.

• Indexes, triggers, constraints, row-level security (RLS) policies, and other metadata related to the XMLType tables that are dependent on the schemas are not preserved. These must be re-created after evolution.

• If top-level element names are changed, additional steps are required after copyEvolve finishes executing. See Top-Level Element Name Changes.

• Copy-based evolution cannot be used if there is a table with an object-type column that has an XMLType attribute that is dependent on any of the schemas to be evolved. For example, consider this table:

  CREATE TYPE t1 AS OBJECT (n NUMBER, x XMLType);
  CREATE TABLE tab1 (e NUMBER, o t1) XMLType 
   COLUMN o.x XMLSchema "s1.xsd" ELEMENT "Employee";
  

  This assumes that an XML schema with a top-level element Employee has been registered under URL s1.xsd. It is not possible to evolve this XML schema, because table tab1 with column o with XMLType attribute x is dependent on the XML schema. Although copyEvolve does not handle XMLType object attributes, it does raise an error in such cases.

General guidelines for using PL/SQL procedure DBMS_XMLSCHEMA.copyEvolveare presented, as well as guidelines that are specific to particular contexts.

The following general guideline applies to using copyEvolve. The rest of this section describes specific guidelines that can also be appropriate in particular contexts.

1. Turn off the recycle bin, to prevent dropped tables from being copied to it:

   ALTER SESSION SET RECYCLEBIN=off;
   

2. Identify the XML schemas that are dependent on the XML schema that is to be evolved. You can acquire the URLs of the dependent XML schemas using the following query, where schema_to_be_evolved is the schema to be evolved, and owner_of_schema_to_be_evolved is its owner (database user).

   SELECT dxs.SCHEMA_URL, dxs.OWNER
       FROM DBA_DEPENDENCIES dd, DBA_XML_SCHEMAS dxs
       WHERE dd.REFERENCED_NAME = (SELECT INT_OBJNAME
                                     FROM DBA_XML_SCHEMAS
                                     WHERE SCHEMA_URL = schema_to_be_evolved
                                       AND OWNER = owner_of_schema_to_be_evolved)
         AND dxs.INT_OBJNAME = dd.NAME;
   

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

3. If the existing instance documents do not conform to the new XML schema, then you must provide an XSL stylesheet that, when applied to an instance document, transforms it to conform to the new schema. You must do this for each XML schema identified in Step 2. The transformation must handle documents that conform to all top-level elements in the new XML schema.

4. Call procedure DBMS_XMLSCHEMA.copyEvolve, specifying the XML schema URLs, new schemas, and transformation stylesheet.

• Top-Level Element Name Changes
  PL/SQL procedure DBMS_XMLSCHEMA.copyEvolve assumes that top-level elements have not been dropped in new schemas and that their names have not been changed. If there are such changes then call procedure copyEvolve with parameter generateTables set to FALSE and parameter preserveOldDocs set to TRUE, so that backup document copies are available.
• User-Created Virtual Columns of Tables Other Than Default Tables
  For tables that are not default tables, any virtual columns that you create are not re-created during copy-based evolution. If such columns are needed then set copyEvolve parameter preserveOldDocs to TRUE, create the tables, and copy the old documents after procedure copyEvolve has finished.
• Ensure That the XML Schema and Dependents Are Not Used by Concurrent Sessions
  Ensure that the XML schema to be evolved, as well as its dependents, are not used by any concurrent session during the XML schema evolution process.
• Rollback When Procedure DBMS_XMLSCHEMA.COPYEVOLVE Raises an Error
  Procedure DBMS_XMLSCHEMA.copyEvolve either completely succeeds or it raises an error. If it raises an error then it tries to roll back as much of the operation as possible.
• Failed Rollback From Insufficient Privileges
  In certain cases you cannot roll back a copy-based evolution operation. For example, if table creation fails due to reasons not related to the new XML schema, then there is no way to roll back.
• Privileges Needed for XML Schema Evolution
  There are several database privileges that you might need, in order to perform copy-based XML schema evolution.

After you modify a registered XML schema, you must update any existing XML instance documents that use the schema. You do this by applying an XSLT stylesheet to each of the instance documents. The stylesheet represents the difference between the old and new XML schemas.

Example 20-2 shows an XSLT stylesheet, in file evolvePurchaseOrder.xsl, that transforms existing purchase-order documents that use the old XML schema, so they use the new XML schema instead.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet 
  version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <xsl:output method="xml" encoding="UTF-8"/>
  <xsl:template match="/PurchaseOrder">
    <PurchaseOrder>
      <xsl:attribute name="xsi:noNamespaceSchemaLocation">
        http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd
      </xsl:attribute>
      <xsl:for-each select="Reference">
        <xsl:attribute name="Reference">
          <xsl:value-of select="."/>
        </xsl:attribute>
      </xsl:for-each>
      <xsl:variable name="V264_394" select="'2004-01-01T12:00:00.000000-08:00'"/>
      <xsl:attribute name="DateCreated">
        <xsl:value-of select="$V264_394"/>
      </xsl:attribute>
      <xsl:for-each select="Actions">
        <Actions>
          <xsl:for-each select="Action">
            <Action>
              <xsl:for-each select="User">
                <User>
                  <xsl:value-of select="."/>
                </User>
              </xsl:for-each>
              <xsl:for-each select="Date">
                <Date>
                  <xsl:value-of select="."/>
                </Date>
              </xsl:for-each>
            </Action>
          </xsl:for-each>
        </Actions>
      </xsl:for-each>
      <xsl:for-each select="Reject">
        <Reject>
          <xsl:for-each select="User">
            <User>
              <xsl:value-of select="."/>
            </User>
          </xsl:for-each>
          <xsl:for-each select="Date">
            <Date>
              <xsl:value-of select="."/>
            </Date>
          </xsl:for-each>
          <xsl:for-each select="Comments">
            <Comments>
              <xsl:value-of select="."/>
            </Comments>
          </xsl:for-each>
        </Reject>
      </xsl:for-each>
      <xsl:for-each select="Requestor">
        <Requestor>
          <xsl:value-of select="."/>
        </Requestor>
      </xsl:for-each>
      <xsl:for-each select="User">
        <User>
          <xsl:value-of select="."/>
        </User>
      </xsl:for-each>
      <xsl:for-each select="CostCenter">
        <CostCenter>
          <xsl:value-of select="."/>
        </CostCenter>
      </xsl:for-each>
      <ShippingInstructions>
        <xsl:for-each select="ShippingInstructions">
          <xsl:for-each select="name">
            <name>
              <xsl:value-of select="."/>
            </name>
          </xsl:for-each>
        </xsl:for-each>
        <xsl:for-each select="ShippingInstructions">
          <xsl:for-each select="address">
            <fullAddress>
              <xsl:value-of select="."/>
            </fullAddress>
          </xsl:for-each>
        </xsl:for-each>
        <xsl:for-each select="ShippingInstructions">
          <xsl:for-each select="telephone">
            <telephone>
              <xsl:value-of select="."/>
            </telephone>
          </xsl:for-each>
        </xsl:for-each>
      </ShippingInstructions>
      <xsl:for-each select="SpecialInstructions">
        <SpecialInstructions>
          <xsl:value-of select="."/>
        </SpecialInstructions>
      </xsl:for-each>
      <xsl:for-each select="LineItems">
        <LineItems>
          <xsl:for-each select="LineItem">
            <xsl:variable name="V22" select="."/>
            <LineItem>
              <xsl:for-each select="@ItemNumber">
                <xsl:attribute name="ItemNumber">
                  <xsl:value-of select="."/>
                </xsl:attribute>
              </xsl:for-each>
              <xsl:for-each select="$V22/Part">
                <xsl:variable name="V24" select="."/>
                <xsl:for-each select="@Id">
                  <Part>
                    <xsl:for-each select="$V22/Description">
                      <xsl:attribute name="Description">
                        <xsl:value-of select="."/>
                      </xsl:attribute>
                    </xsl:for-each>
                    <xsl:for-each select="$V24/@UnitPrice">
                      <xsl:attribute name="UnitCost">
                        <xsl:value-of select="."/>
                      </xsl:attribute>
                    </xsl:for-each>
                    <xsl:value-of select="."/>
                  </Part>
                </xsl:for-each>
              </xsl:for-each>
              <xsl:for-each select="$V22/Part">
                <xsl:for-each select="@Quantity">
                  <Quantity>
                    <xsl:value-of select="."/>
                  </Quantity>
                </xsl:for-each>
              </xsl:for-each>
            </LineItem>
          </xsl:for-each>
        </LineItems>
      </xsl:for-each>
    </PurchaseOrder>
  </xsl:template>
</xsl:stylesheet>

Several examples are presented of using PL/SQL procedureDBMS_XMLSCHEMA.copyEvolve to update an XML schema. (Be sure to back up all registered XML schemas and XML documents that reference them, before using the procedure.)

DECLARE
  res BOOLEAN;
BEGIN
  res := DBMS_XDB_REPOS.createResource(         -- Load revised XML schema
           '/source/schemas/poSource/revisedPurchaseOrder.xsd',
           bfilename('XMLDIR', 'revisedPurchaseOrder.xsd'),
           nls_charset_id('AL32UTF8'));
  res := DBMS_XDB_REPOS.createResource(         -- Load revised XSL stylesheet
           '/source/schemas/poSource/evolvePurchaseOrder.xsl',
           bfilename('XMLDIR', 'evolvePurchaseOrder.xsl'),
           nls_charset_id('AL32UTF8'));
END;/

BEGIN
  DBMS_XMLSCHEMA.copyEvolve(
    xdb$string_list_t('http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd'),
    XMLSequenceType(XDBURIType('/source/schemas/poSource/revisedPurchaseOrder.xsd').getXML()),
    XMLSequenceType(XDBURIType('/source/schemas/poSource/evolvePurchaseOrder.xsl').getXML()));
END;

SELECT XMLQuery('$p/PurchaseOrder/LineItems/LineItem[1]'
                PASSING po.OBJECT_VALUE AS "p" RETURNING CONTENT) line_item
  FROM purchaseorder po
  WHERE XMLExists('$p/PurchaseOrder[Reference="SBELL-2003030912333601PDT"]'
                  PASSING po.OBJECT_VALUE AS "p");
 
LINE_ITEM
------------------------------------------------------------------------------
<LineItem ItemNumber="1">
  <Part Description="A Night to Remember" UnitCost="39.95">715515009058</Part>
  <Quantity>2</Quantity>
</LineItem>

LINE_ITEM
----------------------------------------------------------
<LineItem ItemNumber="1">
  <Description>A Night to Remember</Description>
  <Part Id="715515009058" UnitPrice="39.95" Quantity="2"/>
</LineItem>

Because in-place XML schema evolution avoids copying data, it does not permit arbitrary changes to an XML schema. The primary restriction on using in-place evolution can be stated generally as a requirement that a given XML schema can be evolved in place in only a backward-compatible way.

For the complete list of changes supported by in-place evolution, see Supported Operations for In-Place XML Schema Evolution.

Backward-compatible here means that any possible instance document that would validate against a given XML schema must also validate against a later (evolved) version of that XML schema. This applies to all possible conforming instance documents, not only to existing instance documents For XML data that is stored as binary XML, backward compatibility also means that any XML schema annotations that affect binary XML treatment must not change during evolution.

In addition to this general backward-compatibility restriction, there are some other restrictions for in-place evolution.

• Backward-Compatibility Restrictions
  Restrictions on in-place XML schema evolution are described that ensure backward compatibility of an evolved schema, so that any possible instance documents that satisfy the old XML schema also satisfy the new one.
• Other Restrictions on In-Place Evolution
  Some restrictions on in-place XML schema evolution are necessary for reasons other than backward compatibility of the evolved XML schema.

Some of the operations that are supported for in-place schema evolution are described. Some of these are not permitted in specific contexts, which are specified.

• Add an optional element to a complex type or group: Always permitted. An example is the addition of the optional element shipmethod in the following complex type definition:

  <xs:complexType name="ShippingInstructionsType">
      <xs:sequence>
          <xs:element name="name" type="NameType" minOccurs="0"/>
          <xs:element name="address" type="AddressType" minOccurs="0"/>
          <xs:element name="telephone" type="TelephoneType" minOccurs="0"/>
          <xs:element name = "shipmethod" type = "xs:string" minOccurs = "0"/>
      </xs:sequence>
  </xs:complexType>
  

• Add an optional attribute to a complex type or attribute group: Always permitted. An example is the addition of the optional attribute shipbydate in the following complex type definition:

  <xs:complexType name="ShippingInstructionsType">
      <xs:sequence>
          <xs:element name="name" type="NameType" minOccurs="0"/>
          <xs:element name="address" type="AddressType" minOccurs="0"/>
          <xs:element name="telephone" type="TelephoneType" minOccurs="0"/>
      </xs:sequence>
      <xs:attribute name="shipbydate" type="DateType" use="optional"/>
  </xs:complexType>
  

• Convert an element from simple type to complex type with simple content: Supported only if the storage model is binary XML.

• Modify the value attribute of an existing maxLength element: Always permitted. The value can only be increased, not decreased.

• Add an enumeration value: You can add a new enumeration value only to the end of an enumeration list.

• Add a global element: Always permitted. An example is the addition of the global element PurchaseOrderComment in the following schema definition:

  <xs:schema ...> 
  ... 
      <xs:element name="PurchaseOrderComment" type="string" xdb:defaultTable=""/> 
  .. 
  </xs:schema>
  

• Add a global attribute: Always permitted.

• Add or delete a global complex type: Always permitted. An example is the addition of the global complex type ComplexAddressType in the following schema definition:

  <xs:schema ...> 
  .... 
      <xs:complexType name="ComplexAddressType"> 
          <xs:sequence> 
              <xs:element name="street" type="string"/> 
              <xs:element name="city" type="string"/> 
              <xs:element ref="zip" type="positiveInteger"/> 
              <xs:element name="country"  type="string"/> 
          </xs:sequence> 
       </xs:complexType> 
  ... 
  </xs:schema>
  

• Add or delete a global simple type: Always permitted.

• Change the minOccurs attribute value: The value of minOccurs can only be decreased.

• Change the maxOccurs attribute value: The value of maxOccurs can only be increased, and this is only possible for data stored as binary XML. That is, you cannot make any change to the maxOccurs attribute for data stored object-relationally.

• Add or delete a global group or attributeGroup: Always permitted. An example is the addition of an Instructions group in the following type definition:

  <xsd:schema ...> 
  ... 
    <xsd:group name="Instructions"> 
      <xsd:sequence> 
       <xsd:element name="ShippingInstructions" type="ShippingInstructionsType"/> 
       <xsd:element name="SpecialInstructions" type=" SpecialInstructionsType"/> 
      </xsd:sequence> 
    </xsd:group> 
  ... 
  </xsd:schema>
  

• Change the xdb:defaultTable attribute value: Always permitted. Changes are not permitted to any other attributes in the xdb namespace.

• Add, modify, or delete a comment or processing instruction: Always permitted.

Guidelines that apply to in-place XML-schema evolution are presented. (Be sure to back up your data before performing in-place schema evolution.)

• Before you perform an in-place XML-schema evolution:

  • Back up all existing data (instance documents) for the XML schema to be evolved.

    Caution:

    Make sure that you back up your data before performing in-place XML schema evolution, in case the result is not what you intended. There is no rollback possible after an in-place evolution. If any errors occur during evolution, or if you make a major mistake and need to redo the entire operation, you must be able to go back to the backup copy of your original data.

  • Perform a dry run using trace only, that is, without actually evolving the XML schema or updating any instance documents, produce a trace of the update operations that would be performed during evolution. To do this, set the flag parameter value to only INPLACE_TRACE. Do not also use INPLACE_EVOLVE.

    After performing the dry run, examine the trace file, verifying that the listed DDL operations are in fact those that you intend.

• After you perform an in-place XML-schema evolution:

  If you are accessing the database using a client that caches data, or if you are not sure whether this is the case, then restart your client. Otherwise, the pre-evolution version of the XML schema might continue to be used locally, with unpredictable results.

The parameters of PL/SQL procedure DBMS_XMLSCHEMA.inPlaceEvolve are described, as are the errors associated with this procedure.

procedure inPlaceEvolve(schemaURL IN VARCHAR2,
                        diffXML   IN XMLType, 
                        flags     IN NUMBER);

The value of parameter diffXML of procedure DBMS_XMLSCHEMA.inPlaceEvolve is an XMLType instance that specifies the changes to be applied to an XML schema for in-place evolution. This diffXML document contains a sequence of operations that describe the changes between the old XML schema and the new (the intended evolution result).

The changes specified by the diffXML document are applied in order.

You must create the XML document to be used for the diffXML parameter You can do this in any of the following ways:

• The XMLDiff JavaBean (oracle.xml.differ.XMLDiff)

• The xmldiff command-line utility

• SQL function XMLDiff

The diffXML parameter document must conform to the xdiff XML schema.

The rest of this section presents examples of some operations in a document that conforms to the xdiff XML schema.

• diffXML Operations and Examples
  Operations that can be specified in the diffXML document supplied to procedure DBMS_XMLSCHEMA.inPlaceEvolve are described. An example XML document that conforms to the xdiff XML schema is shown.