Validation

Validation is the process by which we check whether the encoding of a file matches the rules established in the schema that governs the file: whether all of the elements used are defined in the schema, whether they appear in legal places, and whether all required elements are present. There are several different validation tools available; the one oXygen use by default is called jing.

It's much easier to fix one or two validation errors than to fix a large number, so we recommend that you validate early and often—validate every time you save. (And save often!) To validate your file, type Command-shift-v (Mac) or Control-shift-v (PC).

A few general pointers:

  • It is a good idea to save your file before validating it; besides helping get you in the habit of saving early and often, in the off chance the validation process hangs, you won't lose your changes if you have to force quit oXygen.
  • Fix one error, then save and validate again. The XML validation process may report the same error several times in different ways, so a list of five errors may result from a single missing character in the file. Fixing one thing may dramatically reduce your error list and make it easier to diagnose the remaining errors.
  • Alternatively, if you are going to fix multiple errors in a row before re-validating, consider starting from the bottom of the list and working your way up. If you fix an error in a way that adds or deletes lines from the file, oXygen will no longer take you to the correct line when double-clicking on an error message for an error that follows the fix.
  • Look out carefully for missing angle brackets, missing slashes in end-tags, missing end-tags: these are the most common errors and the hardest to see. If you use tag insertion (<, Command-e or Control-e) rather than typing the tags by hand you'll avoid making these errors to start with.

The lists below give common error messages and suggests how to fix the errors involved. Examples use the element <foo type="bar">.

Well-formedness errors

The most basic kinds of errors are those that make your file ill-formed: it does not conform to the basic XML rules of nesting and delimitation. The XML parser (the tool that reads the XML document and maps out its tree structure) can not properly parse a file with this class of error. Examples of this kind of error are things like missing start- or end-tags, missing markup characters (like unmatched quotation marks around attribute values, or missing angle brackets), or overlapping elements.

  • The element type "foo" must be terminated by the matching end-tag "</foo>": the parser has found a discrepancy between a start-tag and the end-tag it thinks should correspond to it. This might be caused by a typo in the name of the start- or end-tag, or by a missing character in the markup (missing or mismatched quotation marks, missing equals sign, missing angle bracket). Go to the error location and look closely. The error message will try to indicate the exact location of the error. If the error is a mistyped element name, the error message will report the start-tag and end-tag involved (e.g. <div> and </dov>), and point out exactly where you made the mistake. However, if the error is an omitted markup character, the error message reports the nearest well-formed tag. This may produce a misleading error message that mentions elements which are perfectly fine. Look at the other error messages for clues about where the error might be, and check your encoding carefully for missing characters.
  • Element type "foo" must be followed by either attribute specifications, ">", or "/>": this indicates there's either a missing quotation mark around an attribute value, missing whitespace before an attribute name, or a missing ">". Look carefully at the start-tag.
  • Attribute name "bar" associated with an element type "foo" must be followed by the "=" character: this indicates there's a missing equals sign within an attribute construct.

Validity errors

Validity errors indicate that your file does not conform to the WWP schema: e.g. because you've used an element that doesn't exist, or you've put an element in the wrong place, or you've omitted some required element.

  • Element "foo" not allowed here; expected the element end-tag, text, or element [big long list of elements]: Reduced to essentials, this error message is saying that it expected some particular set of elements as the content of the <foo> element, but it got some other set of elements. In theory you could read the list of possibilities and figure out what it wanted and where your encoding is different, but in practice it's usually easier to look at your encoding and think "where did I mess up?".
  • Text not allowed here; expected the element end-tag or element "[some other element(s)]": This error message usually means that you have put text (words and punctuation) in a place where only elements are allowed to go: for instance, between <div> elements or list items. In some cases the problem can be solved by enclosing that text in an appropriate element. In other cases, the text in question may be a stray mark (e.g. an accidental comma) which simply needs to be found and deleted.
  • Attribute "bar" not allowed here: The @bar attribute either does not exist or is not permitted on this particular element. Check your typing and look up the element in the documentation to check on its permissible attributes. You can avoid this error by always choosing your attributes from the drop-down list rather than typing them in by hand.
  • Element "foo" missing required attribute "bar": The element foo is missing a required attribute named "bar".
  • Value of attribute "bar" is invalid: this means that the @bar attribute for this element requires a value, but you have not yet provided one.
  • Value of attribute "bar" is invalid; must be equal to "[list of options]": this means that the @bar attribute for this element uses a controlled list of possible values, and the attribute value you've used isn't one of the permitted values. You can avoid this error by always using the drop-down list of attribute values when one is offered.
  • Value of attribute "bar" is invalid; must be an ISO month...[or some other unfamiliar construct]: this means that the @bar attribute for this element is required to conform to a specific pattern: for instance, a date in a standard format. Check the documentation to learn more about the attribute and its required value type.
  • Element foo incomplete: this means that the element foo is fine where it is, but it needs to contain some additional elements in order to be valid. For instance, an <lg> element is invalid if it does not contain at least one <l> element.