View comments | RSS feed

XmlValidate

Description

Uses a Document Type Definition (DTD) or XML Schema to validate an XML text document or an XML document object.

Returns

The following validation structure:

Field Description

Errors

An array containing any validator error messages. These messages indicate that the document does not conform to the DTD or Schema (is not valid).

FatalErrors

An array containing any validator fatal error messages. Fatal errors indicate that the document contains XML formatting errors (is not well-formed XML).

Status

A Boolean value:

  • True if the document is valid.
  • False if the validation check failed.

Warning

An array containing any validator warnings. A well-formed and valid document can produce warning messages.

Category

XML functions

Function syntax

XmlValidate(xmlDoc[, validator])

See also

cfxml, IsXmlDoc, IsXML, XmlFormat, XmlNew, XmlParse, XmlSearch, XmlTransform; Using XML and WDDX in ColdFusion MX Developer's Guide

History

ColdFusion MX 7: Added this function.

Parameters

Parameter Description

xmlDoc

Any of the following:

  • A string containing an XML document.
  • The name of an XML file.
  • The URL of an XML file; valid protocol identifiers include http, https, ftp, and file.
  • An XML document object, such as one generated by the XmlParse function.

validator

Any of the following:

  • A string containing a DTD or Schema.
  • The name of a DTD or Schema file.
  • The URL of a DTD or Schema file; valid protocol identifiers include http, https, ftp, and file.

Usage

If you specify a relative URL or filename in a parameter, ColdFusion uses the directory (or, for URLs, the virtual directory) that contains the current ColdFusion page as the path root.

The validator parameter specifies a DTD or Schema to use to validate the document. If you omit the parameter, the XML document must contain one of the following:

If you use a validator parameter and the XML document specifies a DTD or Schema, the XmlValidate function uses the validator parameter, and ignores the specification in the XML document.

If you do not use a validator parameter, and the XML document does not specify a DTD or Schema, the function returns a structure with an error message in the Errors field.

This function attempts to process the complete XML document, and reports all errors found during the processing. As a result, the returned structure can have a combination of Warning, Error, and FatalError fields, and each field can contain multiple error messages.

Example

The following example has three parts: an XML file, an XSD Schema file, and a CFML page that parses the XML file and uses the Schema for validation. The CFML file displays the value of the returned structure's Status field and displays the returned structure. To show the results of invalid XML, modify the custorder.xml file.

Note: The Schema used in the following example represents the same XML structure as the DTD used in the XmlParse example.

The custorder.xml file is as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<order xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://localhost:8500/something.xsd" id="4323251" >
   <customer firstname="Philip" lastname="Cramer" accountNum="21"/>
   <items>
      <item id="43">
         <name>   Deluxe Carpenter&apos;s Hammer</name>
         <quantity>1</quantity>
         <unitprice>15.95</unitprice>
      </item>
      <item id="54">
         <name>   36&quot; Plastic Rake</name>
         <quantity>2</quantity>
         <unitprice>6.95</unitprice>
      </item>
      <item id="68">
         <name>   Standard paint thinner</name>
         <quantity>3</quantity>
         <unitprice>8.95</unitprice>
      </item>
   </items>
</order>

The custorder.xsd file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
   <xs:element name="customer">
      <xs:complexType>
         <xs:attribute name="firstname" type="xs:string" use="required"/>
         <xs:attribute name="lastname" type="xs:string" use="required"/>
         <xs:attribute name="accountNum" type="xs:string" use="required"/>
      </xs:complexType>
   </xs:element>
   <xs:element name="name" type="xs:string"/>
   <xs:element name="quantity" type="xs:string"/>
   <xs:element name="unitprice" type="xs:string"/>
   <xs:element name="item">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="name"/>
            <xs:element ref="quantity"/>
            <xs:element ref="unitprice"/>
         </xs:sequence>
         <xs:attribute name="id" type="xs:integer" use="required">
         </xs:attribute>
      </xs:complexType>
   </xs:element>
   <xs:element name="items">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="item" maxOccurs="unbounded"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="order">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="customer"/>
            <xs:element ref="items"/>
         </xs:sequence>
         <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
   </xs:element>
</xs:schema>

The CFML file is as follows. It uses a filename for the XML file and a URL for the Schema. The XML and URL paths must be absolute.

<cfset
myResults=XMLValidate("C:\CFusionMX7\wwwroot\examples\custorder.xml", 
"http://localhost:8500/examples/custorder.xsd")>
<cfoutput>
Did custorder.xml validate against custorder.xsd? #results.status#<br><br>
</cfoutput>
Dump of myResults structure returned by XMLValidate<br>
<cfdump var="#myResults#">

ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


Firechaser said on Mar 24, 2005 at 6:00 AM :
In example code:

results.status should be myResults.status
No screen name said on Apr 28, 2005 at 8:07 AM :
The documentation for RETURN values states "Warning : An array containing any validator warnings. A well-formed and valid document can produce warning messages. "

This should read "Warnings". Note the "s" for plurality. Using the singular "Warning" throws an error.
ASandstrom said on Apr 29, 2005 at 10:58 AM :
In response to dboberg@mail.fdn.com
:
You are correct. It should be warnings.

In addition, the example CFM file should refer to the returned structure as #myResults.status# instead of #results.status#, so the code should read:

<cfset
myResults=XMLValidate("C:\CFusionMX7\wwwroot\examples\custorder.xml",
"http://localhost:8500/examples/custorder.xsd")>
<cfoutput>
Did custorder.xml validate against custorder.xsd? #myResults.status#<br><br>
</cfoutput>
Dump of myResults structure returned by XMLValidate<br>
<cfdump var="#myResults#">
ASandstrom said on Nov 15, 2005 at 11:10 AM :
If a validator argument is not supplied, the XML document must contain either !DOCTYPE or a schema declaration.

If a validator argument is supplied, any !DOCTYPE / schema declaration in the XML doc is ignored, but the XML file is expected to have at least a minimum empty DTD, or schema.
wizardwatson said on Apr 26, 2007 at 10:37 AM :
It seems if you do not specify the xsi:noNamespaceSchemaLocation in your document to be validated, XmlValidate works, but it always gives you the same error when the document doesn't validate:

"Cannot find the declaration of element '[my root element]'."

Some explanation of why this is so, and the significance of the xsi declaration would be helpful. The docs seem to indicate you can leave off all namespace declarations, if you are passing in the validator parameter.

I tested this using the above documents, removing the xsi declaration and changing the name of the 'name' element in the sample doc to 'names'.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000674.htm