Elements

<usx>

Element:usx *
empty
Added:1.0
Use:Root element for USX scripture file.
@version:USX version identifier. *
xsd:decimal
Only the specific USX version number for scripture data contained in the file is allowed (1.0, 2.0, 2.5 etc.).
Parent:ROOT

The following schema diagram displays the document structure of a USX scripture file.

Diagram

../_images/usx_usx-document.png

Sample

<usx version="2.5">

<book>

Element:book *
xsd:string
Added:1.0
Use:Brief description of scripure translation.
@code:3-letter book code for the scripture content in the USX document. *
one of bookCode
@style:Content type. *
id
Valid in:Book Identification
Parent:<usx>

Diagram

../_images/usx-element_book.png

Sample

<book code="MAT" style="id">English: Good News Translation 2nd Ed. 1992</book>

<chapter>

Element:chapter *
empty
Added:1.0
Use:Initial element within each chapter text division. Marks the start of a new chapter.
@style:Content type. *
c
@number:Current chapter number (sequential; according to versification definition for the scripture text). *
xsd:integer
@altnumber:Alternate chapter number. (Used to supply the chapter number for an alternate versification scheme. This is required when the numbering for an alternate versification tradition need to be maintained within the same translation text.)
xsd:string of pattern [0-9]+\w?(\u200F?[\-,][0-9]+\w?)*
@pubnumber:Published chapter character. (The chapter character(s) (a string - number, letter or both) which should be displayed in a published version of the scripture text, where the published chapter character is different than the sequential chapter number used within the translation editing environment, as defined by the project versification.) *
xsd:string
Valid in:Chapter Text
Parent:<usx>

Diagram

../_images/usx-element_chapter.png

Sample

Code examples for chapter and verse are provided after the definition for element verse (below).

<verse>

Element:verse *
empty
Added:1.0
Use:Marks the start of a new verse.
@style:Content type. *
v
@number:Current verse number (sequential; according to versification definition for the scripture text). *
xsd:string of pattern [0-9]+\w?(‏?[\-,][0-9]+\w?)*
@altnumber:Alternate verse number. (Used to supply the verse number for an alternate versification scheme. This is required when the numbering for an alternate versification tradition need to be maintained within the same translation text.)
xsd:string of pattern [0-9]+\w?(‏?[\-,][0-9]+\w?)*
@pubnumber:Published chapter character. (The chapter character(s) (a string - number, letter or both) which should be displayed in a published version of the scripture text, where the published chapter character is different than the sequential chapter number used within the translation editing environment, as defined by the project versification.)
xsd:string
Valid in:Chapter Text
Parents:<para>, <row>, <cell>

Diagram

../_images/usx-element_verse.png

Samples

chapter and verse (MAT 5:1, with preceding and following context)

<para style="p"> ... Large crowds followed him from Galilee and the Ten Towns, from Jerusalem, Judea,
  and the land on the other side of the Jordan.</para>
<chapter number="5" style="c" />
<para style="s">The Sermon on the Mount</para>
<para style="p">
  <verse number="1" style="v" />Jesus saw the crowds and went up a hill, where he sat down.
  His disciples gathered around him, <verse number="2" style="v" />and he began to teach them:</para>
  ...

An additional six chapters appear interspersed in Esther in the Septuagint. There are 3 common approaches to handling the Greek additions (and many additional variations!). Although Paratext requires sequential chapter and verse numbers to be used within the translation editing environment – as defined by the project versification – in numerous places this is not the string to be published for the chapter and/or verse identifiers at these locations. Examples from Esther Greek are shown below to highlight the application of the @pubnumber attribute for chapter and verse.

The following example of the text for Esther Greek chapter 1 is taken from the English Good News Bible text. This text follows a versification scheme for Esther Greek which may be referred to as “modern scholars” configuration. Some versions following this scheme include English Good News, French La Bible en francais courant, and German Gute Nachricht Bible.

  • In the first portion of this example, you can see a chapter element with the sequential @number “1” which includes a @pubnumber “A”. The “A” should be presented to the reader.
  • In the second portion of this example, a para element with @style “cp” is found. Although a sequential chapter element is not present at this location, a chapter heading or other appropriate chapter style showing “1” should be presented to the reader.
  • In the second portion of this example you can also see verse elements with sequential @number “18-19”, “20”, “21”, “22”. The corresponding @pubnumber “1-2”, “3”, “4”, and “5” should be presented to the reader.

