8. XML Well-Formed and Valid

What you will learn

• The difference between well-formed and valid
• A checklist for well-formed XML
• What “valid” adds, and what checks it
• How to check your files, and read error messages

Two levels of correct

XML has two separate ideas of “correct”. They are often confused.

Every valid file is well-formed, but a well-formed file is not necessarily valid.

The well-formed checklist

1. The optional declaration, if present, is the very first thing in the file.
2. There is exactly one root element.
3. Every start tag has a matching end tag (or is self-closing).
4. Elements are properly nested.
5. Names are case sensitive, and start and end tags match exactly.
6. Attribute values are quoted, and no attribute repeats on an element.
7. Special characters (<, &) are escaped.
8. Any prefix used has a namespace declared.

Well-formed, but not valid

Imagine a rule that says: “Every book must have a title and a price.” This file obeys the syntax, but not the rule:

<?xml version="1.0" encoding="UTF-8"?>
<library>
  <book>
    <title>Learning XML</title>
  </book>
</library>

Not even well-formed

<library>
  <book>
    <title>Learning XML</Title>
  </book>
</library>

XML is strict on purpose. Browsers recover from broken HTML, but an XML parser stops at the first well-formedness error. That is what makes the data reliable.

What makes a file valid?

To check validity you need a description of the allowed structure, which you write once:

• A DTD (Document Type Definition) is the older, simpler way. The next lesson covers it.
• An XML Schema (XSD) is the modern, more powerful way, which can also check data types such as numbers and dates. Two later lessons cover it.

A description lists things such as which elements may appear, in what order, how many times, which attributes are required, and what kind of value each may hold.

Why validity matters

• Catches mistakes early: a missing field, a wrong order, or a number that is really text.
• Acts as a contract between two systems that exchange data.
• Protects your program: you can trust the shape of data that passed validation.

How to check your files

1. Your browser

Open the .xml file. A well-formed file shows as a tree. A broken file shows an error message with a line number. This checks well-formedness only.

2. Your code editor

Visual Studio Code has extensions that underline XML mistakes as you type, and some can also check against a schema. Search the extensions list for an XML extension from a publisher you trust.

3. Online validators

Several free sites check well-formedness and validate against a DTD or XSD. Do not paste private or sensitive data into a website you do not control. Use made-up sample data instead.

4. Command-line tools

If the xmllint program is installed on your computer, you can check a file from a terminal:

xmllint --noout library.xml

No output means the file is well-formed. An error message names the line. It is not installed by default on Windows.

5. Your own code

PHP can load XML and collect problems. This lets a program refuse bad files politely.

<?php
libxml_use_internal_errors(true);

$xml = "<library><book><title>Learning XML</Title></book></library>";

$doc = new DOMDocument();

if ($doc->loadXML($xml)) {
    echo "The XML is well-formed.";
} else {
    echo "The XML is not well-formed.<br>";
    foreach (libxml_get_errors() as $error) {
        echo "Line " . $error->line . ": " . htmlspecialchars(trim($error->message), ENT_QUOTES, "UTF-8") . "<br>";
    }
    libxml_clear_errors();
}

JavaScript can do the same with the DOMParser, which a later lesson uses.

Reading error messages

• Fix the first error first. Later errors are often caused by it.
• The reported line is where the parser noticed the problem. The real mistake may be a line or two earlier.
• Typical causes: a mismatched or missing end tag, an unescaped &, an unquoted attribute value, two roots, or text before the declaration.

A good routine

1. Write the XML.
2. Check that it is well-formed (browser or editor).
3. If you have a schema, validate against it.
4. Keep sample files for both a good and a bad case, to test your programs.

Common mistakes

• Thinking “valid” and “well-formed” mean the same thing.
• Assuming a file that opens in a browser is also valid against a schema.
• Pasting private data into an online validator.
• Fixing errors from the bottom up instead of the first one down.
• Trusting data because it passed validation.

A:  <list><item><name>Pen</name></item></list>
B:  <list><item></item></list>
C:  <list><item><name>Pen</item></name></list>

Summary

• Well-formed means correct XML syntax, and it is always required. Valid means it also follows a DTD or schema.
• Check well-formedness with a browser, editor, tool, or your own code, and fix the first error first.
• The next lessons show how to write DTDs and schemas.