EditorialXML

validacion

Common JATS XML Errors and How to Fix Them

EditorialXML5 min read
  • jats
  • errors
  • validation

JATS validation reveals error patterns that repeat across journals of all sizes and disciplines. Knowing these patterns speeds correction and prevents the same problems from reappearing issue after issue. This guide collects the most frequent errors we detect when validating thousands of articles, with concrete examples and immediately applicable solutions.

For detailed diagnostics of each error type, see our error guides library.

1. Element in disallowed position

Symptom: The validator reports "element not allowed" or "invalid content model".

Cause: A child element appears where the JATS schema does not permit it. Classic example: placing <table-wrap> directly inside <abstract> or a loose <p> outside any <sec> in the body.

Incorrect:

<body>
  <p>Paragraph without a containing section.</p>
</body>

Correct:

<body>
  <sec sec-type="intro">
    <title>Introduction</title>
    <p>Paragraph inside a valid section.</p>
  </sec>
</body>

See the dedicated guide on element not allowed for more cases.

2. Missing required attribute

Symptom: "Required attribute missing" on elements such as <article>, <contrib>, or <ref>.

Cause: JATS requires specific attributes. The most forgotten is article-type on <article> and id on references, figures, and tables.

Incorrect:

<article dtd-version="1.3">

Correct:

<article article-type="research-article" dtd-version="1.3">

Consult missing required attribute for a full checklist.

3. Duplicate IDs

Symptom: Broken cross-references or uniqueness errors in advanced validators.

Cause: Two elements share the same id value. This frequently occurs when copying reference or figure blocks from a previous article.

Solution: Implement an ID convention (ref1, ref2, fig1, tbl1) and verify uniqueness before final validation.

4. Unlinked affiliations

Symptom: Authors with <aff> defined but no <xref ref-type="aff"> in the contrib.

Cause: Separation between affiliation declaration in <aff id="aff1"> and linking in each author. SciELO and PMC reject articles with "orphan" authors.

<contrib contrib-type="author">
  <name><surname>Perez</surname><given-names>Luis</given-names></name>
  <xref ref-type="aff" rid="aff1"><sup>1</sup></xref>
</contrib>

5. Unstructured free-text references

Symptom: <mixed-citation> with incomplete data or no parseable elements.

Cause: Automatic conversion from Word that does not separate author, title, and source.

Solution: Migrate to <element-citation> with all subelements. For bulk conversion, use reference parsing tools and manually review ambiguous cases. See malformed references.

6. Malformed DOI

Symptom: The DOI includes the https://doi.org/ prefix inside the element value, or contains spaces.

Incorrect:

<article-id pub-id-type="doi">https://doi.org/10.1234/example</article-id>

Correct:

<article-id pub-id-type="doi">10.1234/example</article-id>

7. Unescaped special characters

Symptom: Malformed XML or corrupted characters in names and titles.

Cause: Incorrect encoding (Latin-1 instead of UTF-8) or unescaped &, <, > characters.

Solution: Save all files in UTF-8. Escape & as &amp; in text that is not markup.

Symptom: Figures without images, inaccessible supplementary material.

Cause: Incorrect relative paths in <graphic xlink:href="..."> or xlink namespace not declared.

Verify the namespace is on the root element:

<article xmlns:xlink="http://www.w3.org/1999/xlink" ...>

9. Abstract without language attribute

Symptom: Warning or error in SciELO SPS validators.

Cause: <abstract> without xml:lang when the article has multilingual metadata.

<abstract xml:lang="en">
  <p>Abstract in English...</p>
</abstract>
<trans-abstract xml:lang="es">
  <p>Resumen en español...</p>
</trans-abstract>

10. Inconsistent dates

Symptom: Rejection in SciELO quality control.

Cause: Acceptance date before receipt, or publication date before acceptance.

Review editorial cycle logic before tagging <history>.

11. article-type incompatible with content

Symptom: Article marked as research-article without methods and results sections.

Cause: Using a generic type for all articles regardless of nature.

Use precise types: review-article, case-report, editorial, letter.

12. Tables without semantic structure

Symptom: Tables that do not render correctly in derived HTML.

Cause: Using HTML <table> without JATS <table-wrap> wrapper, or cells without <th> in headers.

<table-wrap id="tbl1">
  <label>Table 1</label>
  <caption><title>Table description</title></caption>
  <table>
    <thead>
      <tr><th>Column A</th><th>Column B</th></tr>
    </thead>
    <tbody>
      <tr><td>Data 1</td><td>Data 2</td></tr>
    </tbody>
  </table>
</table-wrap>

13. Missing or incorrect license

Symptom: Error in SciELO validation for open access journals.

Cause: Omitted <permissions> block or Creative Commons URI that does not match journal policy.

14. ORCID with incorrect format

Symptom: ORCID not recognized by harvesters.

Cause: ORCID stored without full URL or with incorrect hyphens.

Correct:

<contrib-id contrib-id-type="orcid">https://orcid.org/0000-0001-2345-6789</contrib-id>

15. Validation only at the end of the process

Symptom: Accumulation of errors in complete batches.

Cause: Validating the entire issue once, days before SciELO delivery.

Solution: Validate each article as it enters production. Use the JATS validator continuously, not as a final emergency step.

Systematic correction strategy

  1. Classify errors by type (structure, metadata, references, multimedia).
  2. Prioritize blocking errors over warnings.
  3. Fix in template errors that repeat to prevent recurrence.
  4. Document internal tagging conventions for your journal.
  5. Revalidate after each correction round.

Additional resources

Conclusion

JATS errors are not a sign of technical incompetence: they are the predictable result of converting documents designed for human reading (Word, PDF) into structured data for machines. The difference between journals that publish without friction and those facing recurring returns lies in detecting and correcting these patterns early and systematically.

Start by validating your next article in the JATS validator and explore the error guides to deepen each category.

Related articles