chapter and verse (ESG 1, showing chapter, @pubnumber A, and cp 1; verse 18-19 @pubnumber 1-2 etc.)

<chapter number="1" style="c" pubnumber="A" />
<para style="s">Mordecai's Strange Dream</para>
<para style="p">
<verse number="1-3" style="v" />Mordecai, a Jew who belonged to the tribe of Benjamin, was taken
  into exile, along with King Jehoiachin of Judah, when King Nebuchadnezzar of Babylonia captured
  Jerusalem...</para>

...

<para style="cp">1</para>
<para style="s">Queen Vashti Defies King Xerxes</para>
<para style="p">
<verse number="18-19" style="v" pubnumber="1-2" />These things happened in the time of King Xerxes,
  who ruled 127 provinces, all the way from India to Ethiopia, from his royal throne in Susa,
  Persia's capital city. <verse number="20" style="v" pubnumber="3" />In the third year of his reign,
  the king gave a banquet for all his advisers, the representatives of the other countries, the
  noblemen from Persia and Media, and the governors of the provinces.
<verse number="21" style="v" pubnumber="4" />For six whole months he made a show of the riches
  of the imperial court with magnificent and expensive celebrations.</para>
<para style="p">
<verse number="22" style="v" pubnumber="5" />After the feast the king gave a banquet for the people
  of other nations who were in the city...</para>

...

The following example is taken from the English Contemporary English Version (CEV) text, which applies a different versification scheme to Esther Greek following the Vulgate. The NRSV Anglicised Edition is another example following this scheme.

chapter and verse (ESG 1, showing chapter 1 @pubnumber 11, cp 12, and 1; verse 1-3 @pubnumber 2-4, verse 4 @pubnumber 5, verse 12 @pubnumber 1 etc.)

<chapter number="1" style="c" pubnumber="11" />
<para style="ms1">Addition A</para>
<para style="s1">Mordecai's Dream</para>
<para style="p">
<verse number="1-3" style="v" pubnumber="2-4" />Mordecai son of Jair was a Jew from the Benjamin
  tribe, and he lived in the city of Susa in Persia. Mordecai had been taken away from Jerusalem as
  a prisoner, when King Nebuchadnezzar of Babylonia had captured King Jehoiachin. ...</para>
<para style="p">In Mordecai's dream, <verse number="4" style="v" pubnumber="5" /> there was confusion
  and unrest all over the world. He heard crashing thunder, and the earth shook with an earthquake
<verse number="5" style="v" pubnumber="6" /> as two huge dragons went toward each other, ready
  to fight...</para>

...

<verse number="11" style="v" pubnumber="12" /> Mordecai woke up, but he knew that in his dream he
  had seen what God was planning to do. And so, Mordecai thought about his dream all day, trying to
  understand exactly what it meant.</para>
<para style="cp">12</para>
<para style="s1">Mordecai <optbreak /> Saves the King's Life</para>
<para style="p">
<verse number="12" style="v" pubnumber="1" />That night, Mordecai was in the palace courtyard.
  He was resting not far from Gabatha and Tharra, the two officers who were on guard duty.
<verse number="13" style="v" pubnumber="2" /> Mordecai overheard them talking, and as he
  listened carefully, he realized they were planning to murder King Artaxerxes.</para>

...

<para style="ms1">End of Addition A</para>
<para style="cp">1</para>
<para style="s1">Queen Vashti Disobeys <optbreak /> King Artaxerxes</para>
<para style="p">
<verse number="18-20" style="v" pubnumber="1-3" />King Artaxerxes lived in his capital city of Susa
  and ruled 127 provinces from India to Ethiopia.</para>

An example from Psalms (modified French TOB) showing an alternate chapter and verse numbering scheme encoded within the text.

chapter and verse (PSA 42, showing chapter @altnumber and verse @altnumber)

<chapter number="42" style="c" altnumber="41" />
<para style="ms1">DEUXIÈME LIVRE</para>
<para style="mr">(Ps 42–72)</para>
<para style="s1">PSAUME 42</para>
<para style="d">
<char style="va">1</char> Du chef de chœur. Instruction des fils de Coré.</para>
<para style="q1">
<verse number="1" style="v" altnumber="2" /> Comme une biche se tourne</para>
<para style="q1">vers les cours d'eau,</para>
<para style="q1">ainsi mon âme se tourne</para>
<para style="q1">vers toi, mon Dieu.</para>
<para style="q1">
<verse number="2" style="v" altnumber="3" /> J'ai soif de Dieu,</para>
<para style="q1">du Dieu vivant:</para>
<para style="q1">Quand pourrai-je entrer</para>
<para style="q1">et paraître face à Dieu?</para>

