Stylesheet contents ​

This page documents what a custom stylesheet is, how Edifix interprets it, and the practical limits to be aware of when adapting an existing stylesheet for use with the API.

The create_job and create_job_from_file endpoints both accept an optional stylesheet_contents body parameter. When provided, Edifix processes the job against the supplied stylesheet instead of a built-in editorial style, and the job's edit_style is recorded as custom.

For the request schema itself, see the API reference.

The canonical reference for the format is the eXtyles Advanced Processing Setup Guide.

Inheritance model ​

Edifix uses an inheritance model that provides a comprehensive set of built-in reference-restructuring defaults (a custom stylesheet only needs to declare the elements that differ from those defaults).

For example, to change only the punctuation after the year while inheriting all other defaults:

xml
<Publisher name="*">
    <Definition>
        <Journal>*</Journal>
        <Reference type="jrn">
            <Struct item="Year"> Y: </Struct>
        </Reference>
    </Definition>
</Publisher>

NULL style (defaults-only behaviour) ​

Edifix cannot run jobs using only the built-in defaults. The closest defaults-only behaviour is the NULL (No Format) editorial style, which uses the following stylesheet:

xml
<Publisher name="*">
<Definition>
    <Journal>*</Journal>
    <Citation Cit="1"/>
    <Citation_Punctiation>
    </Citation_Punctiation>
    <!-- Describe structure of journal reference -->
    <Reference type="*">
        <Restruct reference="no"/>
        <ChapterPunct type="." drop="no" move="out"/>
        <BookPunct type="." drop="no" move="out"/>
    </Reference>
    <Reference type="jrn">
        <Struct item="Reference">ZA. YTJVP.UWD</Struct>
        <Jrnl convert="abbr" dot="yes"/>
        <AuthorLim check="no"/>
        <LastPage required="no"/>
        <Authors insert-missing="yes"/>
        <ArticlePunct type="." drop="no" move="out"/>
    </Reference>
</Definition>
</Publisher>

Practical differences from an eXtyles RefStr.XSP file ​

If you are adapting a stylesheet for use with the Edifix API, two behaviours differ from a local XSP stylesheet file.

The API does not support INCLUDE directives in submitted stylesheets ​

The XSP stylesheet format supports <INCLUDE> directives that pull in another XSP file by path, for example:

xml
<INCLUDE path="SomeOtherStyle.xsp"/>

<INCLUDE> is not supported in submitted stylesheets. Flatten your stylesheet into a single self-contained document before submitting it.

You must flatten any stylesheet before submitting by resolving all <INCLUDE> directives into a single document:

  • Detect every <INCLUDE> directive at every level of nesting.
  • Inline the referenced content while preserving order.
  • Honour the duplicate-prevention behaviour of the format (reuse="yes" allows the same file to be inlined more than once).
  • Submit a single self-contained XML document.

External data-file dependencies on the Jrnl element ​

The <Jrnl> element supports several attributes that point at external data files. Edifix handles each one differently.

The min-year-warn and max-year-warn attributes on <Jrnl> trigger warnings when a reference year falls outside a journal's known publication date range. Edifix evaluates these attributes against its built-in journal data, and the resulting warnings appear in the job_results JATS XML as <p content-type="warning"> elements inside each reference's <annotation> block.

basic-abbr-file, jrn-wrd-file, and jrn-param-file are all supported, but Edifix ignores their value and always uses its own built-in journal-abbreviation, journal-word, and journal-parameter data instead. add-abbr-file is supported when you send the file itself in journal_abbr_contents: see Sending a journal-abbreviation file.

Sending a journal-abbreviation file ​

To use your own journal names and abbreviations for a job, send the file's contents as text in the journal_abbr_contents parameter of create_job or create_job_from_file, alongside stylesheet_contents. The file overrides Edifix's journal data for that job only.

  • journal_abbr_contents is accepted only with stylesheet_contents; otherwise error 0050. It cannot be combined with a built-in edit_style.
  • The file must contain a <Custom journals> or <Bad journals> section; otherwise error 0051.
  • The stylesheet's <Jrnl> element must declare an add-abbr-file attribute; otherwise error 0052. Its value is ignored, so a path from an eXtyles setup can stay as it is.
  • A stylesheet that declares add-abbr-file without a journal_abbr_contents file runs with Edifix's standard journal data.

The file is tab-delimited, in two sections:

<Bad journals>
#Lookup-string    Target (ISSN or abbr or full-name)
<lookup-string>   <issn>
...

<Custom journals>
#Journal NAME    #Journal ABBREVIATION    #Journal ISSN
<full journal name>    <abbreviation>    ---    <issn>
  • <Bad journals> maps malformed or non-standard journal names to an ISSN, for example a parenthetical variant of an abbreviation. Edifix's PubMed and Crossref lookups resolve many of these already, but unusual variants and older journals may fall outside them.
  • <Custom journals> adds journals that are not in Edifix's journal data, with a full name, standard abbreviation, and ISSN. Journals missing from that data are not abbreviated correctly.

Journals that every job needs can instead be added to Edifix's built-in data: contact Edifix Support.

Validation behaviour ​

The stylesheet_contents parameter accepts a single XML document in the XSP reference-restructuring format, of at most 256 KB; a larger value returns error 0053 and is not checked further. A valid stylesheet must include <Publisher>, <Definition>, and <Reference> elements; otherwise the request returns error 0015. This is a quick check that the three elements are present, not full validation of the stylesheet. Supplying stylesheet_contents overrides any edit_style value in the request; Edifix records the job's edit_style as custom. A journal_abbr_contents value is checked as described in Sending a journal-abbreviation file (errors 0050–0052).

If stylesheet_contents is blank or omitted, you must specify edit_style (see Editorial styles).

Last updated: 6 Nov 2026, 03:16:59
Loading navigation...