<para>

ico_R Schema pattern name: Para

Element:para
xsd:string
Added:1.0
Use:Paragraph content.
@style:Content type. *
Permitted values vary for each document division. The para @style types list presents an itemization of style values by category (paragraphs, poetry, titles etc.) and indicates the document divisions in which each type is valid.
Valid in:Book Header, Book Titles, Book Introduction, Introduction End Titles, Book Chapter Label, Chapter Text
Parents:<usx>

Diagram

../_images/usx-element_para.png

Sample

<para style="p">
<verse number="1" style="v" />This is the Good News about Jesus Christ, the Son of God ...</para>

<para style="q1">“God said, ‘I will send my messenger ahead of you</para>
<para style="q2">to open the way for you.’</para>

<para style="s">The Sermon on the Mount</para>
<para style="p">
  <verse number="1" style="v" />Jesus saw the crowds and went up a hill, where he sat down.
  His disciples gathered around him, <verse number="2" style="v" />and he began to teach them:</para>
<para style="s">Salt and Light</para>
<para style="r">(Mark 9.50; Luke 14.34,35)</para>
<para style="p">
  <verse number="13" style="v" />“You are like salt for the whole human race...</para>

<table>

ico_R Schema pattern name: Table

Element:table
empty
Added:1.0
Use:Contains <row> and <cell> child elements which compose the structure of a USX <table>. Tables are composed of a vertical sequence of one or more rows. Rows are composed of a horizontal sequence of one of more cells.
Valid in:Book Introduction, Chapter Text
Parents:<usx>

Diagram

../_images/usx-element_table.png

<row>

Element:row (* within <table>)
empty
Added:1.0
Use:Contains a horizontal sequence of table <cell> elements. The horizontal position of a table cell relates to its corresponding table column.
Valid in:Any valid <table>
Parents:<table>

<cell>

ico_R Schema pattern name: TableContent

Element:cell (* within usx-element_row)
xsd:string
Added:1.0
Use:Table cell content. Contains the cell text and and child elements.
@style:Cell column and alignment (legacy). *
th# | thr# | tc# | tcr#
The variable represents the table column number. See “About cell @style” note below.
@align:Cell alignment. *
start | center | end
Represents “left”, “center”, and “right” respectively in left-to-right direction texts, and “right”, “center”, “left” in right-to-left direction texts.
Valid in:Any valid <row>
Parents:<row>

Note

Like the @style attribute applied to other USX elements, the cell @style value is a reference to the source text USFM marker in Paratext, from which USX encoded text is often derived. In USFM text, the table cell markers define the column to which they belong. The variable # represents the table column number. Strictly speaking @style is redundant information in USX. It is used by Paratext for round-tripping USX to USFM. In USX, the position of a <cell> in its sequence defines its respective column, and the @align attribute is the primary source of cell alignment information.

Diagram

../_images/usx-element_cell.png

Sample

NUM 2:3-9

<table>
  <row style="tr">
    <cell style="th1" align="start">Tribe </cell>
    <cell style="th2" align="start">Leader </cell>
    <cell style="th3" align="start">Number</cell>
  </row>
  <row style="tr">
    <cell style="tc1" align="start">Judah </cell>
    <cell style="tc2" align="start">Nahshon son of Amminadab </cell>
    <cell style="tcr3" align="end">74,600</cell>
  </row>
  <row style="tr">
    <cell style="tc1" align="start">Issachar </cell>
    <cell style="tc2" align="start">Nethanel son of Zuar </cell>
    <cell style="tcr3" align="end">54,400</cell>
  </row>
  <row style="tr">
    <cell style="tc1" align="start">Zebulun </cell>
    <cell style="tc2" align="start">Eliab son of Helon </cell>
    <cell style="tcr3" align="end">57,400</cell>
  </row>
  <row style="tr">
    <cell style="tc1" align="start" />
    <cell style="tc2" align="end">Total: </cell>
    <cell style="tcr3" align="end">186,400</cell>
  </row>
</table>

<char>

ico_R Schema pattern name: Char

Element:char
xsd:string
Added:1.0
Use:An element for marking character level content types within para, table cell and note elements.
@style:Content type. *
Permitted values vary for each document division. The char @style types list presents an itemization of style values by category and indicates the document divisions in which each type is valid.
Valid in:Book Titles, Book Introduction, Introduction End Titles, Book Chapter Label, Chapter Text
A limited subset of @style types are valid within note (Footnote, CrossReference)
Parents:<para>, <cell>, <note>

Diagram

../_images/usx-element_char.png

Sample

<para style="ip">The name <char style="bk">Genesis</char> means “origin.”

Then the <char style="nd">Lord</char> God took some soil from the ground and formed a man

<para style="p">
  <verse number="1" style="v" />This is the Good News about Jesus Christ, the Son of God.
  It began as the prophet Isaiah had written:</para>
<para style="q1">
  <char style="qt">“God said, ‘I will send my messenger ahead of you</char></para>
<para style="q2">
  <char style="qt">to open the way for you.’</char></para>
...

<note>

The USX note element is used to contain the content for any footnotes or cross references content. Different note types are distinguished by the note @style attribute. The content for each note type is marked using <char> with a specific subset of @style types for the chosen note type. To help make things clear in this document, the markup for footnotes and cross references are described in separate sections because they use different char @style types within them.

ico_See See: <note> Types

<figure>

ico_R Schema pattern name: Figure

Element:figure
xsd:string
Added:1.0
Use:Definition for an illustration which could be formatted at or near to this location in a publication.
The element’s text content is the caption for the illustration.
xsd:string
@style:Content type. *
fig
@desc:Illustration description. This text is not normally rendered within a publication. *
xsd:string | empty
@file:Illustration filename or URI. *
xsd:string | empty
@size:Illustration relative size. *
col | span | <user defined> xsd:string | empty
col - Illustration should be inserted inline within the space for the current text column.
span - Illustration should be inserted across (spanning) all text columns (i.e. the maximum available page or screen width).
@loc:Illustration location/range. *
xsd:string | empty
@copy:Copyright information. *
xsd:string | empty
@ref:Illustration reference. This text will commonly be rendered together with the illustration caption. * xsd:string | empty
Valid in:Book Introduction, Chapter Text
Parents:<usx>

Diagram

../_images/usx-element_figure.png

Sample

<figure style="fig" desc="" file="avnt016.jpg" size="span" loc="" copy="" ref="1.18">
        At once they left their nets.</figure>

<optbreak>

Element:optbreak
empty
Added:2.0
Use:Discretionary (optional) line break location.
Primarily used in poetic text, but could also be used for marking optional breaks for titles, headings, or table <cell> content.
Valid in:Book Titles, Book Introduction, Introduction End Titles, Book Chapter Label, Chapter Text
Parents:<para>, <cell>

Sample

<para style="s1">Jesus Heals a Man <optbreak /> Who Could Not Walk</para>

<ref>

Element:ref
Added:2.0
Use:Scripture reference.
When <ref> is used with a USX encoded text, each segment of a scripture reference should be wrapped in a <ref> element.
xsd:string
@loc:A parsable (machine-readable) representation of the vernacular text for the scripture reference. Book names must be one of bookCode. Chapter verse separator is always a colon (:).
Valid in:
Parents:

Diagram

../_images/usx-element_ref.png

Sample

<ref loc="MAT 3:1-4">Mt 3.1-4</ref>,<ref loc="MAT 3:7-13">7-13</ref>
<ref loc="MAT 3:4-4:5">Mt 3.4—4.5</ref>
<ref loc="LUK 3-5">Lk 3—5</ref>
<ref loc="MAT-LUK">Mt—Lk</ref>
<ref loc="MAT 3:4-5:6">Matthew 3.4—5.6</ref>; <ref loc="LUK 7">Luke 7</ref>

Sample Details

Example:

<char style="xt">Mt 3.4-5</char>

becomes:

<char style="xt"><ref loc="MAT 3:4-3:5">Mt 3.4-5</ref></char>

Comma-delimited verses and chapters are split up as much as possible:

Example:

Mt 3.4-5,6

becomes:

<ref loc="MAT 3:4-3:5">Mt 3.4-5</ref>,<ref loc="MAT 3:6">6</ref>

Example:

Mt 3.4-5.7

becomes:

<ref loc="MAT 3:4-5:7">Mt 3.4-5.7</ref>

Chapter ranges are acceptable:

Example:

Mt 3-5

becomes:

<ref loc="MAT 3-5">Mt 3-5</ref>

Book ranges are encoded as first reference only:

Example:

Mt-Lk

becomes:

<ref loc="MAT">Mt-Lk</ref>