The OSIS Website
"A Common Format for Many Visions"

OSIS™ 2.0 User's Manual (draft)

Bible Technologies Group

OSIS™ 2.0.1 User's Manual (draft)


Draft Version of OSIS User's Manual

Note the updated schema and users manual number. One of our users already spotted a bug and it has been corrected. Make sure the schema and users manual you are consulting correspond in the numbering.

As you go through this guide to the OSIS 2.0.1 schema, you are going to notice mistakes, omissions and examples you don't find useful. Those were not left as an exercise for the reader.

The editors discussed having a registry of Bible verses for people who contribute corrections, supply omissions or examples but feared that there might be more corrections, supplied omissions or examples than there are verses in the Bible. Not to mention that some verses are more popular than others.

So, as an alternative, future versions of the OSIS User's Manual will have a Contributor's section, which will list your name and the number of corrections or supplied omissions/examples that you have contributed to the manual. Counting by the editors will be final but generous and credit given for duplicates or suggestions not ultimately used in the form submitted. Please specify if you want your email contact information included as well. Address your comments, corrections, supplied omissions/examples, to osis-editors@bibletechnologieswg.org.

This manual is meant to be a guide for all users of the OSIS schema and your assistance will be appreciate both by the editors as well as the community of OSIS users.

Contents

1. Introduction to OSIS™

Welcome to the OSIS (Open Scriptural Information Standard™) User's Manual. OSIS is a set of XML structures that can be used to produce Bibles, commentaries, and related texts that can be easily interchanged with other users, formatted as HTML, PDF, Postscript or any other desired format, and searched on any personal computer. It provides a standard way to express such documents, which is important because it saves time, money, and effort for:

  • authors, who will have less need to adjust their manuscripts for each different potential publisher;
  • publishers, who will gradually come to experience lower costs by not having to manage converting texts presented by authors in so wide a variety of formats, and by not having to provide texts in a different form to each electronic-book system vendor out there (or pay indirectly for those vendors to do the conversions).
  • and software vendors, who can avoid writing a lot of code to manage different formats, and thus make their programs smaller, faster, and more reliable.

The OSIS development team closely studied previous Bible encoding forms, as well as tools for literary encoding in general. By doing this we hope we have avoided some weaknesses, and gained from some strengths, of each one, and we thank the many people who worked on those prior specifications, as well as those who have provided help and feedback in developing OSIS itself, and testing it by encoding large numbers of Biblical and related texts. A list of participants may be found in an Appendix.

Users familiar with the Text Encoding Initiative will find OSIS markup quite familiar, because the bulk of the elements we define correspond directly to TEI elements, and almost always have the same name (though often simplified content). The schema also provides a TEIform attribute for such elements, so they can be recognized by form-aware processors as equivalent to their TEI counterparts. We have attempted to point out any elements below that do not have TEI equivalents, for the sake of anyone using both systems.

OSIS is provided as a free resource by the Bible Technologies Group™ (or BTG™), which is a collaborative effort of the American Bible Society, the Society of Biblical Literature, the Summer Institute of Linguistics, the United Bible Societies, other Bible Societies and related groups, and individual volunteers around the world. OSIS is designed to meet the needs of diverse user communities who read, study, research, translate or distribute biblical texts. This introduction gives a brief overview of OSIS before leading you step by step through producing your first OSIS text.

For more information on OSIS, you may wish to join the OSIS Users' Group. To do so, send mail to osis-user@whi.wts.edu, setting the Subject line to "subscribe". Online information about OSIS is also available at http://www.bibletechnologies.org and http://www.bibletechnologieswg.org.

2. Getting started

The first question that is often asked when learning that OSIS uses XML (a markup language) is: "I'm not a computer person. Can I learn to use OSIS?" If you can type and use even the most basic word processor or computer text-editing program, the answer is clearly "Yes!" OSIS was designed to be offer the beginning user a simple way to do the basic "markup" required for a standard biblical text. "Markup" refers to markers placed within the text, that indicate where useful units (or "elements") such as verses, quotations, cross-references, and other things begin and end.

If you know HTML, you already know most of what you need to know to use OSIS; OSIS uses the same pointy-bracket syntax as HTML (or XHTML to be completely precise). It merely provides a different set of element and attribute names. A few names such as "p" and "div" are the same; others are new, such as "verse". The core set of elements for OSIS is actually smaller than the set for HTML 3.2. To be sure, there are some complex cases that we deal with later, but you can do useful work with no more information than is provided in this basic manual.

The second question that is most often asked is: ‘Do I need an XML editor to do OSIS?’ This question often comes up after a friend of a friend has recommended some editor, and you then checked its price. XML editors vary from free to over $10,000.00 (US), and many are difficult to use (though XMetal™ is a notable exception, and not very expensive).

The basic answer is no, you do not need any special software. You can use any text editor you like to create OSIS documents (or any other XML documents, for that matter). Many will even color the tags for you, because they know how to color HTML tags and the languages are similar enough. However, you should have a way to check your documents for errors -- if your editor doesn't know enough about XML to warn you if you misspell a tag, or forget to end some element that you started, you will want to check for errors periodically using an "XML validator". Many such program are available for various computers; some are available as Web services. (See Appendix, Validating Your OSIS Document for pointers and instructions on web based validation services.) Both Internet Explorer and Netscape can also validate an OSIS file once you have installed the OSIS rules file (called a "schema") and an appropriate stylesheet.

An OSIS-aware text editor will do this checking for you, either on demand or continuously. A friendlier OSIS-aware text editor will provide help by showing you just which elements are permitted at any given place. The friendliest editors also give you the option to see and edit a fully-formatted view on demand, rather than staring directly at pointy-brackets. The choice between the many tools is a personal one, dictated by your working style, level of technical sophistication, goals, budget, and other factors.

3. Some authoring tools

The OSIS team is working even as this manual is being written to adapt free authoring tools that will hide most if not all of the markup from the casual user of OSIS. In the meantime, the best way to learn OSIS is to use a simple text editor, such as WordPad or Kedit on Windows, BBEdit or Alpha on MacOS, or vi or emacs on Linux. You can even use a word processor, though any formatting that you do in it won't matter (you would simply save the file as "text only").

The examples in this manual have been kept deliberately short and can be downloaded as a package from the OSIS website. After you have gained some basic skill using OSIS, you may want try out more sophisticated editors.

Editing is much easier with an editing program that is aware of XML rules in general, and OSIS in particular. For example, rather than seeing literal tags with pointy-brackets, you can have a choice of seeing that, or structural views of your document (say, as a tree or expandable outline), or fully-formatted views to facilitate print layout.

Many products are available that can help you edit XML documents. One style shows the literal XML source file, but colors tags, attributes, and other things to make them stand out. Most such programs also read an XML schema and ensure that you only insert elements and attributes are permitted by the OSIS schema (schemas, such as the OSIS one, declare what elements and attributes are permitted where in documents of a particular kind). One free and helpful tool of this kinds is jEdit, which runs on most platforms. It can be set up to know about many kinds of files, including XML files, and OSIS in particular.

With such an editor, you can see or print a basic a formatted view by using most any Web browser. Later in this manual are instructions for setting up an OSIS file with a style sheet (generally in CSS) so that typical browsers can deal with it.

There are also more word-processor-like XML editors, which primarily show a formatted view defined by some style sheet. These are mainly commercial. XML Spy is one such tool (see http://www.xmlspy.com/); XMetal (see http://www.corel.com/servlet/Satellite?pagename=Corel/Products/productInfo&id=1042152754863) is another.

For high-end layout and typesetting from XML source files, usually a stylesheet language called XSL-FO is used. Two of the more popular commercial XSL-FO solutions are 3b2 (see http://www.3b2.com/), and Antenna House (see http://www.antennahouse.com/). Non-XML-based composition systems such as Quark™ and TeX generally have ways to import XML, but using them for XML composition requires substantial expertise and effort.

4. Your First OSIS Document

Like HTML documents, an OSIS document starts with a header, and then goes on to the actual text content. The header identifies the file as being XML, and as using the OSIS schema. It also provides places to declare a bibliographical description of the work and of any other works cited; and a place to record a history of editing changes. Here is a short, but valid, OSIS document:

<?xml version="1.0" encoding="UTF-8"?>
<osis xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">
<osisText osisIDWork="thisWork" osisRefWork="bible" xml:lang="en-US">
<header>
<work osisWork="thisWork">
<title>Contemporary English Version</title>
<type type="OSIS">Bible</type>
<identifier type="OSIS">Bible.en.CEV.1995</identifier>
<rights type="x-copyright">Copyright 1995 American Bible Society</rights>
<scope>Esth.1.1-Esth.1.4</scope>
<refSystem>Bible</refSystem>
</work>
<work osisWork="bible">
<type type="OSIS">Bible</type>
<refSystem>Bible</refSystem>
</work>
</header>
<div type="section" scope="Esth.1.1-Esth.1.4">
<title>Queen Vashti Disobeys King Xerxes</title>
<p>
<verse sID="Esth.1.1-Esth.1.2" osisID="Esth.1.1 Esth.1.2" n="1-2"/>
King Xerxes of Persia lived in his capital city of Susa and ruled one
hundred twenty-seven provinces from India to Ethiopia.
<verse eID="Esth.1.1-Esth.1.2"/>
<verse sID="Esth.1.3" osisID="Esth.1.3"/>
During the third year of his rule, Xerxes gave a big dinner for all
his officials and officers. The governors and leaders of the provinces
were also invited, and even the commanders of the Persian and Median
armies came.
<verse eID="Esth.1.3"/>
<verse sID="Esth.1.4" osisID="Esth.1.4"/>
For one hundred eighty days he showed off his wealth and spent a lot
of money to impress his guests with the greatness of his kingdom.
<verse eID="Esth.1.4"/>
</p>
</div>
</osisText>
</osis>

5. XML and OSIS declarations

The first several lines of any OSIS document will generally be identical:

The first line above identifies the document as being XML; this is required in exactly the form shown, and enables computers to identify how to process the rest of the document.

The second through third lines are a very long start-tag for the outermost OSIS element, which is called "osis." All elements in an OSIS document must be declared within the OSIS namespace. There are two ways to achieve this and other than remembering to pick one of the two following methods, that is all you need remember about it to start encoding texts using OSIS 2.0.

OSIS Namespace, Method 1: Copy the following lines just after <?xml version="1.0" encoding="UTF-8"/>:

<osis xmlns="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">

OSIS Namespace, Method 2: Copy the following lines just after <?xml version="1.0" encoding="UTF-8"/>:

<osis:osis xmlns:osis="http://www.bibletechnologies.net/2003/OSIS/namespace"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bibletechnologies.net/2003/OSIS/namespace osisCore.2.0.1.xsd">
Note with the second method, the last closing element must be: </osis:osis>. The first method is simpler but both are legitimate.

At this point, the OSIS document has begun. This sample is a single document rather than a collection of documents, so the next element opened is osisText:

<osisText osisIDWork="CEV" osisRefWork="Bible" lang="en">

Every osisText needs to supply an osisIDWork attribute and value. The value will generally be the short name of what is being encoded, in this case the Contemporary English Version, or CEV. The short name is defined in the work declaration for the work, described later. The work element that identifies the work being encoded should be the first work element, if the text has more than one. This sets things up for some of the later elements nested within the osisText element. One such element is work. It requires an osisWork attribute. That attribute's value has to be the same as the value found on the osisIDWork attribute of osisText (see line 7 of the sample). Other elements use/require an osisID attribute which refer back to the osisIDWork attribute of osisText (see lines 19 and 21 of the sample).

Every osisText also needs to specify what reference or versification scheme any osisRefs within it refer to. This may or may not be the same work. Depending on how finely you distinguish things, there are several major versification traditions, and countless fine-grained variations. For the present, we identify and reserve names for these major traditional reference systems:

  • NRSVA New Revised Standard Version with Apocrypha
  • NA27 Nestle-Aland, 27th Edition of the Greek New Testament
  • KJV King James Version or Authorized Version (AV)
  • LXX Septuagint
  • MT Masoretic Text. Hebrew tradition varies in several respects, the best known being that it numbers what is given as a title for Psalms in most English translations as verse 1,and the beginning of the psalm in such a translation as verse 2.
  • SamPent the Samaritan Pentateuch used a quite different numbering system.
  • Synodal Russian
  • Vugl Vulgate
  • Loeb This system is used for most classical literature, though many major works have other systems as well.

OSIS is developing a schema for declaring versification systems formally, and for declaring some systems in terms of others. This will enable programs to map between systems. However, at this time we merely reserve the names above for some systems we know to be substantially different and important.

6. Canonical vs. non-canonical parts of a work

The element osisText has one other important attribute that is not shown above. It is called "canonical", and always has a value of "true" or "false". When true, it asserts that the content is a part of the text being encoded. For example, the "text" of the Bible includes the content of books, chapters, and verses but does not include notes, section-headings added by editors or translators, etc.

The canonical attribute is available on all elements. Its value inherits in the same manner as xml:lang. Because of this inheritance, encoders will seldom need to make this attribute explicit. In osisText this attribute is set to a default value of "true", while header, note, and reference that setting is overidden by setting the value of that attribute to be "false."

In books other than the Bible, a similar distinction holds: the text proper of Herodotus' Histories must be contained in elements with canonical="true", while notes, header data, and the like must not.

The meaning of this attribute is limited. It must not be used to encode interpretive or theological judgements about canonicity. For example, encoders who include the apocryphal books of the Bible, or the alternate longer ending to the Gospel of Mark, must mark them as canonical (whether by default or explicitly). This is simply because they are part of the text being encoded. Users of a text are never justified in drawing conclusions about a translator's, editor's, or encoder's position on questions of inspiration or other theological questions based on how they set the canonical attribute, because the attribute does not mean that.

In most cases use of the canonical attribute is straightforward, and we expect that the default values will almost always produce the intended result. However, there will arise truly difficult cases: for example, one may be encoding an ancient text with annotations of its own. In that case those notes would be canonical, while any added by the current editor would not be. In such cases, the practice chosen and its rationale should be described in the work's documentation.

7. The OSIS text header

The first element within every osisText must be a header. The header declares various works (including the work being encoded and any that are being referenced), and provides a place to keep a revision history of the text.

7.1. The Revision Description

To record changes or edits to the text, authors and editors are encouraged to insert a change element every time significant editing is done. Each change element should contain a date element which says when those edits were completed, in the form

yyyy-mm-ddThh:mm:ss

Note that all fields must have exactly the number of digits shown (4-digit year, 2-digit month, etc.). It is permissible to omit the time and the preceding "T", thus giving just a date. For example, December 25th of 1999 CE would be:

1999-12-25

A date element in the revision description is followed by any number of p (paragraph) elements, in which the changes made are summarized. The person responsible for making the changes should also be identified, using the resp attribute on the change element.

Recommended practice is that more recent change elements appear earlier in the document. That is, entries should occur in reverse chronological order. For example:

<change><date>2003-09-11</date>
<p>sjd: Filling in the gaps. Adding some info for 2.0 as defined
at the Calvin College meetings.</p>
</change>
<change><date>2003-07-01</date>
<p>sjd: Annotated alpha list of elements. Reworked reference and
work sections and added type, scope, and explanations of type and
subtype for work. Explained more elements and attributes.</p>
</change>
<change><date>2003-06-17</date>
<p>sjd: Wrote conformance section. Added lists of elements and
attributes, USMARC list. Inserted placeholders for doc on all element
types. Got document back to XML WF. Wrote CSS stylesheet.</p>
</change>

7.2. Work Declarations

A work element is a declaration. It provides information comparable to that found on the title page of a printed work, using the fields defined by the Dublin Core Initiative (see http://dublincore.org/).

The work element serves two purposes. The work element in the header with an osisWork attribute that matches the osisIDRef in the osisText element identifies the work in which it occurs -- much like the title page in a printed work. For example:

<osisText osisIDWork="CEV" osisRefWork="Bible" lang="en">
<header>
<work osisWork="CEV">

Note that the match between osisIDWork="CEV" in osisText and osisWork="CEV" in the work element links this osisText to this particular work element.

Subsequent work elements identify other works -- much like a citation in a footnote or bibliography in a printed work. Each assigns a local name to each one, using the osisWork attribute. Works so declared can then be referred to from osisIDs or osisRefs throughout the text. For Bibles, this should generally be the accepted acronym or abbreviated form of the translation's name (some standard version abbreviations are listed in an appendix). No periods, hypens, spaces, or colons are allowed in short names.

Note: This mechanism of declaring a short name and using it later as a prefix, is very similar to the XML Namespace mechanism defined at http://www.w3.org/TR/xml-names11/.

7.3. The Dublin Core

Each work element describes a single publication using several pieces of information, primarily title, creator, date, publisher, identifier and language. All of the standard "Dublin Core" fields may be used, plus a few OSIS-specific additions (further information on the Dublin Core system may be found at http://www.dublincore.org). All of the Dublin core fields may be repeated as necessary, but must be encoded in the order shown here. For example:

<work osisWork="EG">
<title>Egyptian Grammar</title>
<creator role="aut">Alan Gardiner</creator>
<contributor role="dte">Francis Llewellyn Griffith</contributor>
<date event="original" type="gregorian">1927</date>
<date event="eversion" type="gregorian">2003</date>
<type type="x-grammar">Grammar</type>
<publisher>Griffith Institute, Ashmolean Museum, Oxford</publisher>
<language type="ISO-639">EN</language>
<language type="Ethnologue">EG-ancient</language>
<identifier type="ISBN">0900416351</identifier>
<identifier type="LCCN">95230980</identifer>
</work>
<work osisWork="CPV">
<title>Cotton Patch Version of Luke and Acts: Jesus' Doings and
the Happenings</title>
<creator role="aut">Clarence Jordan</creator>
<date event="original" type="gregorian">1969</date>
<date event="eversion" type="gregorian">2003</date>
<type type="x-bible">Bible</type>
<publisher>Association Press
<name type="place">New York, NY</name></publisher>
<language type="ISO-639">EN</language>
<identifier type="ISBN">0809617250</identifier>
<identifier type="LCCN">69-18840</identifer>
<scope osisRef="Luke" />
<scope osisRef="Acts" />
</work>

7.3.1. title

A title element must be provided in the work element and contain the main title of the work. Additional titles may also be specified, using the type attribute to identify them as main, sub, part, monographicSeries, or another kind of title. No OSIS-specific types are established for this type attribute.

7.3.2. creator

The creator element is used to specify the person(s) or organization(s) who are primarily responsible for the intellectual content of a work. The role attribute must specify the particular role the primary responsible party played. The most common values would be aut (author), edt (editor), cmm (commentator), trl (translator). A short list of such codes appears in Appendix D: Contributor Roles, with the complete set being found in Appendix G: USMARC Relator Codes This list covers an enormous range, and it should seldom if ever be necessary to use a code not from this list.

7.3.3. contributor

Many people may contribute to a work in roles other than the primary role listed under creator. They should be listed using the contributor element. Their specific role should be recorded in the role attribute of their contributor element. See Appendix G: USMARC Relator Codes for the complete list of role codes provided by the USMARC organization.

7.3.4. date

Date elements in the work element record significant dates in the production or publication process. Use the role attribute to identify the particular date contained in each of the date elements. Those defined roles are:

  • original The original publication date of the first edition
  • edition The date of publication of the referenced or source edition
  • imprint The printing date of the referenced or source edition
  • eversion The revision date of the present electronic edition

The type attribute is used, instead, to identify the calendrical system in which the date is expressed, from the list: Chinese, Gregorian, Islamic, ISO, Jewish, and Julian. At this time, OSIS only defines a syntax for Gregorian dates: yyyy:mm:dd. See the later section on "Date Formats".

7.3.5. publisher

The publisher element in the work element is used to indentify the publisher of a particular work. If a work was published by more than one publisher and that publication record needs to be recorded, use multiple publisher elements and distinguish them using the type attribute. The description given in this attribute is not constrained but it is suggested that values that tie a publisher to a particular edition, such as <publisher type="1848Edition"> should be used. For cases where full identification of a publication history is essential, use of multiple work elements is suggested.

7.3.6. language

A language element must be provided for each language used substantially in a work. The language may be specified using an ISO 639 or ISO 639-2, or SIL Ethnologue codes. The type attribute must be set to IANA, IETF, ISO-639-1, ISO-639-2, ISO-639-2-B, ISO-639-2-T, LINGUIST, or SIL. In the rare case that none of these is sufficient, a prose description should be inserted in the element and the type attribute set to other.

7.3.7. type

The nature or genre of the content of the resource. This element includes terms describing general categories, functions, genres, or aggregation levels for content. Dublin Core's recommended best practice is to select a value from a controlled vocabulary (for example, the DCMI Type Vocabulary -- see http://dublincore.org/documents/dcmi-type-vocabulary/). OSIS does not provide such a controlled vocabulary at this time. If you encode this element, the controlled vocabulary in use should be identified via the type attribute (for example, <type type="DCMI">). To describe the physical or digital manifestation of the resource, use the format element instead.

Note that the Dublin Core type element is distinct from the OSIS type attribute (the latter can occcur on any OSIS element, to distinguish relevant subdivisions of the type).

7.3.8. identifier

The identifier elements provide one or more formal identifiers for the work. The values to be entered for the type attribute on the identifier element are shown in bold. Note that these values must be entered exactly as shown. XML is case sensitive, that is to say, DEWEY is not equal to Dewey. Enter the latter one and you will get an error message.

  • DEWEY Dewey Decimal System
  • DOI Digital Object Identifier
  • ISBN International Standard Book Number
  • ISSN International Standard Serial Number
  • LCCN Library of Congress Control Number
  • OSIS Open Scriptural Information Standard
  • SICI Serial Item and Contribution Identifier
  • URI Uniform Resource Identifier
  • URL Uniform Resource Locator
  • URN Uniform Resource Name

ISBN and LCCN numbers must be recorded without spaces or hyphens. ISBNs must contain ten digits (that is, they must include the final check digit).

We strongly recommend the assignment of an ISBN to each published work using OSIS. This number must, if available, be specified in the identifier field for the work.

The following examples show identifier elements used along with their type attribute to provide an identifier for a work, in this case, the "Cotton Patch Version of Luke and Acts" noted above:

<identifier type="ISBN">0809617250</identifier>
<identifier type="LCCN">69-18840</identifer>
Note that without the proper type attribute, a reader or computer only has a string of numbers, which could be from almost any system of identifiers. The type attribute plays an important role in making sure the information you so carefully record is understandable to others or even yourself, after a few months have lapsed since you looked at the text.

7.3.9. coverage

This element may be used to specify the spatial location (a place name or geographic coordinates), temporal period (a period label, date, or date range) or jurisdiction (such as a named administrative entity) to which the work applies. For example, an edition of Herodotus could be specified as Greek/Hellenic, Classical Period. Or a study of medieval Bibles could declare coverage as "medieval".

7.3.10. description

An account of the content of the resource.

Examples of description include, but are not limited to: an abstract, table of contents, reference to a graphical representation of content or a free-text account of the content.

7.3.11. format

The physical or digital manifestation of the resource.

Typically, format may include the media-type or dimensions of the resource. Format may be used to identify the software, hardware, or other equipment needed to display or operate the resource. Examples of dimensions include size and duration. Recommended best practice is to select a value from a controlled vocabulary (for example, the list of Internet Media Types [MIME] defining computer media formats).

7.3.12. relation

A reference to a related resource.

Recommended best practice is to identify the referenced resource by means of a string or number conforming to a formal identification system.

7.3.13. rights

Information about rights held in and over the resource.

Typically, rights will contain a rights management statement for the resource, or reference a service providing such information. Rights information often encompasses Intellectual Property Rights (IPR), Copyright, and other property rights. The rights element is informative only. Legal rights and penalties for violation of those rights vary from jurisdiction to jurisdiction. Reuse of any resource should be done only after obtaining the necessary rights and permissions or ascertaining that none is required.

7.3.14. subject

A topic of the content of the resource.

Typically, subject will be expressed as keywords, key phrases or classification codes that describe a topic of the resource. Recommended best practice is to select a value from a controlled vocabulary or formal classification scheme.

7.3.14.1. subject classification systems

The type attribute on subject allows the user to specify what classification system the subject entered can be found.

<subject type="ATLA">Fathers of the Church</subject>

Means that the subject "Fathers of the Church" is a subject found in the listing of subjects maintained by the American Theological Libraries Association (ATLA). To assist users, an admittedly partial list of the more well known subject classification systems have been prepared by the OSIS project. Those systems with their abbreviations for use with an OSIS encoded text are as follows:

  • ATLA American Theological Libraries Association
  • BILDI Biblewissenschaftliche Literaturdokumentation Innsbruck
  • DBC Dutch Basic Classification
  • DDC Dewey Decimal Classification
  • EUT Estonian Universal Thesaurus
  • FGT Finnish General Thesaurus
  • LCSH Library of Congress Subject Heading
  • MeSH Medical Subject Headings
  • NLSH National Library Subject Headings (National Library of Poland)
  • RSWK Regeln für den Schlagwortkatalog
  • SEARS Sears List of Subject Headings
  • SOG Soggettario
  • SWD_RSWK Swiss National Library
  • UDC Universal Decimal Classification
  • VAT Vatican Library

For classification systems not listed, insert the classification system with a leading "x-" in the type attribute and notify the OSIS team if that system should be added in a future revision of the schema.

7.3.14.2. source

A reference to a resource from which the present resource is derived.

The present resource may be derived from the source resource in whole or in part. Recommended best practice is to identify the referenced resource by means of a string or number conforming to a formal identification system.

7.3.14.3. type

The nature or genre of the content of the resource.

Type includes terms describing general categories, functions, genres, or aggregation levels for content. Recommended best practice is to select a value from a controlled vocabulary (for example, the DCMI Type Vocabulary [DCT1]). To describe the physical or digital manifestation of the resource, use the format element.

7.3.15. Non-Dublin Core Elements and Attributes in the Work Declaration

7.3.15.1. scope

The scope element(s) must have an osisRef attribute, which defines what part of the titled work occurs in this electronic edition. For example, an edition may consist of only the New Testament and Psalms, or of only a single book. Contiguous ranges may be specified using the hyphen notation described later for osisRefs in general; discontiguous ranges must be specified by including multiple scope element(s), as shown in the second example above. These should be, but are not required to be, in canonical order.

7.4. Identifying a Work given a work declaration element

The six elements already described are the primary means of identifying a referenced work.

If a publication matches all of the above elements within work, it is presumed to be an acceptable resolution for any reference to that work as declared.

If no perfect match can be found, applications may, indeed should, attempt to fall back to the closest available publication. OSIS does not define a required method of fallback, or define what "closest" must mean in all contexts. However, one possible approach is to successively ignore particular elements in this order:

  • Identifier: because identifiers are often ambiguous. For example, hardcover and softcover editions of a book typically have different ISBNs, and occasionally publishers re-use an old ISBN for a completely different book.
  • Date: because a different imprint or edition of the same conceptual work is typically adequate. Precisely targeted links, however, may not refer to the exact location desired. Applications may wish to ignore all dates except for the original publication date.
  • Publisher: because several publishers may publish a given work (particularly older works), publishers may change name, etc.
  • Language: Accepting a publication that does not match in language is a substantial concession. However, some variations of language are greater than others. For example, some modern Bible translations are available in separate American and British English versions, and substituting one for the other is not unreasonable. This is particularly true because translations generally use translated titles as well, and so if the language is not closely related, the title will probably not match either. Applications may wish to encode some knowledge of language and dialect similarities to implement more sophisticated fallback.
  • Creator: because some authors have multiple forms of name: St. Augustine vs. Augustine of Hippo vs. Augustine. The Bible Technology Group intends to develop an authority list of normative name-forms for relevant authors, and once such a list is available, using it will help to avoid such problems. As with other elements, more sophisticated applications may wish to attempt some kind of approximate matching in order to achieve better fallback.
  • Title: the final item to discard is probably title. If a work's title differs, it is probably a different work, or at least a translation into a non-close language. On the other hand, some titles have been used by multiple authors, and so a match on title alone should be considered suspect.

Arguments can easily be made for a variety of other fallback methods. For example, if the identifier element matches, the work is probably right, even though an identifier mismatch is not good evidence that the work is wrong.

7.5. Date formats

All dates in the header and in attributes should be in this standard format, which is based on IETF RFC 3339. However, it uses period rather than colon as the field separator (for consistency with other OSISis types), and adds features to allow for dates BCE, for approximate dates, for date ranges, for yearless dates (as used in many daily devotionals), for weekly dates, and for named times of day (such as used in many prayer books). There are 3 standard date formats; the prefixes that identify them are reserved, and may not be redefined via the refSysId attribute of any work element:

  • yearly:yyyy-mm-ddThh.mm.ss

    Any number of fields may be left off from the right end; for example, if the seconds are dropped (along with the preceding colon), the time refers to the entire minute specified; if the entire time section is left off (along with the preceding "T"), the string refers to the entire day.

    The year must always have 4 digits. However, the year may be entirely omitted to indicate dates that apply to any year, such as in a book of 365 daily readings.

    To indicates years before the common era, add an underscore ("_") before the first digit of the year (immediately following the colon). A hyphen would be preferable, but it is already in use to indicate ranges in osisRefs.

    The entire date/time string (possibly including a leading underscore) may be preceded by "~", indicating that the time is approximate. No means is provided to express just how approximate a time may be.

  • weekly:n

    When readings or other materials are specified as being for particular days of the week, this form must be used. The 'n' value may range from 1 to 7; 1 indicates Monday, in accordance with ISO 8601:2000.

As an alternative to quantitative times, a small set of named times is provided, which can be specified in place of the entire (post-"T") time section (the "T" itself remains). For example:

yearly:06-04T~(Vespers)

would be the identifier for a prayer, reading, or other work to be used at Vespers on June 4 of any year. The named times (which are case-sensitive) include: Vigils, Matins, Lauds, Terce, Sext, None, Vespers, Compline; Sunrise, Sunset; Morning, Afternoon, Evening, Night; AM, PM; Fajr, Zuhr, _Asr, Maghhrib, _Isha, Lail, Dzuha, _Id.

Some works will be primarily organized by dates and times: for example, lectionaries, daily devotionals, prayer books, historical time lines, etc. In such works, use the osisID attribute to identify the retrievable portions; the value should the the applicable time in one of the formats just shown.

Typically, such works are organized in chgronological order of the times specified; however, OSIS does not impose that requirement.

8. Title Pages

In order to make the encoding of title pages as found in standard works easier, OSIS 2.0 introduced the titlePage element. This element contains the following elements from the header: title, contributor, creator, subject, date, description, publisher, type, format, identifier, source, language, relation, coverage, which are explained in the material on the header section. Three additional elements are allowed, which are figure, milestone, and, p. Due to the complexity of title pages, all of these elements may occur in any order inside the titlePage element.

The titlePage element can occur within the osis, osisText, and, osisCorpus elements.

Users just starting with OSIS should use a minimum headers and simple titlePage element until they have gained some experience with text encoding and determining what is, or perhaps more importantly, what is not useful to have encoded in a work.

9. Basic Elements

While book, chapter, and verse numbers are a familiar and useful way of referring to locations in the Bible, they often conflict with the boundaries of parables, stories, genealogies, paragraphs, quotations, and other important units of understanding. Even to print a well-formatted Bible edition, and much more to support high-end search, annotation, and other capabilities, these meaningful units must also commonly be marked.

It is possible to encode a Bible using only book, chapter, and verse markup. However, most encoders also want to also represent sections, paragraphs, quotations, and so on. Higher-level structures are tagged as div, for "division", with a type attribute to specify the particular significance. div elements can occur within other div elements to any number of levels. The first and outermost div should occur immediately after the end of the header. For example,

<div type="book" osisID="Gen">
<head>Genesis</head>
<chapter osisID="Gen.1">
<head>1</head>
<verse osisID="Gen.1.1">In the beginning,...</verse>
<verse osisID="Gen.1.2">The earth was formless and void...</verse>
...
</chapter>
</div>

The div element is used for many top-level components, and so makes heavy use of the type attribute. The pre-defined types include the most common major divisions found in present-day Bibles and related works:

acknowledgement, afterword, annotant, appendix, article, article, back, body, book, bookGroup, chapter, colophon, commentary, concordance, coverPage, dedication, devotional, entry, front, gazetteer, glossary, imprimatur, index, introduction, majorSection, map, outline, paragraph, part, preface, section, subSection, titlePage. ’

The main body of a Bible will typically consist of div elements of type="bookGroup" (such as each Testament, the Apocrypha, and perhaps smaller groups such as the Pentateuch, the Minor Prophets, etc), plus any front and back matter divisions (the selection of which varies greatly between editions).

With each bookGroup div, there will typically be book divs corresponding to each included Canonical or deutero-canonical book. Some books are divided into majorSections (such as the sub-books in Psalms), sections (typically topical divisions with headings), subSections (occasional minor divisions within sections). A specific chapter element is provided and encouraged, though div type="chapter" is also permissible.

Below this point typical texts switch from successive levels of div elements, to more specific markup such as paragraphs, lists, quotations, inscriptions, and the like. Also at this level, the markup begins commonly to interact with verse markup.

Use of the types defined for div is mandatory when a provided type is applicable. For example, a colophon must be marked up as <div type='colophon'>. If types not provided are needed, they may be added but must begin with "x-", to distinguish them from OSIS-standard values.

Such markup forms the primary backbone of an OSIS document. Chapter and verse elements are important (particularly for retrieval), but considered to be an overlay onto the more linguistic or thematic structure. Therefore, so long as verses or chapters do not cross the boundaries of other elements, they may be expressed in the normal fashion (NASB):

<chapter osisID="Mark.10">
<head>Mark Chapter 10</head>
<div type="section"><head>Divorce</head>
<verse osisID="Mark.10.1">Jesus then left that place and went into
the region of Judea and across the Jordan. Again crowds of people
came to him, and as was his custom, he taught them.
</verse>
<verse osisID="Mark.10.2">Some Pharisees came and tested him by
asking, "Is it lawful for a man to divorce his wife?"
</verse>
<verse osisID="Mark.10.3">"What did Moses command you?" he replied.
</verse>
<verse osisID="Mark.10.4">They said, "Moses permitted a man to write
a certificate of divorce and send her away."
</verse>
<verse osisID="Mark.10.5">"It was because your hearts were hard that
Moses wrote you this law," Jesus replied. </verse>
<verse osisID="Mark.10.6">"But at the beginning of creation God 'made
them male and female.' </verse>
<verse osisID="Mark.10.7">'For this reason a man will leave his
father and mother and be united to his wife,</verse>
<verse osisID="Mark.10.8">and the two will become one flesh.' So they
are no longer two, but one. </verse>
<verse osisID="Mark.10.9">Therefore what God has joined together, let
man not separate."</verse>
<verse osisID="Mark.10.10">When they were in the house again, the
disciples asked Jesus about this. </verse>
<verse osisID="Mark.10.11">He answered, "Anyone who divorces his wife
and marries another woman commits adultery against her. </verse>
<verse osisID="Mark.10.12">And if she divorces her husband and
marries another man, she commits adultery." </verse>
</div>
...
</chapter>

10. Simple paragraphing, quotes, and notes

Paragraphs (element p), quotations (element q), and other grouping elements can be inserted around groups of verses, as shown below. Likewise, note elements can be inserted where needed. The paragraph need not give an osisID for the set of verses it contains, since they are typically provided on the verse elements themselves:

...
<p>
<verse osisID="Esth.4.10">Then Esther spoke to Hathach, and gave him
a command for Mordecai: </verse>
<verse osisID="Esth.4.11"><q>All the king's servants and the people
of the king's provinces know that any man or woman who goes into the
inner court to the king, who has not been called, he has but one law:
put all to death, except the one to whom the king holds out the
golden scepter, that he may live. Yet I myself have not been called
to go in to the king these thirty days.</q> </verse>
<verse osisID="Esth.4.12">So they told Mordecai Esther's words.
</verse> </p>
<p>
<verse osisID="Esth.4.13">And Mordecai told them to answer Esther:
"Do not think in your heart that you will escape in the king's palace
any more than all the other Jews. </verse>
</p>
<p>
<verse osisID="Esth.4.14">For if you remain completely silent at this
time, relief and deliverance will arise for the Jews from another
place, but you and your father's house will perish. Yet who knows
whether you have come to the kingdom for such a time as this?"
</verse>
</p>
<p>
<verse osisID="Esth.4.15">Then Esther told them to reply to Mordecai: </verse>
<q>
<verse osisID="Esth.4.16">"Go, gather all the Jews who are present in
Shushan, and fast for me; neither eat nor drink for three days, night
or day. My maids and I will fast likewise. And so I will go to the
king, which is against the law; and if I perish, I perish!
</verse></q>
</p>
<p><verse osisID="Esth.4.17">So Mordecai went his way and did
according to all that Esther commanded him.<note
type="textual">Septuagint adds a prayer of Mordecai
here.</note></verse> </p>

Notice in this example that all the paragraphs and quotations still enclose an exact number of verses; there are exceptions to this elsewhere in the Bible, that need special handling as explained later.

When tagging quotations, do not also include quotation marks. They will be generated in the typesetting or display process. This is important for several reasons. FIrst, if some people use q, some use punctuation marks, and some use both, anyone processing OSIS texts will have to check every text and account for all the variations -- this is expensive and time-consuming: that is, it will make the Bibles cost more (to someone), and be delivered later. Another reason is that punctuation for quotes differs around the world; so any given quotation mark may be meaningless to other communities. In Spanish, for example, there are special rules about how to mark quotes that continue after an interruption -- such cases can be distinguished by adding a type attribute to the q element, with values such as initial, medial, and final.

Many editions of the Bible have accompanying notes, often of several distinct types. A number of predefined types, and some additional internal structure, are discussed later. It is customary to include the notes directly within the text, at the point to which they apply. This can be done via the note element, which can be placed almost anywhere. In the future, it is likely that notes will more commonly reside outside of the text, instead residing in special notes-files that can be attached (via osisRef) to any Bible edition on request.

Every note should have a type attribute to indicate its purpose; many Bible editions show different kinds of notes in different places. The pre-defined note types are listed below; they are not sharply-defined, wholly distinct categories. In addition, if none of these categories suffice, encoders may create their own so long as their names begin with "x-".

  • allusion The note explains an implicit reference the text makes to another text or concept.
  • alternative The note records an alternate possible reading of the text, whether due to ambiguity in translation or to manuscript variation.
  • background The note provides background information, such as cultural norms, explanations of geographic or other information original readers would have known, and so on.
  • citation The note cites a supporting text or further explanation of some kind.
  • crossReference The note provides a cross-reference to a related passage or other text.
  • devotional The note includes information of interest for devotional reading.
  • exegesis The note discusses a relevant point of exegesis or interpretation
  • explanation The note explains implicit, ambiguous, or otherwise non-obvious aspects of the passage.
  • speaker [2.0] This type is intended mainly for use in sermons and other performance texts, where the performer may wish to make notes to him or herself. For example, "tell joke here".
  • study The note provides helps for a deeper study of the passage.
  • translation The note discusses an issue of translation, such as a word whose meanining is unclear in the original, or a reasons for the translator's choice of phrasing. Bible translation projects will likely use this heavily, using the subtype attribute to mark the status of each note as resolved or unresolved, the person responsible for the note, and so on.
  • variant The note records a textual variation in manuscript tradition, relevant at its location.

Sometimes a verse or chapter starts or end in the middle of some other unit, such as a poetic line group, paragraph, quotation, or speech. In such cases an alternate form of the verse or chapter tags must be used. This usage is explained in the next section.

11. Elements that cross other elements

The normal form of an element is a start tag and an end tag: <verse>...</verse>. For handling markup that crosses boundaries, however, a special form must be used. It consists of two totally empty instances of the same element type: one to mark the starting point, and one to mark the ending point. The two empty elements identify themselves as to which is the start and which is the end, and co-identify themselves by the sID attribute (the start of the traditional element) and the eID attribute (the end of the traditional element), the values of which must match.

Empty elements are indicated in XML by a tag with "/" preceding the final ">": thus "<verse/>" rather than <verse> or </verse>. Elements used in this way are commonly called "milestones", and those particular elements in OSIS that permit this alternate encoding are thus called "milestoneable". Elements that are "milestoneable" in the OSIS schema are:

  • abbr
  • chapter
  • closer
  • div
  • foreign
  • l
  • lg
  • q
  • salute
  • seg
  • signed
  • speech
  • verse

This is particularly useful where modern translations break up verses or other traditional divisions in a Bible text. For example, a paragraph based encoding of part of the Book of Esther would appears as follows:

<p>
<verse sID="Esth.2.7" osisID="Esth.2.7"/>Mordecai had a very beautiful cousin named Esther, whose Hebrew name
was Hadassah. He had raised her as his own daughter, after her father and mother died.<verse eID="Esth.2.7"/>
<verse sID="Esth.2.8" osisID="Esth.2.8"/>When the king ordered the search for beautiful women, many were
taken to the king's palace in Susa, and Esther was one of them.</p>
<p>Hegai was put in charge of all the women,<verse eID="Esth.2.8"/>
<verse sID="Esth.2.9" osisID="Esth.2.9"/>and from the first day, Esther was his favorite. He began her beauty
treatments at once. He also gave her plenty of food and seven special maids from the king's palace, and they had
the best rooms.<verse eID="Esth.2.9"/>
</p>

There are two things to note about the Esther example:

  • Esther 2:8 is divided by a paragraph (the p element and so must be marked using the verse element as a milestones with the sID and eID attributes to link those two milestones together.
  • Where overlapping elements are necessary, the milestoneable element technique must be used for the entire text. That is, it is an error to mark some verses in Esther with traditional verse elements, i.e., as containers and others with the milestoneable verses. The reason is quite simple, inconsistent markup is more difficult to process and makes the encoded text less useful for everyone.

This is equivalent to the TEI "milestone" method for marking such phenomena. It has the advantage that milestones representing a given type of element have the same name as the element, and automatically have the same attributes. Although XML itself will not detect a validation error if attributes other than eID are specified on the ending milestone, eID is specified on the starting milestone, or the start and end milestones are in the wrong order, each of these conditions is an OSIS error.

For OSIS purposes, there is no semantic difference between marking up a chapter or verse as a container using a start and end tag, versus marking it up as a "milestone pair" consisting of two empty tags.

Note: Typesetting and layout systems vary in their ability to accommodate non-hierarchical markup such as this. Fortunately, in most Bible editions the only formatting consequence of a verse element is insertion of the verse number, and perhaps insertion of a line-break; these are within the capabilities of most layout and style systems even though the verse is not a container in XML terms.

12. Special Text Types

The bulk of the remaining OSIS elements fall into a few simple classes: First, markup for special text types, such as epistles and drama. Second, generic structures such as lists, tables and glossaries (typically found in appendixes of printed Bibles). And finally, small-scale elements that mark, quotations, notes, names, index entries, and the like.

12.1. Markup for epistles and similar materials

Letters, epistles, and similar texts are marked up in basically the same way as any other text. However, three special elements are available for marking portions unique to this genre:

12.1.1. salute

The salute element encloses the salutation or greeting, typically at the very beginning of a letter. It should include the whole salutation, including (if present) the "to", "from", and any following greeting or blessing. If the boundaries of a salutation are the same as the boundaries of a paragraph, section, or other unit, that unit should be placed outside, with the salute element directly within. For example (LBP):

<div type="book" osisID="1Tim">
<head>The First Epistle to Timothy</head>
<chapter osisID="1Tim.1">
<salute>
<verse osisID="1Tim.1.1">FROM: PAUL, a missionary of Jesus Christ,
sent out by the direct command of God our Savior and by Jesus Christ
our Lord -- our only hope.</verse>
<verse osisID="1Tim.1.2">To: Timothy. Timothy, you are like a son
to mein the things of the Lord. May God our Father and Jesus Christ
our Lord show you his kindness and mercy and give you great peace
of hear and mind.</verse>
</salute>
<verse osisID="1Tim.1.3">...</verse>
</chapter>
...
</div>

12.1.2. signed

The signed element surrounds the name of the author and/or amanuensis of a letter and its immediately surrounding phrase of opening or closing (if any). In Biblical epistles, it is common for the author to be named only at the beginning; this should still be marked up with the signed element.

signed may appear with or without an accompanying closer or salute element, and the name may or may not also be tagged as a name (if it is, the name should be the inner element even if it includes all the text content of the signed element. In New Testament epistles, there is not generally an obvious, final signature. However, this element may be used somewhat more broadly of a phrase or portion judged as intended to identify the writer. As shown below, the signature of an amanuensis may also be marked up in this way. For example (RSV):

  • <verse osisID="Rom.16.22"><signed>I Tertius salute you which wrote this epistle in the Lorde.<signed</verse>

    [English, Tyndale, 1525/1530]

  • <verse osisID="1Cor.16.21"><signed>I, Paul, write this greeting with my own hand.</signed></verse>

    [English, RSV]

  • <verse osisID="2Cor.1.1"><signed>Paul, an apostle of Jesus Christ by the will of God, and Timothy [our] brother, to the church of God which is at Corinth, with all the saints who are in all Achaia:</signed></verse>

    [English, Webster]

  • <verse osisID="Gal.6.11"><signed>See with what large letters I am writing to you with my own hand.</signed></verse>

    [English, RSV]

  • <verse osisID="Eph.1.1"><signed>Paul, an apostle of Christ Jesus through the will of God, to the saints that are at Ephesus, and the faithful in Christ Jesus:</signed></verse>

    [English, American Standard Version, 1901]

  • <verse osisID=""><signed>Paul, and Silvanus, and Timothy, to the church of the Thessalonians which is in God the Father and in the Lord Jesus Christ: Grace to you, and peace. </signed></verse>

    [English, RKJNT]

  • <verse osisID="1TIm.1.1"><signed>Paul, an apostle of Jesus Christ, according to the commandment of God our Savior, and of Christ Jesus our hope:</signed></verse>

    [English, Douay-Rheims Bible, Challoner Revision]

  • <verse osisID="Phm.1.1"><signed>Mimi Paulo, mfungwa kwa ajili ya Kristo Yesu, na ndugu Timotheo,</signed> ninakuandikia wewe Filemoni mpendwa, mfanyakazi mwenzetu</verse> <verse osisID="Phm.1.2">na kanisa linalokutana nyumbani kwako, na wewe dada Afia, na askari mwenzetu Arkupo.</verse>

    [Swahili NT]

12.1.3. closer

The closer element surrounds the closing portion of a letter, typically consisting of final greetings or blessing, and a signature (see signed). It is a matter of judgement just where a closer begins and ends. For example:

  • <closer><verse osisID="1John.5.21">Dear children, keep away from anything that might take God's place in your hearts. Amen. Sincerely, <signed>John</signed></verse></closer>

    [LBP]

12.1.3.1. benediction

OSIS presently provides no special markup for benedictions and blessings. Recommended practice at this time if an encoder wishes to identify them in a text, is to use seg type="benediction". For example:

  • <verse osisID="2Cor.13.14"><seg type="benediction">The grace of the Lord Jesus Christ, and the love of God, and the communion of the Holy Spirit, [be] with you all. Amen.</seg></verse>

    [Webster]

12.2. Dramatic texts

OSIS provides two main features for marking up dramatic texts: A way to declare the list of characters, or castList; and a way to identify speeches and speakers in the body of a dramatic text.

A castList element contains a structured list of the roles, or cast, of a dramatic work. It is drawn directly from the TEI structure for the same thing. For example, in the Song of Songs, some translations may present the list of characters at the start of the book: lover, beloved, and friends. The same might be done for Job. However, these elements will be most commonly used for extra-Biblical materials, such as a play based on the Bible, or dramas in classical or other literature.

A simple example of a castList is shown below, perhaps for a dramatic re-enactment of Job:

<castList>
<castGroup>
<head>Cast of characters</head>
<castItem>
<actor>Patrick Durusau</actor>
<role>Job</role>
<roleDesc>A man of God who suffers greatly</roleDesc>
</castItem>
<castItem>
<actor>(a whirlwind)</actor>
<role>God</role>
<roleDesc>The Almighty, who permits Job's suffering, and
responds to his questions about it.</roleDesc>
</castItem>
<castItem>
<actor>(a disembodied voice)</actor>
<role>Satan</role>
<roleDesc>The instigator of Job's suffering</roleDesc>
</castItem>
<castItem>
<actor>Todd Tillinghast</actor>
<role>Eliphaz</role>
<roleDesc>The first of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Chris Little</actor>
<role>Bildad</role>
<roleDesc>The second of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Steve DeRose</actor>
<role>Zophar</role>
<roleDesc>The third of Job's friends to speak</roleDesc>
</castItem>
<castItem>
<actor>Troy Griffiths</actor>
<role>Elihu</role>
<roleDesc>The youngest and last of Job's friends to speak,
who was slightly less clueless than the rest.</roleDesc>
</castItem>
</castGroup>
</castList>

The castList element contains the entire casting List, and consists of one or more castGroup elements. Multiple castGroups, each with its own head, would be used if there were multiple sub-groups of the cast to be listed separately; more typically there will be only one castGroup within a castList.

At this time, castList can only occur in a work declaration, after the Dublin Core elements. Thus, if a Bible encoder wishes to include the casts of Song of Songs and of Job, they would each need to be marked as a separate castGroup within that one castList.

The castItem element contains the full information for a single character. This must include a name for the role being played, and should include a roleDesc, that is, a description of that role. It may also include the name of an actor, if the text being encoded represents a particular enactment rather than, say, a libretto or script.

In general there is no need to also encode an actor name or role name with an explicit name element, unless the encoder wishes to provide a normalized form for later reference; in that case, the name element would be placed just within the actor or role element, not surrounding it.

It is strongly recommended that each castGroup and castItem have an ID attribute. Since IDs must be unique across all element types in a document, encoders may wish to prefix certain kinds of IDs to separate them and avoid conflicts. For example, an appropriate ID for a castItem representing the Friends in Song of Songs would be "cast.friends", or perhaps "cast.song.friends".

12.3. speaker

The speaker element is used to identify the person or role that is uttering the content of an associated speech.

<div osisID="NRSV.Song.2">
<speech>
<speaker>woman</speaker>
<verse osisID="NRSV.Song.2.1">I am a rose of Sharon, a lilly of the valleys.</verse>
</speech>
</div>

Which is the equivalent to:

<div osisID="NRSV.Song.2">
<speech who="woman">
<verse osisID="NRSV.Song.2.1">I am a rose of Sharon, a lilly of the valleys.</verse>
</speech>
</div>

Either method is correct but careful encoders will choose one or the other and be consistent in using one method or the other. Other than document invalidity, nothing makes use of an encoded document more difficult than correct, but inconsistent encoding.

12.4. speech

The speech element is used to indicate quoted direct speech. In that sense it represents a kind of quotation. However, the q element is to be used for quotations in general, where the speech element is limited to accounts of an individual making an actual speech in some kind of performance context. In general, both elements should not be applied to the same text portion. Just as with the q element, using the speech element makes quotation marks unnecessary, and they must not be used. For example:

<chapter osisID="Acts.7">
<head>Stephen's Speech to the Sanhedrin</head>
<verse osisID="Acts.7.1" sID="a71"/>Then the high priest asked him, <speech>Are
these charges true?</speech>
<verse eID="a71">
<verse osisID="Acts.7.2" sID="a72"/>To this he replied:
<speech>Brothers and fathers, listen to me! The God of glory appeared
to our father Abraham while he was still in Mesopotamia, before he
lived in Haran. <verse eID='a72'/>
<verse osisID="Acts.7.3" sID="a73">'Leave your country and your people,' God
said, 'and go to the land I will show you.'<verse eID="a73"/>
<verse osisID="Acts.7.4" sID="a74"/>"So he left the land of the Chaldeans and
settled in Haran. After the death of his father, God sent him to this
land where you are now living. <verse eID="a74"/>
<verse osisID="Acts.7.5" sID="a75"/>He gave him no inheritance here, not even a
foot of ground. But God promised him that he and his descendants
after him would possess the land, even though at that time Abraham
had no child. <verse eID="a75"/>
<verse osisID="Acts.7.6" sID="a76"/>God spoke to him in this way: 'Your
descendants will be strangers in a country not their own, and they
will be enslaved and mistreated four hundred years. <verse eID="a76"/>
<verse osisID="Acts.7.7" sID="a77"/>But I will punish the nation they serve as
slaves,' God said, 'and afterward they will come out of that country
and worship me in this place.'<verse eID="a77"/>
<verse osisID="Acts.7.8" sID="a78"/>Then he gave Abraham the covenant of
circumcision. And Abraham became the father of Isaac and circumcised
him eight days after his birth. Later Isaac became the father of
Jacob, and Jacob became the father of the twelve
patriarchs.<verse eID="a78"/>
...
<verse osisID="Acts.7.53" sID="a79"/>you who have received the law that was put
into effect through angels but have not obeyed it.
<verse eID="a79"/>
</speech>
...</chapter>

Note that in this example the high priest's short speech in verse 1 is marked up as a normal container element with normal start- and end-tags, as is Stephen's reply. But, note that all the verse boundaries have been repesented with milestoneable verse elements. The reason for this is quite simple, if the encoding jumps from using containers for verses and only on occassion changes to milestones, noting that Stephen's speech start inside a verse, the file becomes very difficult to process reliably. When a conflict arises between the scope of chapter/verse units and other units, the chapter/verse units give way by being represented as milestones. If a conflict arises between two other units (say, a quote that encompasses part but not all of each of two paragraphs), it is left to the encoder's discretion which or them is represented via milestones.

12.5. Marking up poetic material

Although poetic material is commonly called "verse" material, OSIS avoids that term because of potential confusion with the book/chapter/verse reference system. Thus, like "TEI," markup of poetry refers to lines and line groups.

In addition, OSIS provides a typographic line-break element. This is because in at least some editions of the Bible, the exact placement of typographic line-breaks within poetic lines is considered very important; while on the other hand it is determined in part by presentational concerns (for example, column width), rather than by linguistic characteristics of either the source or target language.

OSIS provides three main elements for marking up poetic material:

12.5.1. lg

The lg or "line group" element is used to contain any group of poetic lines. Thus it covers for units like couplet, stanza, and entire poem. Line groups can contain smaller line groups as well.

12.5.2. l

The l element is used to mark poetic lines, as determined by the linguistic nature of poetry in the language of the work. For example, much English poetry consists of lines that can be located by the position of rhyming words, and/or by counting syllables; Hebrew poety can often be divided into lines based on parallelism of thought or meaning.

The following example shows an encoding of the first two verses of Psalm 7 from the CEV which uses the lg and l elements to mark poetic material.

<div type='section' scope='Ps.7.1-Ps.7.17'>
<title>The <divineName type='x-yhwh'>LORD</divineName> Always Does Right</title>
<lg>
<l>
<verse sID='Ps.7.1' osisID='Ps.7.1'/>You, <divineName type='x-yhwh'>LORD</divineName> God,<lb type='x-secondLine'/>
are my protector.</l>
<l>Rescue me and keep me safe<lb type='x-secondLine'/>from all who chase me.<verse eID='Ps.7.1'/>
</l>
<l>
<verse sID='Ps.7.2' osisID='Ps.7.2'/>Or else they will rip me apart</l>
<l>like lions<lb type='x-secondLine'/>attacking a victim,<lb type='x-secondLine'/>and no one will save me.
<verse eID='Ps.7.2'/>
</l>
</lg>
</div>

12.5.3. lb

The lb element, or "line break", is used to mark line breaks that are not the result of linguistically or poetically significant structure, but are primarily part of the typography and layout. For example, a lone line might be broken to fit into a narrow column. The lb element is an empty element used to mark where such breaks occurred in an important copy text, or where they should be placed in a text to be rendered.

Bible typesetting has a long tradition involving placement of such breaks. In some cases, translators have carefully decided preferred or required break-points for various set widths. These can be accommodated by using the type attribute of lb. For example, type="wide-pref" and type="narrow-pref" might be used to identify the locations of preferred line-breaks for wide and narrow column layouts. Similarly, type might be used to distinguish various levels of indentation following the break, or other typographic factors deemed important.

The lb element should not be used merely to record where line breaks in general happened to occur in a source edition. For most source editions this information is unimportant; for manuscripts it may be imortant, but must be marked up using the milestone element instead.

12.6. Lists, tables, genealogies, figures and other material

Simple glossaries such as appear at the back of many Bibles, may be encoded at this time using the simple list, label, item elements described below. A dicitonary extension is well along in development, and should be available as an extension module within the next few months. That module should be used for any but the simplest lexical tools; and once available, OSIS may decide to recommend against further use of list to represent even simple glossaries.

12.6.1. list

All types of lists are marked using the list element; they can be distinguished by type attribute valuess such as "ordered", "unordered", "compact", "definition", and type. A list consists of any number of items, some or all preceded by labels, which corresponded to the definition-terms of definition lists in various schemas.

12.6.2. label

A leading label for a given list item. Labels are optional.

12.6.3. item

The main content or description for each list item.

(list example forthcoming)

12.6.4. table

OSIS provides only very rudimentary tables: a table consists of rows, which in turn consist of cells. Formatting and layout is not part of the table markup; it can either be done automatically, as in HTML browsers, or by inserting some signal to the layout engine, such as type attributes or processing instructions. Note that a table can be nested inside another table. Simply start a new table element inside a cell element.

12.6.5. row

12.6.6. cell

(table example forthcoming)

12.6.7. figure

The figure element is used to insert graphic non-textual materials, in other words, maps, pictures, drawings into an encoded text. The figure element in OSIS may contain caption (see next section) along with optional index and note elements.

An example of a figure in an OSIS text might be:

<figure src="Beckmann_1917.jpg" alt="Painting by Max Beckmann, titled
Christ and the Woman taken in Adultery"><caption>Christ and
the Woman Taken in Adultery by Max Beckmann,
1917</caption><index index="illustrations"
index1="Beckmann, Max">
</figure>

At first it may look odd that the material in the alt attribute is repeated in the caption element. The alt attribute is important for situations where the application or user (for the visually impaired) cannot use or see the image that has been inserted in the text. The alt attribute is a friendly way of insuring that the encoded text will be understandable by the widest range of both applications and users.

The index attribute allows the encoder to encode the information necessary to automatically create an index, for either an online version of this material or a more traditional back of the book index. The index attribute gives the type of index where this item will appear and index1 provides the material that will appear in that index. See index (below) for more information on this element.

12.6.8. caption

(see example above, fuller examples forthcoming)

12.7. milestone

The milestone element is an empty element, and so is represented as <milestone/> rather than as a typical start- or end-tag. It is used to mark point events in a text, often involving the layout of the original text, or special points of access into the electronic text.

For example, when digitizing a manuscript, it may be considered important to record where the page, column, and line boundaries of the original manuscript fell. This would be done as shown here:

<milestone type="pb" n="37-verso"/>
<p>The Lord said to Eliphaz:<milestone type="line"/>
What my servant Job has said about me is true, <milestone type="line"/>
but I am angry with you and your two friends for <milestone type="line"/>
not telling the truth. <verse osisID="Job.42.8">So I want you to go
over to <milestone type="line"/>
Job and offer seven bulls and seven goats on an <milestone type="line"/>
alter as a sacrifice to please me. After this, Job <milestone type="line"/>
will pray, and I will agree not to punush you for <milestone
type="line"/>your foolishness.</verse><milestone type="line"/>
<verse osisID="Job.42.9">Eliphaz, Bildad, and Zophar obeyed the Lord,
and he answered Job's prayer.</verse>

Note that because milestone is an empty or point element, not a container, it may be placed freely without concern about violating the boundaries of other elements in the same region.

Where a break to be represented by a milestone occurs between other units, such as verses or paragraphs, the milestone should be placed between those units, rather than just within either one.

When setting attribute n on a milestone, it should indicate the number of the unit starting, not the unit ending. For example, <milestone type="page" n="3"/> indicates the break between pages 2 and 3, not between pages 3 and 4. Numbering does not need to be unique across various types of milestones -- for example, the 24th line on page 5 of a manuscript may be marked simpley n="5", rather than n="24.5" or similar.

Several predefined types are provided for the milestone element (the value for the type attribute is shown in bold):

  • pb

    Marks the location of a page break in the source text.

  • column

    Marks the location of a column break in the source text. Assuming page boundaries are also marked, the start of the first column need not be marked unless something else (such as a footer) precedes it in the encoding of the page. Columns should be numbered in the order of reading (for example, right to left in Hebrew texts). In the case of, say, an English/Hebrew diglot edition, where there is no principled order of reading among the columns, the direction used for the pages (Hebrew or Greek) should be considered the dominant direction, and the same direction should be used for numbering columns.

  • header

    A milestone of type "header" should precede the encoding of the page header if it is being included in the encoded text. This would normally be true only for digitized editions of manuscripts or other important copy editions, because in modern print Bibles headers are typically automatically generated.

  • footer

    Type "footer" should be used just like type "header", except that it marks the page footer area instead.

  • line

    Line milestones should be used to mark line breaks in the copy text when they are considered significant. This will normally only be true for important manuscripts, where line numbering may be needed for paleographic or reference use. Line milestones must not be used to represent linguistically significant line breaks, such as in poetry, for which the lg and l elements are provided.

  • halfLine

    In certain languages it is important to mark half-line units, and this type is provided for such cases.

  • screen

    The milestone of type "screen" is to be used to mark preferred break points in an on-screen rendering of the text. For example, if the user requests to be taken to the book of Psalms in a given electronic edition, it may be best not to take them to Psalm.1.1, but to an earlier point, preceding any introductory material. In many cases this can be accomplished by taking them to the appropriate div (since the <div type="book" osisID="Ps"> should precede and Psalms-specific introductory material); but this milestone type is available for other cases. The OSIS specification does not impose requirements on how applications make use of such milestones.

13. Common elements in all texts

The elements found in this section can be found in almost any encoded text.

13.1. a

The a element is exactly analogous to the HTML a element, and likewise may be used to encode links within a document. This eases integration of OSIS documents into the Web environment. For example:

<p>See Edwards' famous treatise on <a
href="http://www.ccel.org/e/edwards/affections/religious_affections.html">religious
affections</a> for additional information.</p>

13.2. index

The index element may be placed at any point in the document to indicate a topic under which that location should be indexed. It is always an empty element. Multiple indexes (such as of places, names, theological or ethical issues, etc) must be distinguished via the name attribute.

Indexes with up to 4 levels of headings are supported. The primary index entry name is specified on the level1 attribute, followed by sub-headings level2, level3, and level4. For example:

<head>On Justice<index name="topic" level1="Virtues"
level2="Justice"/>

There is also a see attribute, which may be used to represent the need for a cross-reference to another index entry; such elements should be placed together at the end of the document body (since they do not refer to a particular location). For example:

<index name="topic" level1="Virtues" level2="Justice" see="Fairness"/>

No separate "see also" type is provided at this time.

13.3. reference

The reference element is used to encode an explicit cross-reference to another passage or work (the work referred to need not be Biblical, but must be declared via a work element in the header, and by accessible via the same canonical referencing scheme defined in osisID syntax. Reference elements will often occur within notes, but may also occur freely in text (the latter is more common when encoding non-Biblical works). For example:

(example forthcoming)

13.4. abbr

Marks a portion of the content as an abbreviation. The expanded value should be supplied as the value of the expansion attribute. For example:

<abbr expansion="Journal of Biblical Literature">JBL</abbr>

Most often seen in notes, where citations are often abbreviated and users may not be familiar with the abbreviation. Putting expansion in the expansion attribute allows software to chose to diplay the expansion instead of the abbreviation or to display it upon request by the reader.

13.5. catchWord

Catchwords and catchphrases are those parts of notes that are copied from the main text, to orient the reader as to the note's precise applicability. Catchwords in notes must be marked when present. For example:

<verse osisID="NRSV:Ezek.19.5">When she saw that she was thwarted,
that her hope was lost, she took another of her cubs and made him a
young lion.</verse> <note>It is uncertain to which king <catchWord
osisRef="Ezek.19.5">another of her cubs</catchWord> refers....</note>

13.6. divineName

divineName is only for the Deity. Angels, demons, idols, and the like should be tagged with <name type='nonhuman'> For example:

<divineName>El Shaddai</divineName>

13.7. foreign

Marks an insertion of text not in the primary language, such as "Talitha Cum" in Mark 5:41. The specific language should be indicated via the xml:lang attribute. For example:

<verse osisID="NRSV:Mark.5.41">He took her by the hand and said to her:
<q><foreign xml:lang="arc">Talitha cum</foreign></q>, which means,
<q>Little girl, get up!</q></verse>

13.8. hi

Provides simple text highlighting capability; types that can be distinguished as to their purpose (emphasis, marking of interpolated or transliterated foreign words, boldness for headings, etc.) must instead be marked using the appropriate, more specific, element. The hi element (short for "highlighted") is reserved for cases where the purpose of the highlighting or other typographic distinction is unclear, or known to be unimportant.

The type attribute on the hi element allows the user to specify what typographic distinction was observed in the text. As noted above this is not meant as a guide for stylesheets but for recording what was observed. If it is known with reasonable certainty why a word or phrase appears in italic, for example a foreign phrase, then the foreign element should be use to mark it. To enable consistency in the marking of such distinct texts, the OSIS schema provides seven (7) standards values for the type attribute on the hi element as follows:

  • bold
  • illuminated
  • italic
  • line-through
  • normal
  • small-caps
  • underline

If additional values are needed, they should be created by prepending "x-" to the value.

13.9. seg

This is primarily used for segmentation of text in ways not provided by the OSIS schema. For example, the lowest level of division that has a defined element in OSIS is word. Note that for this version of the schema, it is presumed that a word is distinguished by being bounded on either side by white space. The OSIS core team was aware that such a definition is too crude to be useful for a number of modern and ancient languages and intends to address that issue in a future release of the schema.

In cases where subdivisions of words need to be encoded, prefixes, suffixes, morphemes, the seg element is the correct element to be used. It can also be used, with caution, to mark a textual feature that is not otherwise provided for by the schema. It should be noted that this element can only contain very small elements and cannot contain things like verses or paragraphs.

13.10. inscription

inscriptions should not also be tagged as quotations. For example, where Paul refers to an alter inscription in Athens (NIV):

<verse osisID="Acts.17.23">For as I walked around and looked carefully
at your objects of worship, I even found an altar with this inscription:|
<inscription>To an unknown god</inscription>
<p><verse osisID="Dan.5.22"><q sID="q.Dan.83"/>But you
his son, O Belshazzar, have not humbled yourself, though you knew all
this.</verse>
<verse osisID="Dan.5.23">Instead, you have set yourself up against
the Lord of heaven. You had the goblets from his temple brought to
you, and you and your nobles, your wives and your concubines drank
wine from them. You praised the gods of silver and gold, of bronze,
iron, wood and stone, which cannot see or hear or understand. But you
did not honor the God who holds in his hand your life and all your
ways.</verse>
<verse osisID="Dan.5.24">Therefore he sent the hand that wrote the
inscription.</verse></p>
<p><verse osisID="Dan.5.25">This is the inscription that was written:
<inscription>Mene, Mene, Tekel, Parsin</inscription></verse>

Note the use of an empty tag to represent the start of Daniel's quotation, which ends at the end of verse 28 (where <q eID="q.Dan.83"/> would appear to end the quotation). There is no need for quotation marks, either at the start of verse 22 or of verse 25 (after a paragraph break within the quotation) -- the appropriate punctuation conventions for the language and publisher involved will be provided via a stylesheet mechanism.

In the example from Daniel, the repetition of words from the inscription (in verse 26-28) should not also be marked as inscriptions.

Inscriptions are found in Exod.39.30, Dan.5.25, 2Tim.2.19. There are additional passages where inscriptions are mentioned without being quoted verbatim, such as Matt.22.20; these would not be encoded using the inscription element.

13.11. mentioned

This element marks meta-linguistic use of a term. That is, it encloses a word, phrase, or other unit that is not being used, but only mentioned. For example:

<verse osisID="NRSV:John.1.42">He brought Simon to Jesus, who looked
at him and said, <q>Your are Simon son of John. You are to be called
<mentioned>Cephas</mentioned></q> (which is translated Peter).</verse>

In this example, Cephas is not being used by Jesus to call Simon to him but is being used to tell him his new name.

13.12. name

When a name appears in a text, it is important to mark it with this element and to use the type attribute to record what type of name has been marked. Remember that a computer cannot distinguish Job, as in the man from Ur, from job, as in ‘I have a job for you...’ without your assistance, at least at the beginning of a sentence. Despite what you may read in the newspaper, computers are very literal and quite dumb when it comes to reading texts.

The formal types of names provided are:

  • geographic
  • holiday
  • nonhuman
  • person
  • ritual
<verse osisID="NRSV:Job.1.1">There once was a man in the land of <name type="geographic">Uz</name>
whose name was <name type="person">Job</name>. That man was blameless and upright, one who feared <divineName>God</divineName>
and turned away from evil.</verse>

Note that there are three names in that verse, one geographic, one of a person, and one of the Deity. The first two are marked with the name element and appropriate type attribute. Any use of any form of the name of the Deity is marked with divineName Different forms of the divine name should be specified, if desired, using the type attribute on divineName.

13.13. q

The q element marks all quotations, whether inline or block-length. It often crosses the boundaries of other units, and so may be encoded using empty elements with sID and eID attributes. The positioning of q elements will not always coincide with the placement of quotations marks in a printed version. For example, there are varying conventions about how to punctuate quotations that are continued across paragraph boundaries, or continued after a marker such as "he said, graciously."

(examples forthcoming)

13.14. rdg

This element is used to mark variant or alternate readings. At this time it is intended for use within note elements. For example:

<verse osisID="NRSV.Song.2.1">I am a rose<note
osisRef="NRSV.Song.2.1@s[rose]">Heb <rdg>crocus</rdg></note> of Sharon, a lilly of the valleys.</verse>

This example illustrates (or reinforces) several points: 1. A note appears directly in the textual material where the user would normally see a raised letter or number to indicate a note. 2. The osisRef attribute allows the note to point at a particular word in the text to which the note applies. 3. The rdg element holds an alternative word or reading to the one found in the text. The interested reader will note that the identification of "crocus" is unclear but it is known that there were no "roses" in the modern sense of the word growing on the plain of Sharon (northern Israel) in biblical times.

13.15. transChange

This element should be used to mark text that was changed in a notable way in translation. For example, the KJV traditionally distinguishes all words inserted in translation (often via italics); the Aplified Bible has several punctuation conventions for marking explanatory or other expansions; and some translations indicate where the tense of verbs has been changed, perhaps due to sequence-of-tense requirements in the target language. Several sub-types are provided, as listed below; others may be coined if needed, so long as their names begin "x-".

  • added
  • amplified
  • changed
  • deleted
  • moved
  • tenseChange

(examples forthcoming)

13.16. w

The w element provides a place to put rudimentary word-level annotation, such as part of speech identifiers, lemma or Strong's numbers, and the like. Formal systems for expressing such information are under development; in the meantime, w provides a convenient placeholder so at least the most basic such information can be easily located for use by processors.

w element has the following attributes in addition to those that it shares with other elements:

  • gloss Record commets on a particular word or its usage.
  • lemma Use to record the base form of a word.
  • morph Use to record grammatical information for a word.
  • POS Use to record the function of a word according to a particular view of the language's syntax.
  • src Use to record origin of the word.
  • xlit Use to record a tranliteration of a word.

(examples forthcoming)

14. Canonical refererence (or versification) schemes

A canonical refererence scheme is a system of agreed names and/or numbers for for referring to parts of a document. In the Bible, the traditional system used in most languages consists of a book name (such as Genesis), then a chapter number, then a verse number. Most works of Classical literature have similar schemes, nearly all of which are also hierarchical (that is, they work from larger units to smaller).

The basic form for Biblical verse references is strictly defined by OSIS, so that various electronic Bible versions can interoperate easily. Standard abbreviations for the canonical and deuterocanonical books are provided; chapter and verse numbers follow the book abbreviation separated by periods. For example:

Matt.1.1

OSIS uses such identifiers in several places:

  • To identify a portion of text from an actual canonical work, such as a verse of the Bible. The verse element bears an osisID attribute which must include the identifier appropriate to the verse. For example, <v osisID="Matt.1.1">>....
  • To identify a reference into a Biblical or other passage, that is not contained at the point of reference. For example, "<p>The correctness of my exegesis is incontrovertibly proven by <reference osisRef="Matt.1.1">the first verse of Matthew.</p>"
  • In the header, to identify what portions of the Bible are included in a declared work. For example, a particular edition may include only the NT and Psalms. The scope element may be used to specify each relevant portion.

14.1. Partial identifiers

It is permissible to refer to an entire chapter by simply omitting the verse number and the preceding ".", for example:

Matt.5

Similarly, it is permissible to refer to an entire book by omitting the chapter and verse number and both corresponding periods:

1Cor

For those books of the Bible that have only 1 chapter, the chapter number "1" must be specified: The first verse of Jude is thus Jude.1.1, not Jude.1.

14.2. Works

A reference can also identify a place in a particular edition or translation of the Bible, or to other works entirely, such as Josephus, writing of the Apostolic fathers, classical or modern literature, and so on. We discuss later how to declare particular works and give them local short names. Once that is done, the short name for any declared work can be put before any reference to it, for example:

NIV:Matt.1.1

The colon is required, to make it is clear where the work ends and the within-work reference begins. Most commonly, however, the work is omitted (the default work used then is whatever work was named on the osisWorkID attribute of the osisText element).

It is possible to refer to an entire work, such as the whole CEV, NIV, KJV, the Iliad, etc. However, to do so the work name must be stated, and the following colon must be included (without the colon, it would be interpreted as a top-level identifier within the default work).

14.3. Sub-identifiers

Translations also often split verses into parts, provided labels such as "a" and "b" for the separate parts. Encoders may freely add sub-identifiers below the lowest standardized level. They are set off from the standardized portion by the character "!" (as opposed to "." between levels of the standard system). For example:

Rev.2.20!b

Such subdivisions are not standard across different translations, so applications must be prepared to discard them when trying to locate a referenced location in a different edition.

These extensions are not considered a formal part of the canonical reference scheme, and so a work that uses them need not claim it is using a different scheme.

14.4. Grouping

Translators often group several adjacent verses into a single block, so that they can translate them using word order more natural in the target language. In such cases, the larger unit (commonly a paragraph or p element), gets an osisID that lists all the individual osisIDs for the verses included, separated by white space. For example:

<p osisID="Matt.1.1 Matt.1.2 Matt.1.3">...</p>

osisIDs never allow the use of ranges. Only osisRefs (discussed later) do.

Ranges are prohibited for osisIDs in order to simplify implementation of tools that search for particular passages by reference. If an encoder wished to mark IDs at, say, the pericope level, the markup would be quite verbose because many verses would need to be listed in a single attribute on the div type="pericope". However, there is no need to do this if the verses within the pericope are themselves identified.

14.5. Other details of osisIDs

The "."-separated parts of an osisID are defined to represent a hierarchy. In the traditional versification (introduced by William Whittingham in his New Testament published in Geneva in 1557), these would be book, chapter, and verse numbers. In other schemes for the Bible, or schemes for entirely different works, the names of the parts may differ, but the expectation is that they still form a hierarchy.

The parts of an osisID may contain any mixture of numbers, letters, and underscores. However, to avoid conflict with the other punctuations used (such as ":" to separate the work from the in-work location, "@" to separate fine-grained references in osisRefs, and "!" to separate work-specific extensions to a versification scheme), no other characters are allowed.

The ! as the terminator, allows encoders to append names and/or numbers to provide finer-grained reference points. Such extensions may not be valid across reference systems so should be used with care.

As with XML in general, these identifiers are case-sensitive: "Matt" is the correct form, and there is no Bible book in OSIS that is called "matt" or "MATT". Applications for end users may choose to accept case variants in such names, but applications for encoders (such as OSIS editors) must not produce documents with invalid reference names.

14.6. Coding multiple versification or reference schemes in a single document

A work may provide identifiers drawn from multiple distinct versification schemes. A Bible may wish to provide both the Hebrew and Greek traditional verse numberings; while a work of classical literature may be made more accessible by marking the boundaries of canonical units drawn from completely unrelated systems, such as Loeb and Whiston for Josephus (and 4 more systems for Josephus' Jewish War specifically -- see H. Douglas Buckwalter and Mary K. Shoaff, Guide to Reference Systems for the Works of Flavious Josephus, Evangelical Theological Society, 1995, ISBN 093205501X).

The work element is not required for the standard reference systems already reserved. See XML and OSIS Declarations.

A simpler case may also arise where multiple reference schemes are in use: an osisCorpus that includes several osisTexts, each of which uses a different reference scheme. This case is simpler, since each osisText can provide its own default reference system, using the osisRefWork attribute on osisText.

This is accomplished in the same way as just described for discursive translations: the multiple identifiers are simply placed where needed, separated by spaces when they co-occur on a single element. Each reference system used much be declared as a work in the header, and each identifier much indicate the reference system from which it is drawn. For example, a line of Josephus that has two distinct identifiers would appear like this (presuming the appropriate work declarations in the header):

<l osisID="josephus-war:loeb:245.22 josephus-war:whiston:22.3.14b">

Because verse, chapter, and similar elements can be expressed by empty-element pairs when necessary, it is possible to encode multiple reference systems even though they may have completely unrelated start and end points for their units. For example, a work that has one reference system based on sentences, and another based on lines of a normative print edition, can co-exist. However, taken to extremes this would get rather messy, and be difficult to maintain without OSIS-aware software to assist.

15. OSIS references

An osisRef is very much like an osisID. The fundamental difference is that while an osisID identifies the actual occurrence of canonical text, an osisRef is used to refer to canonical text from somewhere else. For example, a footnote (particularly one of type="crossReference") may refer to a related passage, or a section heading in Mark may include references to the parallel passages in Matthew and Luke; in such cases an osisRef rather than an osisID is used.

Any valid osisID value is also a valid osisRef value, and refers to the same thing. Thus for example, a commentary might say:

<p>The same interpretive method applies also in <reference
osisRef="Luke.1.1">the first verse of Luke</reference>.</p>

However, osisRefs provide additional capabilities. They can refer to a contiguous range of books, chapters, verses (or other units, as applicable to the work being referenced), and they can refer to precise locations within a given canonically-reference unit.

To refer to a range, simply include two osisIDs, one for the first verse (or chapter or book) of the range, and one for the last. Separate the 2 values by a single hyphen (white space is also permitted, but not recommended, on either or both sides of the hyphen). For example:

John.3.14-John.3.16
Prov.30-Prov.31
Esth-Song
Ps.149-Prov.3.4

Both sides of the hyphen must hold complete references. It is not correct to abbreviate the first example above to merely "John.3.14-16" (as always, the values of osisID and osisRef attributes need not be the same values displayed to the reader).

A single osisRef cannot identify a discontiguous range of a work. For example, a complex reference such as "John 3:14-16, 18; 4:1-2; 19-20" cannot be encoded as a single reference. It must instead be encoded as several parts, each contiguous:

<p>See also
<reference osisRef="John.3.14-John.3.6">John 3:14-16,
</reference>
<reference osisRef="John.3.18">18; </reference>
<reference osisRef="John.4.1-John.4.2">4:1-2; </reference>
<reference osisRef="John.19-John.20">4:1-2;
</reference>.</p>

It is permissible for osisRefs, including those on either side of a hyphen in a range reference, to use osisIDs that include the work-specific extension fields ("!" followed by a name).

15.1. Fine Grained References

To refer to specific locations within a named canonical reference element, give the osisID as usual, followed by a "grain identifier", which consists of the character "@", and then an identifier for the portion desired. Such identifiers are of the form:

grainType(parameters)

Two grain types are defined at this time:

cp (short for "code point") counts through the character content of the referenced element, essentially by characters. Technically, the units counted are Unicode code points, a term which is defined more precisely than the generic term "character". The first code point of content is number 1, not 0.

Markup does not imply a space for purposes of counting even if it may for purposes of layout, printing or indexing.

When referring to a location in canonical content, text within non-canonical elements is not counted. (Thus, the intuitive count will not be changed by the insertion of notes, references, critical apparatus, and the like). When referring to a location in non-canonical content, all text in all included elements counts, whether canonical or not.

Grains: s (short for string) finds the first match of the string value specified, with regard to case, within the canonical reference specified. If the canonical reference is one of several applied to the same target element (for example, when a paragraph has osisRef="Matt.1.1 Matt.1.2 Matt.1.3), that whole element is searched. If the string is not found, the user agent must warn the user, and may offer to suggest a best guess (for example, by searching again while ignoring case, whitespace, punctuation, accents, spelling variation, etc).

16. Different versification systems

Hebrew tradition numbers the proscriptions above Psalms (such as "A Maskil according to David") as verse one, and goes on from there; Greek tradition does not number the proscriptions, and start verse 1 after it. Of course, this would make all references in Psalms be off by one verse if the version reached is from the other tradition.

A few languages use traditional reference schemes that completely differ from the familiar book/chapter/verse one.

Many works of Classical literature likewise have more than one standard canonical reference scheme, such a Loeb numbers plus another method.

In such cases, where there are large and systematic differences, different "versification schemes" must be defined and named. On the other hand, nearly every edition of the Bible has some slight deviations from a standard versification scheme that it otherwise follows: for example, subdividing verses into parts "a" and "b", combining verses into a larger translation unit, and so on. It is highly undesirable to call these separate versification schemes, because they differ so slightly; because the differences can be mechanically resolved; and because there is considerably overhead to maintaining and mapping among versification schemes. Thus, as described below such minor extensions can be done without an edition having to say it is using a completely different versification scheme.

BTG intends to develop an XML schema for declaration files that can express such systems, and their mapping to other systems. This work has not been completed. However, we have reserved names for the major versification systems, see: XML and OSIS declarations above.

Each work must identify which versification scheme(s) it uses; this is done by a reference to the versification scheme declared by a work declaration in the header except that the predefined versification systems need not have work declarations.

References can also state what versification scheme they are expressed in, so that they may be correctly interpreted.

HTML may provide targets that look like canonical Bible references, but this would not remove the requirement to specify osisID where applicable. An osisID is mandatory when applicable.

17. Conformance requirements

17.1. Conformance levels

There are 4 levels of OSIS conformance for the markup in OSIS documents:

17.1.1. Level 1: "Minimal OSIS document"

The document must be a well-formed and valid XML document according to the OSIS schema.

The document must be complete in accordance with the scope declaration in its work declaration. For example, a document with a missing chapter is not OSIS-conforming.

The document must mark all canonical references where applicable (for example, book, chapter, and verse boundaries in Bibles. Marking in groups, for example a paragraph that includes several verses, is permissible.

The header must include work declarations for the document itself, and for the versification system it uses.

All work declarations must provide unique osisWorkID values, and only those values may appear as work identifiers in osisIDs and osisRefs (whether by default or explicit) in the document.

All work declarations must provide at least title, creator, and date(s). Creator may be coded as "(anonymous)" or "(unknown)" if applicable. The date of electronic publication is required; other dates may be omitted or coded as "(unknown)" if applicable, though they should be provided if known.

At least one revision description element must be included, describing the most recent substantial changes to the document. The name and email address of the last responsible party should be included.

Empty elements substituted for containers (such as verse, q, etc.) must occur in matched pairs. Each end must actualy be expressed by a true XML empty element, not by start and end tags with nothing between. The earlier member of each pair must have an sID attribute and no eID attribute; the later member of each pair must have an eID attribute and no sID or any other attributes. The sID and eID values for a pair must match (including as to case), and must be distinct from all other sID and eID attribute values in the document.

All elements must be used substantially in accordance with their intended meaning as conveyed in this documentation (including documentation and standards referred to, such as Dublin Core, USMARC Relator Codes, and so on).

17.1.2. Level 2: "Basic OSIS Document"

All requirements of Level 1 conformance must be fulfilled.

A clear statement of rights must be provided within the rights element. If the document is licensed for free copying under certain conditions, those conditions or a reliable URI to them must be provided. If there are encumbrances or if clearance is required to copy or use the work, contact information for the responsible party must be provided directly within the rights element.

The source edition from which the electronic edition was produced must be clearly identified, or clearly stated as unknown (the latter practice is deprecated, and encoders are strongly encouraged to make a serious effort to identify the source edition).

All inscriptions (for example, "mene mene tekel parsin") must be marked where applicable.

All instances, translations, or transliterations of the tetragrammaton must be marked via the divineName element.

All languages substantially appearing in the text must be identified, and all points where the text itself identifies a phrase as coming from a particular language must be marked up to match (for example, "Talitha cumi").

All epistolary markup (opener, closer, signature, salute) must be provided where applicable.

Poetic text must be marked sufficiently to enable rendering it readably as poetry. The distinction of using l for linguistically or poetically significant line breaks, versus using lb for typographically significant or preferred line breaks, must be maintained.

If the source edition had section, paragraph, block quotation, or other similar demarcations in addition to book, chapter, and verse numbering, they must be included and appropriately marked up.

If the source edition had footnotes, sidenotes, endnotes, or other notes, they must be included, and must be distinguished into as many types as can be readily distinguished by observing the typographic conventions of the source edition. Once OSIS standardizes a format for external annotation files, this requirement may be fulfilled either by inline encoding of annotations, or external.

17.1.3. Level 3: Complete OSIS document

All the requirements of Level 2 must be fulfilled.

All notes, front and back matter, illustrations, section heads, and other non-canonical phenomena of the source edition must be included.

17.1.4. Level 4: Scholarly OSIS document

All the requirements of Level 3 must be fulfilled.

Substantial critical apparatus must be available in the text, such as: Strong's or comparable numbering of words; part-of-speech and/or other linguistic markup; encoding of variant readings, critical apparatus, and the like; extensive translation, scholarly, interpretive, or other notes.

At least highly significant persons and places in the text must be marked as names, and refer to the normative form of the corresponding individual (the BIble Technologies Group is preparing normative lists at this time). Where such identification is a matter of non-obvious interpretation, that fact must be marked, and the encoders' practices and biases should be duly noted in the front matter.

The text must also conform to the requirements of Level 3 Quality as described below.

17.2. Quality levels

The conformance levels defined above do not specify the level of accuracy and proofreading of the text proper. This is instead measured by the following scale of "Quality":

17.3. Level 1: Sub-OCR Quality

The text may have many typographical errors; essentially, it is unproofread text from automated OCR, probably of a less-than-ideal original.

17.4. Level 2: OCR Quality

The text may have up to 5 typographical errors per source page. It may be unproofread output from ideal OCR of an ideal source, or may have been run at least through rudimentary spell-checking or vocabulary counting and repair, or entered by a double-keying or similar service that maintains accuracy to the required level.

17.5. Level 3: Proof Quality

There may not be more than an average of 1 error per source page (or per 2000 characters of content) as compared with the stated copy text. This requirement does not preclude producing new editions, which for example may fix typos in the original, normalize spelling of older texts, and so on. However, in such cases it is recommended that the best available copy of the source text as it existed prior to such modernizations, also be made available.

17.6. Level 4: Trusted Quality

A Trusted Quality document must fulfill all the requirements of a Proof Quality document, and must also have been in public use for at least one year, and read by at least 5 independent proofreaders, with all noted errors fixed. The text should have available a complete log of changes made since it reached Proof Quality. Random spot-checks of at least 3% of the text must come up with no instances of more than 1 error per 5 pages (or 10,000 characters of content).

18. Application Requirements

Applications should avoid making any processing distinctions between elements represented as non-crossing single elements or as milestone pairs.

Applications must interpret OSIS references as accurately as is feasible, but apply smart fallback as needed. For example, grains will not map across translations or languages, though most will typically survive changes between successive editions of the same text, or differences between British and American English versions. Applications should in general at least offer to take the user to the nearest reliably-findable place; in this case, the verse.

Applications must be able to interpret the OSIS elements and process them in a manner consistent with their express intent as specified in this document, and in accordance with standard practices of Bible publishing. For example, applications should be capable of distinguishing the typography used for inscriptions, the divine Name, verse labels and references, foreign insertions in the text, notes, and so on in ways readily recognizable to users of print Bibles.

The Bible Technologies group also strongly advocates making all software, and especially all OSIS-aware software, accessible to print-disabled users. This includes details such as providing text alternates for all graphics, not marking up poetry such that it can only be line-broken given certain line widths or font sizes; not making crucial distinctions only via color, subtleties of font, etc.; and not using tables gratuitously to achieve formatting goals rather than to represent truly tabular information. Subtle technical factors can also ruin otherwise accessible software, for example, the order in which panes are drawn. Implementors are strongly encouraged to consult with experts on accessibility, and obtain specific critical testing and review by print-disabled users before finalizing product releases. The Bible Technology will, as resources permit, be glad to help connect implementors with accessibility experts.

19. Alphabetical list of Elements

  • NAME: PLACEMENT
  • a: Content inline
  • abbr: Content inline
  • actor: castGroup structure
  • caption: Figure structure
  • castGroup: castGroup structure
  • castItem: castGroup structure
  • castList: castGroup structure
  • catchWord: Annotation
  • cell: table structure
  • chapter: Main content
  • closer: Epistolary structure
  • contributor: Dublin Core (in work)
  • coverage: Dublin Core (in work)
  • creator: Dublin Core (in work)
  • date: Dublin Core (in work)
  • description: Dublin Core (in work)
  • div: Main structure
  • divineName: Content inline
  • figure: Figure structure
  • foreign: Main content
  • format: Dublin Core (in work)
  • head: Main content
  • header: Header
  • hi: Content inline
  • identifier: Dublin Core (in work)
  • index: Content inline
  • inscription: Content inline
  • item: List structure
  • l: Poetic structure
  • label: List structure
  • language: Dublin Core (in work)
  • lb: Poetic structure
  • lg: Poetic structure
  • list: List structure
  • mentioned: Annotation
  • milestone: Annotation
  • milestoneEnd: (deprecated -- do not use)
  • milestoneStart: (deprecated -- do not use)
  • name: Content inline
  • note: Content inline
  • osis: Header
  • osisCorpus: Header
  • osisText: Header
  • p: Content inline
  • publisher: Dublin Core (in work)
  • q: Content inline
  • rdg: Content inline
  • reference: Reference system
  • refSystem: Header (in work)
  • relation: Dublin Core (in work)
  • revisionDesc: Header
  • rights: Dublin Core (in work)
  • role: castGroup structure
  • roleDesc: castGroup structure
  • row: table structure
  • salute: Epistolary
  • scope: Dublin Core (in work)
  • seg: Content inline
  • signed: Epistolary
  • source: Dublin Core (in work)
  • speaker: Content structure
  • speech: Content structure
  • subject: Dublin Core (in work)
  • table: table structure
  • teiHeader: Header (in work)
  • title: Dublin Core (in work)
  • titlePage: Content structure
  • transChange: Content inline
  • type: Dublin Core (in work)
  • verse: Content inline
  • w: Content inline
  • work: Header

20. Alphabetical list of Attributes and normative values

20.1. Global attributes

These global attributes are in addition to xml:base, xml:lang, and xml:space which are defined by the XML standard itself.

Attribute name DataType Usage Description
annotateRef xs:string optional
annotateType osisAnnotation optional
ID xs:ID optional May be added to any element, generally to make that element accessible as a link target for generic hypertext browsers, or for the OSIS a element.
osisID osisIDType optional The osisID attribute identifies the element bearing it as a container for actual canonically-referenceable text, and provides the applicable osisID: osisID="Matt.1.1". It must not be used on elements that merely refer to, or discuss, a canonically-referenceable text. For those cases, use the annoteWork and osisRef attributes, instead. See the section on reference systems for details on the form required for this attribute's value.
canonical true | false optional The canonical attribute identifies the element bearing it as containing actual text of the work being encoded, as opposed to annotations, commentary, inserted headings, header metadata, notes, and other (non-canonical) information. Its value inherits in the same way as xml:lang. That is, the value applies to all descendant elements except where overridden.
resp xs:string optional This attribute, whose name is short for "responsible party", may be coded on any element to identify the party primarily responsible for that element and its content. For example, it might identify a member of a translation team; or on a note, it might identify the author of the note. Each distinct responsible party must be identified by the same value of this attribute wherever they are identified at all (that is, it is not permitted to use their initials sometimes, their last names other times, etc.). A list of responsible parties should be provided in the front matter or in the header.
type xs:string (several element types restrict the values, as listed below). optional The type attribute allows encoders to identify more precise distinctions within the borad applicability of any given element. For example, the div (division) element has many subtypes, such as bookGroup, concordance, dedication, glossary, etc. Many other element types also have pre-defined values provided for the type attribute. Some but not all of those element types also permit users to add their own values, so long as they begin with "x-". When a predefined type is applicable, it must be used instead of creating a new type.
subType xs:string optional In the rare event that the type attribute does not provide a fine-enough grained distinction of element types, the sub-type attribute may be used to make such distinctions. There are generally no restrictions on the values permitted for subType, except that the encoder should be consistent, and should document the meaning of any values used.
n xs:string optional This attribute is identical to the TEI n attribute, and may be used to provide a name or number to identify the particular element instance. However, it should not be used to encode a value for which the osisID, osisRef, or ____ attribute is applicable.
xml:lang xs:language optional This attribute is defined by the XML standard itself, and identifies the primary natural language of the content of an element. The value of this attribute is inherited; that is, any contained elements are presumed to be in the same language, unless they override it by specifying their own explicit xml:lang attribute value. The form of the xml:lang attribute is constrained by Internet specifications, particularly IETF RFC 1766, Tags for the Identification of Languages. Such tags consist of a 2-letter language code from ISO 639 (see http://www.oasis-open.org/cover/iso639a.html), optionally followed by a two letter country code from ISO 3166 (see http://www.oasis-open.org/cover/country3166.html). For example, "de" or "en-GB" Alternatively, they may be codes from the IANA registry at http://www.iana.org/assignments/language-tags. Remaining languages should use SIL Ethnologue codes (see http://www.ethnologue.com/codes/).
script osisScripts optional This attribute provides a slight extension beyond the capabilities of the xml:lang attribute. For many languages, it is enough to specify the language itself, and the country where it is spoken (say, Canadian vs. French dialects of the French language). However, there are cases where a given language community may use multiple writing systems: either different character sets and character usage rules; different spelling or other conventions; etc. In such cases, the particular script system used for writing the current work (or element within a work) must be specified via this attribute. This attribute inherits in precisely the same manner as xml:lang.

20.2. Normative values for the type attribute, by element

The heading for each basic element type below, indicates whether the list of values provided is extensible (by adding names beginning with "x-", or non-extensible).

Users who find values potentially of general use, that are not already provided, are asked to send them to the editors for possible incorporation into future versions of the specification. Likewise, users who discover any substantial ambiguity in the values provided, are asked to notify us and to provide examples and explanations, so that we can attempt to rectify any such problem.

20.2.1. annotateType

The annotateType attribute, which is available on all content elements, is to be used along with the annotateRef attribute, to indicate the type of annotation is being made to another work or portion of another work. This sort of reference can point to anything that can be pointed to using an osisRef so the annotation about a word, phrase, verse, chapter or larger portion of text.

These values characterize the annotation, not the work that is being annotated. They will be particularly helpful in systems where annotations of a particular type, rebuttal for example, are being sought for a particular work.

If the type of annotation you are making does not appear in this list, use the OSIS attribute extension, that is, "x-" in front of your attribute value.

  • commentary A comment or fuller commentary on the reference given by the annotateRef attribute.
  • exposition A development of the meaning of the reference given by the annotateRef attribute..
  • meditation A mediatation on the reference given by the annotateRef attribute..
  • outline An outline of the reference given by the annotateRef attribute..
  • rebuttal A rebuttal of one or more points in the reference given by the annotateRef attribute..
  • sermon A sermon based on the reference given by the annotateRef attribute.
  • studyGuide A studyguide on the reference given by the annotateRef attribute.
  • translation A translation of the reference given by the annotateRef attribute.

20.2.2. calendar

The standard calendar varies by historical time period as well as culture. We have not attempted to list all the possible calendars that might be used in OSIS documents, but provide the following starter set. Suggestions of other calendars with references to documentation would be greatly appreciated.

For cases where the required calendar is not one of the following values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your calendar.

  • Chinese Information on the Chinese calendar can be found at: http://webexhibits.org/calendars/calendar-chinese.html
  • Gregorian Standard calendar in use in the US and Europe. For further information see: http://www.geocities.com/calendopaedia/gregory.htm
  • Islamic Standard calendar in Muslim countries and religious communities. For further information see: http://webexhibits.org/calendars/calendar-islamic.html
  • ISO This is not a separate calendar from the Gregorian but is a specific notation for recording dates. For further information see: http://www.cl.cam.ac.uk/~mgk25/iso-time.html
  • Jewish Official calendar of Israel and for religious purposes. For further information see: http://webexhibits.org/calendars/calendar-jewish.html
  • Julian Largely historical but note that the Julian calendar continues in use by the Russian Orthodox Church. For further information see: http://www.geocities.com/calendopaedia/julian.htm

20.2.3. transChange

The type values on the transChange element is used to indicate a departure from a literal rendering of the source text. This happens most often when words are added to a translation to make the meaning of the text clearer or when the grammatical structures of the translation language do not offer same tenses for example, as the source language.

If the user encounters a change in translation that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute.

  • added Words added.
  • amplified More than addition of words to smooth out a translation.
  • changed Words are changed in the translation, such as modern spellings.
  • deleted Words that appear in the original but not in the translation.
  • moved Words that are moved to better represent the meaning of the text being translated from their original order.
  • tenseChange Indicates a change of the tense from the original to one that occurs in the translation language.

20.2.4. div

The type attribute for div mainly identifies larger sections that occur in print volumes, especially Bibles. This list was determined in part by examining a large selection of print Bibles, and covers most things that seem to be common. However, the list may be extended if necessary by adding names beginning "x-".

  • acknowledgement Standard acknowledgement page.
  • afterword The afterword in a text.
  • annotant Signals an annotation of another text.
  • appendix The appendix, in Bibles usually where maps, tables and similar material is found.
  • article An short work, usually by a separate author from the main work, on a particular theme or topic.
  • back Similar to appendix. Legacy of generic encoding systems that divide texts into front, body and back material.
  • body The main portion of a text.
  • book Bibles generally refer to the Book of Genesis. While at variance with standard publishing terminology, there is no good reason to not continue this tradition.
  • bookGroup Should be used in Bibles to contain groups of books, such as gathering all the books of the Torah or similar groups.
  • chapter Standard chapter as is found in a textbook.
  • colophon Most often found in hand written texts to identify the author, place of composition but does occur in some printed works.
  • commentary Useful for separating divisions in a text that have blocks of Bible text from blocks of text that are commentaries on the Bible text.
  • concordance Should be used for short concordances that are bound with Bibles and other works. Full concordances are texts in their own right.
  • coverPage A page in printed books before the actual title page.
  • dedication A page, usually in gift Bibles, that record the gift of the Bible to a particular individual.
  • devotional Should be used to indicate that the division contains a short worship service.
  • entry Best used in the sense of an entry in a dictionary.
  • front
  • gazetteer
  • glossary
  • imprimatur
  • index
  • introduction
  • majorSection
  • map
  • outline
  • paragraph
  • part
  • preface
  • section
  • subSection
  • summary
  • titlePage

20.2.5. Identifier

The type attribute on the identifier element is used to identify the identifier system from which the identifier was obtained. Note that the values for the type attribute must be entered exactly as shown, all others must use the "x-" extension mechanism.

If the user uses an identifier system that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • Dewey Dewey Decimal System
  • DOI Digital Object Identifier
  • ISBN International Standard Book Number
  • ISSN International Standard Serial Number
  • LCCN Library of Congress Control Number
  • OSIS Open Scriptural Information Standard
  • SICI Serial Item and Contribution Identifier
  • URI Uniform Resource Identifier
  • URL Uniform Resource Locator
  • URN Uniform Resource Name

20.2.6. language

The language element has two attributes with enumerated values. There is the type attribute as well as use attribute. The values for both are enumerated below.

20.2.6.1. type attribute on <language>

The type attribute on the language element is used to identify the authority for the value found in the element content. This provides the user of the file a reference that will assist them in determining the meaning of the content of the element. Different authorities have different names for the same languages and knowing which authority issued a particular name can be quite helpful.

If the user uses an authority that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • IANA Internet Assigned Numbers Authority: Language codes from the IANA registry: http://www.iana.org/assignments/language-tags.
  • IETF Internet Engineering Task Force: http://www.ietf.org/rfc/rfc1766.txt
  • ISO-639-1 International Organization for Standardization: http://www.oasis-open.org/cover/iso639.html
  • ISO-639-2 International Organization for Standardization: http://lcweb.loc.gov/standards/iso639-2/langhome.html (from the Library of Congress website)
  • ISO-639-2-B International Organization for Standardization: (same list as ISO-639-2 but in bibliographic order.)
  • ISO-639-2-T International Organization for Standardization: (same list as ISO-639-2 but in terminology code order.)
  • LINGUIST Linguist List: A resource maintained by linguists, http://www.linguistlist.org/.
  • other Does not use the "x-" extension, simply put "other."
  • SIL SIL International (formerly, Summer Institute for Linguistics): http://www.ethnologue.com/codes/ (the definitive site for language codes).
20.2.6.2. use attribute on <language>

The use attribute on the language element is used to identify how the language identified in the language element is used in the text. The most common uses are noted in this enumerations.

The values that are duplicates, that is: original and source or target and translation are not errors. Communities have grown up around using one term or the other and since they are equivalent, there appeared to be no reason to arbitrarily pick one over the other. Users should be consistent in their usage within a document and if possible, within collections of documents.

If the user needs a use of language that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • base Language is used as the primary language of the text.
  • didactic Language is used for instruction, such as in a grammar, in the text.
  • interlinear As the name implies, one of two or possibly more languages used to represent a text, such as English and Latin. The Loeb translation series being a good example.
  • original Use where the language is used for the text that is being translated. Duplicate of "source" value below.
  • quotation Language used for quotations in the text.
  • source Use where the language is used for the text that is being translated. Duplicate of "original" above.
  • target Use for the language into which a translation is being made. Duplicate of "translation" below.
  • translation Use for the language into which a translation is being made. Duplicate of "target" above.

20.2.7. milestone

The type attribute on the milestone element is used to identify what type of point is being indicated. Note that the values for the type attribute must be entered exactly as shown, all others must use the "x-" extension mechanism.

If the user needs to indicate point in the text that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • columnMarks the end of a column where there is a multi-column display.
  • footer Marks the footer region of a page.
  • halfLine Used to mark half-line units if not otherwise encoded.
  • header Marks the header region of a page.
  • line Marks line breaks, particularly important in recording appearance of an original text, such as a manuscript.
  • pb Marks a page break in a text.
  • screen Marks a preferred place for breaks in an on-screen rendering of the text.

20.2.8. name

The type attribute on the name element is used to identify the type of name that is being encoded. This is important for searching software to be able to distinguish geographic names from personal names or to create lists of particular types of names. Note that the values for the type attribute must be entered exactly as shown, all others must use the "x-" extension mechanism.

If the user needs to record a type of name in the text that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • geographic Name of a place or location.
  • holiday Name of a holiday or festival.
  • nonhuman Name of any nonhuman other than the Deity. For the latter, see divineName.
  • person Name of any person.
  • ritual Name of a ritual.

20.2.9. notes

The type attribute on the note element is used to identify the type of note that appears in the text. This is important for searching software to be able to find notes of a particular type, or to suppress notes that are not of interest for a particular reader or purpose. Note that the values for the type attribute must be entered exactly as shown, all others must use the "x-" extension mechanism.

If the user needs to record a type of note in the text that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • allusion Use for a note that records an allusion in the text. Ex: "Call me Ishmael" in a modern novel is an allusion to Moby Dick by Herman Melville. The text does not cite Melville but the encoder notes the allusion.
  • alternative Use for a note that provides an alternative to the main text, usually with a translation. Differs from variant, see below, in that variant is of the original text, not the translation.
  • background Use for a note that provides background information, usually about unfamiliar practices, terms or measures.
  • citation Use for a note that contains a formal citation to another work, modern footnote is a good example.
  • crossReference Use for a note that provides a cross reference to material relevant to the issue under discussion in the text.
  • devotional Use for a note that details devotional aspects of text or issues in the text under discussion.
  • exegesis Use for a note that makes the case for a particular interpretation of a text.
  • explanation Use for a note that provides a brief explanation of a term or phrase.
  • study Use for notes that are of particular interest to students (formal or self-directed).
  • translation Use for notes that comment on issues in a translation or particular translation decisions.
  • variant Use for notes that provide alternatives to the original text that underlies a particular translation. Most annoying examples read: "Some Arabic manuscripts read..." If you provide a variant, please provide a formal citation. To do otherwise, simply annoys the reader.

20.2.10. subject

The following are the valid values for the type attribute on the subject element. Note that what is entered is in bold and the following material is just for the convenience of the reader. Note that an XML parser will expect the values to be entered exactly as you see them in this list. Case, that is upper or lower, matters to an XML parser. An attribute with the value ATLA is VALID, but one with the value atla is INVALID. You have been warned.

  • ATLAAmerican Theological Libraries Association
  • BILDI Biblewissenschaftliche Literaturdokumentation Innsbruck
  • DBC Dutch Basic Classification
  • DDC Dewey Decimal Classification
  • EUT Estonian Universal Thesaurus
  • FGT Finnish General Thesaurus
  • LCC Library of Congress Classification
  • LCSH Library of Congress Subject Heading
  • MeSH Medical Subject Headings
  • NLSH National Library Subject Headings (National Library of Poland)
  • RSWK Regeln für den Schlagwortkatalog
  • SEARS Sears List of Subject Headings
  • SOG Soggettario
  • SWD_RSWK Swiss National Library
  • UDC Universal Decimal Classification
  • VAT Vatican Library

20.2.11. titles

The type attribute on the title element is used to allow special rendering of particular titles, as well as searching for particular types of titles in the text.identify the type of note that appears in the text. Note that the values for the type attribute must be entered exactly as shown, all others must use the "x-" extension mechanism.

If the user needs to record a type of title in the text that is not covered by these values, please use the OSIS attribute extension mechanism, "x-" in front of the name of your value for this attribute. Such additions systems should be brought to the attention of the OSIS editors.

  • acrostic Use for tites where alignment of first or final letters of words in the title are meaningful.
  • continued Use for titles that are continuations of some other part of the title.
  • main Use for the main title of a work.
  • parallel Use where titles are given in alternative languages.
  • psalm Use in the Psalms where what are considered "titles" in the English text are actually numbered as verses in the Hebrew text.
  • sub Use for subparts of a title.

21. osisIDs: Construction Rules

The really adventerous reader will consult the osisCore.2.0 schema for the regular expression that governs the form of osisIDs. For those in a hurry or who simply want to avoid the complexity of XML Schema regexes (the abbreviated form of regular expressions) the following guide should suffice.

Any osisID is divided into a number of parts, some of which are optional, that is they can be omitted and still have a valid osisID. The following breaks out the structure of an osisID into its various parts and notes what is allowed in each part and what parts are required.

21.1. Prefix: (optional)

The prefix to an osisID must contain at least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods, and concluding in a colon ":". Note that if you use a prefix, the colon is required. The prefix is optional.

Some examples of valid prefixes include:

  • Bible:
  • Bible.French:
  • Spurgeon.Commentaries_Job:

21.2. Main (required)

The main part of an osisID consists of at least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods. The main part of the osisID is required.

Note that one difference from traditional identification of Bible verses that OSIS uses a period to separate the verse from the chapter. One usually sees, Gen. 1:1. That is what should be displayed to the reader of a OSIS text, but use of whitespace as a separator (between Gen. and chapter 1, in XML causes problems. So, the whitespace was replaced by a period.

Some examples of valid main parts of an osisID include:

  • Gen.
  • Mark
  • Mark.8
  • Matt.6.1

21.3. Extension (optional)

While standard citation systems are well known and should be covered by the main part of the osisID, there are cases where such systems have been extended. Some of those extensions are standard and other are not.

In order to allow for extension of citation systems, OSIS allows a standard citation to be followed by the exclamation mark "!" which signals that what follows is not part of the standard reference. This allows systems that do not recognize extensions to at least put the user at the starting place of the standard reference.

The beginning exclamation mark is required, if the extension mechanism is used and is followed by least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods.

Some examples of valid extensions to an osisID include:

  • Prov.26.12!b ID for the second half of verse 12.
  • other examples?

22. osisRefs: Construction Rules

The osisRef regex is over twice as long as the osisID regex, in part because of the addiional capabilities of an osisRef. The allowable characters are basically the same but there are some nuances to constructing an osisRef. The following guide should get you past all of the common cases, and even a few of the odder ones.

22.1. Prefix: (optional)

The prefix to an osisID must contain at least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods, and concluding in a colon ":". Note that if you use a prefix, the colon is required. The prefix is optional.

Note that if you omit the prefix on an osisRef, it is optional afterall, your reference can only point to another location in the OSIS text where you are inserting the osisRef. This is the equivalent of the osisID without a prefix, it defaults to the text that you are working in at the moment. For purposed of illustration, all the osisRefs shown below have the prefix attached.

Some examples of valid prefixes include:

  • Bible:
  • Bible.French:
  • Spurgeon.Commentaries_Job:

22.2. Main (required)

The main part of an osisRef consists of at least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods. The main part of the osisRef is required.

Note that one difference from traditional identification of Bible verses that OSIS uses a period to separate the verse from the chapter. One usually sees, Gen. 1:1. That is what should be displayed to the reader of a OSIS text, but use of whitespace as a separator (between Gen. and chapter 1, in XML causes problems. So, the whitespace was replaced by a period.

Some examples of valid main parts of an osisRef include:

  • Gen.
  • Mark
  • Mark.8
  • Matt.6.1

22.3. Extension (optional)

While standard citation systems are well known and should be covered by the main part of the osisRef, there are cases where such systems have been extended. Some of those extensions are standard and other are not.

In order to allow for references that use an extension of citation systems, OSIS allows a standard citation to be followed by the exclamation mark "!" which signals that what follows is not part of the standard reference. This allows systems that do not recognize extensions to at least put the user at the starting place of the standard reference.

The beginning exclamation mark is required, if the extension mechanism is used and is followed by least one letter, number or underscore, that may be followed by any number of letters, numbers or underscores, separated by periods.

Some examples of valid extensions to an osisRef include:

  • Prov.26.12!b osisRef for the second half of verse 12.
  • other examples?

22.4. Grains (optional)

One shortcoming of most reference systems is the inability to point to a particular place in a line of text. This is of particular interest for Bible study, where the user wants to point to a particular word in a passage, not the entire passage itself. OSIS developed a syntax that follows the prefix, main osisRef and even the extension (if present) that allows you to do exactly that.

The grain operators come in two types: 1) cp, which allows you to point at a particular character in the text, and 2) s, which allows you to point at a string of characters. It is probably easier to illustrate these separately.

The cp grain operator is a number, enclosed by square brackets and preceded by the "@" sign, all of which follows, at a mimimum, the main part of an osisRef. For example:

  • RSV:Gen.1.1@cp[8] Points at the starting character of the word "beginning."
  • RSV:Gen.3.20@cp[32] Points to the starting character of the word "Eve."

This operator will be the most useful for automated systems that allow users to point and select a point in the text for automatic generation of this operator. When this syntax was being developed, the editors made the mistake of picking an example before considering how tedious it was to count spaces, apostrophes, and other punctuation that goes into the total for a cp operator. Users who wish to avoid the tedium of (and error prone as well) counting characters, may wish to use the s operator.

The s grain operator is a string, enclosed by square brakets and preceded by the "@" sign, all of which follows, at a mimimum, the main part of an osisRef. For example:

  • RSV:Gen.1.1@s[beginning] Points at the starting character of the word "beginning."
  • RSV:Gen.3.20@s[Eve] Points to the starting character of the word "Eve."

You may wish to convince yourself that the s operator is easier to use than cp but to each his own.

Warning: Note that the s operator does not allow spaces. That is to say that you cannot put a phrase between the square brakets. That limiation is due to the handling of spaces in XML. It was an issue that the editors struggled with for some time but ultimately, it was decided that word level matching would meet most users needs.

22.5. Ranges (optional)

It is often the case that texts make references to a range of Bible verses and with the osisRef mechanism, not only duplicates that ability, but also provides for the grain matching mentioned above.

The beginning of a range in an osisRef is indicated by a hyphen "-" character that occurs at the very end of the first part of the range. That hyphen is immediately followed by the same order of expression found in the first part, with one exception, there is no prefix allowed on the second half of an osisRef range.

The reason to disallow a prefix on the second half of a range is quite simple. A range, at least in the OSIS sense, is defined as occurring within a work. That is to say that a range that attempted to say: Bible:Gen.1.1-Livy:Bk.1, would make no sense to any processor. So, when using the range operator, be sure that the range occurs within a single work.

With the omission of the prefix, the second half of a range follows the same rules as the first half.

23. Selected Contributor Roles

This is a selected set of the most common role names likely to be needed for basic encoding. The full set of relator codes on which this listing (and the descriptions are based, was taken from: MARC Code List: Relator Codes -- Term Sequence (http://lcweb.loc.gov/marc/relators/re0002r1.html). This listing will be followed for later OSIS modules.

  • ann Annotator: Use for a person who writes manuscript annotations on a printed item.
  • art Artist: Use for a person (e.g., a painter) who conceives, and perhaps also implements, an original graphic design or work of art.
  • aut Author: Use for a person or corporate body chiefly responsiblefor the intellectual or artistic content of a work, usually printed text. This term may also be used when more than one person or body bears such responsibility.
  • cwt Commentator for written text: Use for a person or corporate body responsible for the commentary or explanatory notes about a text. For the writer of manuscript annotations in a printed book, use Annotator
  • com Compiler: Use for a person who produces a work or publication by selecting and putting together material from the works of various persons or bodies.
  • ctb Contributor: Use for one whose work has been contributed to a larger work, such as an anthology, serial publication, or other compilation of individual works. Do not use for someone whose sole function in relation to a work is as author, editor, compiler or translator.
  • cre Creator: Use for a person or corporate body responsible for the intellectual or artistic content of a work.
  • edt Editor: Use for a person who prepares for publication a work not primarily his/her own, such as by elucidating text, adding introductory or other critical matter, or technically directing an editorial staff.
  • ill Illustrator: Use for the person who conceives, and perhaps also implements, a design or illustration, usually to accompany a written text.
  • pbl Publisher
  • trl Translator: Use for a person who renders a text from one language into another, or from an older form of a language into the modern form.

24. Normative Abbreviations for canonical and deutero-canonical books

These names are taken from the SBL Manual of Style, which also provides normative abbreviations for works of classical literature, manuscripts, journals, and other information objects of interest to Biblical studies.

24.1.

Hebrew Bible/Old Testament

  • Gen Genesis
  • Exod Exodus
  • Lev Leviticus
  • Num Numbers
  • Deut Deuteronomy
  • Josh Joshua
  • Judg Judges
  • Ruth Ruth
  • 1Sam 1 Samuel
  • 2Sam 2 Samuel
  • 1Kgs 1 Kings
  • 2Kgs 2 Kings
  • 1Chr 1 Chronicles
  • 2Chr 2 Chronicles
  • Ezra Ezra
  • Neh Nehemiah
  • Esth Esther
  • Job Job
  • Ps Psalms
  • Prov Proverbs
  • Eccl Ecclesiastes
  • Song Song of Solomon
  • Isa Isaiah
  • Jer Jeremiah
  • Lam Lamentations
  • Ezek Ezekiel
  • Dan Daniel
  • Hos Hosea
  • Joel Joel
  • Amos Amos
  • Obad Obadiah
  • Jonah Jonah
  • Mic Micah
  • Nah Nahum
  • Hab Habakkuk
  • Zeph Zephaniah
  • Hag Haggai
  • Zech Zechariah
  • Mal Malachi

New Testament

  • Matt Matthew
  • Mark Mark
  • Luke Luke
  • John John
  • Acts Acts
  • Rom Romans
  • 1Cor 1 Corinthians
  • 2Cor 2 Corinthians
  • Gal Galatians
  • Eph Ephesians
  • Phil Philippians
  • Col Colossians
  • 1Thess 1 Thessalonians
  • 2Thess 2 Thessalonians
  • 1Tim 1 Timothy
  • 2Tim 2 Timothy
  • Titus Titus
  • Phlm Philemon
  • Heb Hebrews
  • Jas James
  • 1Pet 1 Peter
  • 2Pet 2 Peter
  • 1John 1 John
  • 2John 2 John
  • 3John 3 John
  • Jude Jude
  • Rev Revelation

Apocrypha and Septuagint

  • Bar Baruch
  • AddDan Additions to Daniel
  • PrAzar Prayer of Azariah
  • Bel Bel and the Dragon
  • SgThree Song of the Three Young Men
  • Sus Susanna
  • 1Esd 1 Esdras
  • 2Esd 2 Esdras
  • AddEsth Additions to Esther
  • EpJer Epistle of Jeremiah
  • Jdt Judith
  • 1Macc 1 Maccabees
  • 2Macc 2 Maccabees
  • 3Macc 3 Maccabees
  • 4Macc 4 Maccabees
  • PrMan Prayer of Manasseh
  • Sir Sirach/Ecclesiasticus
  • Tob Tobit
  • Wis Wisdom of Solomon

These abbreviations are as defined in the SBL Handbook of Style published by the Society of Biblical Literature, except that spaces have been removed from the abbreviations for some Apocryphal and Septuagint books.

Note that because XML prohibits digits as the first character of IDs and other XML names, these abbreviations cannot be used directly as XML IDs, and are not of that schema datatype.

25. Encoding commentaries

(this section is still to be written)

26. Encoding devotionals, lectionaries, and time-organized documents

Information that is organized by time, must mark those organizational units using the appropriate div or other elements; the applicable time goes on the osisID attribute.

27. Encoding multilingual editions

(this section is still to be written)

28. Encoding glossaries, dictionaries, and lexica

A set of dictionary markup elements, drawn directly from the TEI, is currently in preparation, and is expected to be added in the next release of OSIS, as an optional add-on module. The main entry terms will be used as the osisID values.

29. Standard OSIS Codes for Bible Editions

All Bible Edition codes must have the language code for the target language in question, then a colon, then the abbreviation shown here.

29.1. Ancient language editions

  • Steph Stephanus GNT, 1551
  • Vul Latin Vulgate, 1405
  • Erasmus Latin translation by Desiderius Erasmus Roterodamus, 1516
  • Mas Masoretic text (various, ~900-1100)
  • BHS Biblia Hebraica Stuttgartsiensa
  • NA Nestle-Aland Greek New Testament (may suffix edition number, such as "NA27")
  • LXX Greek Septuagint

29.1.1. English Editions (prefix "en:")

  • AAT The Complete Bible: An American Translation, by Edgar Goodspeed and J. M. Powis Smith, 1939.
  • ABT The Afro Bible Translation
  • ATB The Alternate Translation Bible
  • ASV American Standard Version
  • AB The Amplified Bible
  • ALT Analytical-Literal Translation
  • ASL American Sign Language Translation
  • AV Authorized Version (same as KJV)
  • Bar The New Testament: A New Translation, by William Barclay
  • BB The Biker Bible
  • BWE Bible in WorldWide English
  • CCB Christian Community Bible
  • COM The Common Edition: New Testament
  • COV Covenant Edition New Testament
  • CJB Complete Jewish Bible
  • CONC Concordant Version
  • CEV Contemporary English Version
  • CPV Cotton Patch Version, tr. Clarence Jordan
  • Dar Darby
  • DR Douay-Rheims
  • DRP David Robert Palmer's translations of the gospels
  • EMTV English Majority Text Version
  • ENT Extreme New Testament
  • ERV Easy-to-Read Version
  • ESV English Standard Version
  • FF Ferrar Fenton Bible
  • GLW God's Living Word
  • GNC God's New Covenant: A New Testament Translation, by Heinz W. Cassirer
  • GW God's Word
  • GNB Good News Bible (TEV)
  • HCSB Holman Christian Standard Bible
  • ICB International Children's Bible (children's version of the NCV)
  • ISB International Standard Bible (formerly titled The Simple English Bible)
  • ISV The International Standard Version
  • JBP New Testament in Modern English, by J.B. Phillips
  • JNT Jewish New Testament: A Translation of the New Testament That Expresses Its Jewishness
  • KJV King James Version
  • DKJB Defined King James Bible
  • KJII King James Version II (renamed to Literal Translation of the Holy Bible)
  • KJ21 King James for the 21st Century
  • KJ2000 King James 2000
  • LITV The Literal Translation of the Holy Bible (formerly named King James II)
  • MKJV Modern King James Version
  • RAV Revised Authorised Version (British edition of the NKJV)
  • RKJV Revised King James New Testament
  • TMB The Third Millennium Bible
  • UKJV Updated King James Version
  • LB Living Bible
  • MAEV Modern American English Vernacular
  • MLB Modern Language Bible: New Berkeley Version
  • Mof Bible: James Moffatt Translation
  • NAB New American Bible
  • NASB New American Standard Bible
  • MLB New Berkeley Version (see Modern Language Bible)
  • NCV New Century Version
  • NEB New English Bible
  • NET New English Translation
  • NEvT New Evangelical Translation
  • NIrV New Internation Reader's Version
  • NIV New International Version
  • NJB New Jerusalem Bible
  • NKJV New King James Version
  • NLV New Life Version
  • NLT New Living Translation
  • NRSV New Revised Standard Bible
  • NWT New World Translation (published by the Watchtower Bible and Tract Society of the Jehovah's Witnesses)
  • OBP The Original Bible Project
  • OSB Orthodox Study Bible
  • ONT The Original New Testament: The First Definitive Translation of the New Testament in 2000 Years, by Hugh Schonfield
  • PMB Postmodern Bible - Amos
  • Rec Recovery Version
  • REB The Revised English Bible (revision of NEB)
  • RSV Revised Standard Version
  • RV Revised Version, 1885
  • Sch The Schocken Bible
  • SEB The Simple English Bible
  • TM The Message
  • TMB The Third Millennium Bible
  • TEV Today's English Version
  • TNIV Today's New International Version
  • Tyn Tyndale
  • Wey Weymouth
  • WEB World English Bible
  • Wms The New Testament in the Language of the People, by Charles B. Williams)
  • WNT Wesley's New Testament
  • Wuest The New Testament (An Expanded Translation)
  • Wyc Wycliffe
  • Yes Yes Word (update of Tyndale translation)
  • YLT Young's Literal Translation of the Bible

29.1.2. Non-English Modern Languages

Thousands of additional languages have Bibles or portions; most of these have only one translation in the language. In those cases the language code as defined elsewhere in OSIS may be used, with no following name required.

  • Luther German by Martin Luther, 1534
  • Algonquin Tr. John Eliot, 1662
  • ReinaV Spanish Reina Valera

30. Complete list of USMARC Relator Codes

  • Actor act Use for a person who principally exhibits acting skills in a musical or dramatic presentation or entertainment.
  • Adapter adp Use for a person who 1) reworks a musical composition, usually for a different medium, or 2) rewrites novels or stories for motion pictures or other audiovisual medium.
  • Annotator ann Use for a person who writes manuscript annotations on a printed item.
  • Architect arc
  • Applicant app
  • Appraiser USE Expert
  • Arranger arr Use for a person who transcribes a musical composition, usually for a different medium from that of the original; in an arrangement the musical substance remains essentially unchanged.
  • Artist art Use for a person (e.g., a painter) who conceives, and perhaps also implements, an original graphic design or work of art, if specific codes (e.g., egr, etr) are not desired. For book illustrators, prefer Illustrator ill. (UF Graphic technician)
  • Assignee asg Use for a person or organization to whom a license for printing or publishing has been transferred.
  • Associated name asn Use as a general relator for a name associated with or found in an item or collection, or which cannot be determined to be that of a Former owner fmo or other designated relator indicative of provenance.
  • Attributed name att Use to relate an author, artist, etc. to a work for which there is or once was substantial authority for designating that person as author, creator, etc. of the work. (UF Supposed name)
  • Auctioneer auc Use for a person or corporate body in change or the estimation and public auctioning of goods, particularly books, artistic works, etc.
  • Author aut Use for a person or corporate body chiefly responsible for the intellectual or artistic content of a work. This term may also be used when more than one person or body bears such responsibility. (UF Joint author)
  • Author in quotations or text extracts aqt Use for a person whose work is largely quoted or extracted in a works to which he or she di not contribute directly. Such quotations are found particularly in exhibition catalogs, collections of photographs, etc.
  • Author of afterword, colophon, etc. aft Use for a person or corporate body responsible for an afterword, postface, colophon, etc. but who is not the but who is not the chief author of a work.
  • Author of introduction, etc. aui Use for a person or corporate body responsible for an introduction, preface, foreword, afterword, or other critical matter, but who is not the chief author.
  • Author of screenplay, etc. aus Use for a person or corporate body responsible for a motion picture screenplay, dialog, spoken commentary, etc.
  • Bibliographic antecedent ant Use for the author responsible for a work upon which the work represented by the catalog record is based. This may be appropriate for adaptations, sequels, continuations, indexes, etc.
  • Binder bnd
  • Binding designer bdd (UF Designer of binding)
  • Book designer bkd Use for the person or firm responsible for the entire graphic design of a book, including arrangement of type and illustration, choice of materials, and process used. (UF Designer of book)
  • Book producer bkp Use for the person or firm responsible for the production of books and other print media, if specific codes (e.g., bkd, egr, tyd, prt) are not desired. (UF Producer of book)
  • Bookjacket designer bjd (UF Designer of bookjacket)
  • Bookplate designer bpd (UF Designer of bookplate)
  • Bookseller bsl
  • Bowdlerizer USE Censor
  • Calligrapher cll
  • Cartographer ctg
  • Censor cns Use for a censor, bowdlerizer, expurgator, etc., official or private. (UF Bowdlerizer, Expurgator)
  • Choreographer chr Use for a person who composes or arranges dances or other movements (e.g., "master of swords") for a musical or dramatic presentation or entertainment.
  • Client cli Use for a person or organization for whom another person or organization is acting.
  • Collaborator clb Use for a person or corporate body that takes a limited part in the elaboration of a work of another author or that brings complements (e.g., appendices, notes) to the work of another author
  • Collector col Use for a person who has brought together material from various sources, which has been arranged, described, and cataloged as a collection. The collector is neither the creator of the material nor the person to whom manuscripts in the collection may have been addressed.
  • Collotyper clt
  • Commentator cmm Use for a person who provides interpretation, analysis, or a discussion of the subject matter on a recording, motion picture, or other audiovisual medium.
  • Compiler com Use for a person who produces a work or publication by selecting and putting together material from the works of various persons or bodies.
  • Complainant cpl Use for the party who applies to the courts for redress, usually in an equity proceeding.
  • Complainant-appellant cpt Use for a complainant who takes an appeal from one court or jurisdiction to another to reverse the judgment, usually in an equity proceeding.
  • Complainant-appellee cpe Use for a complainant against whom an appeal is taken from one court or jurisdiction to another to reverse the judgment, usually in an equity proceeding.
  • Composer cmp Use for a person who creates a musical work, usually a piece of music in manuscript or printed form.
  • Compositor cmt (UF Typesetter)
  • Conceptor ccp Use for a person or corporate body responsible for the original idea on which a work is based, this includes the scientific author of an audio-visual item and the conceptor of an advertisement.
  • Conductor cnd Use for a person who directs a performing group (orchestra, chorus, opera, etc.).
  • Consultant csl Use for the person called upon for professional advice or services in a specialized field of knowledge or training.
  • Contestant cos Use for the party who opposes, resists, or disputes, in a court of law, a claim, decision, result, etc.
  • Contestant-appellant cot Use for a contestant who takes an appeal from one court of law or jurisdiction to another to reverse the judgment.
  • Contestant-appellee coe Use for a contestant against whom an appeal is taken from one court of law or jurisdiction to another to reverse the judgment.
  • Contestee cts Use for the party defending a claim, decision, result, etc. being opposed, resisted, or disputed in a court of law.
  • Contestee-appellant ctt Use for a contestee who takes an appeal from one court or jurisdiction to another to reverse the judgment.
  • Contestee-appellee cte Use for a contestee against whom an appeal is taken from one court or jurisdiction to another to reverse the judgment.
  • Contractor ctr Use for the person or corporate body who enters into a contract with another person or corporate body to perform a specific task.
  • Copyright claimant cpc Use for the person listed as as copyright owner at the time of registration. Copyright can be granted or later transfered to another person or agent, at which time the claimant becomes the copyright holder.
  • Copyright holder cph
  • Corrector crr Use for a corrector of manuscripts, such as the scriptorium official who corrected the work of a scribe. For printed matter, use Proofreader pfr.
  • Correspondent crp Use for a person or organization who was either the writer or recipient of a letter or other communication.
  • Costume designer cst Use for a person who designs or makes costumes, fixes hair, etc., for a musical or dramatic presentation or entertainment.
  • Counterfeiter USE Forger
  • Curator of an exhibition cur Use for a person who is responsible for conceiving and organizing an exhibition.
  • Dancer dnc Use for a person who principally exhibits dancing skills in a musical or dramatic presentation or entertainment.
  • Dedicatee dte Use for a person or organization to whom a book, manuscript, etc., is dedicated (not the recipient of a gift).
  • Dedicator dto Use for the author of a dedication, which may be a formal statement or in epistolary or verse form.
  • Defendant dfd Use for the party defending or denying allegations made in a suit and against whom relief or recovery is sought in the courts, usually in a legal action.
  • Defendant-appellant dft Use for a defendant who takes an appeal from one court or jurisdiction to another to reverse the judgment, usually in a legal action.
  • Defendant-appellee dfe Use for a defendant against whom an appeal is taken from one court or jurisdiction to another to reverse the judgment, usually in a legal action.
  • Delineator dln Use for a person or organization executing technical drawings from others' designs.
  • Depositor dpt Use for a person or organization placing material in the physical custody of a library or repository without transferring the legal title.
  • Designer dsr Use for a person or organization responsible for design if specific codes (e.g., bkd, tyd) are not desired.
  • Designer of binding USE Binding designer
  • Designer of book USE Book designer
  • Designer of bookjacket USE Bookjacket designer
  • Designer of bookplate USE Bookplate designer
  • Designer of type USE Type designer
  • Director drt Use for a person who is responsible for the general management of a work or who supervises the production of a performance for stage, screen, or sound recording.
  • Dissertant dis Use for a person who presents a thesis for a university or higher-level educational degree.
  • Distributor dst Use for an agent or agency that has exclusive or shared marketing rights for an item.
  • Donor dnr Use for the donor of a book, manuscript, etc., to its present owner. Donors to previous owners are designated as Former owner fmo or Inscriber ins.
  • Draftsman drm Use for the person who prepares technical or mechanical drawings. (UF Technical draftsman)
  • Dubious author dub Use for a person or corporate body to which authorship has been dubiously or incorrectly ascribed.
  • Editor edt Use for a person who prepares for publication a work not primarily his/her own, such as by elucidating text, adding introductory or other critical matter, or technically directing an editorial staff.
  • Electrotyper elt
  • Engineer eng Use for a person or organization that is responsible for technical planning and design, particularly with construction.
  • Engraver egr
  • Etcher etr
  • Expert exp Use for a person in charge of the description and appraisal of the value of goods, particularly rare items, works of art, etc. (UF Appraiser)
  • Expurgator USE Censor
  • Film editor flm Use for an editor of a motion picture film. This term is used regardless of the medium upon which the motion picture is produced or manufactured (e.g., acetate film, video tape). (UF Motion picture editor)
  • Forger frg (UF Counterfeiter)
  • Former owner fmo Use for the person or organization who owned an item at any time in the past. Includes those to whom the material was once presented. The person or organization giving the item to the present owner is designated as Donor dnr
  • Funder fnd Use for the person or agency that furnished financial support for the production of the work.
  • Graphic technician USE Artist
  • Honoree hnr Use for the person in memory or honor of whom a book, manuscript, etc. is donated. (UF Memorial)
  • Host hst Use for the person who is invited or regularly leads a program (often broadcast) that includes other guests, performers, etc. (e.g., talk show host).
  • Illuminator ilu
  • Illustrator ill Use for the person who conceives, and perhaps also implements, a design or illustration, usually to accompany a written text.
  • Imprimatur USE Licensor
  • Inscriber ins Use for the person who signs a presentation statement.
  • Instrumentalist itr Use for a person who principally plays an instrument in a musical or dramatic presentation or entertainment.
  • Interviewee ive
  • Interviewer ivr
  • Inventor inv
  • Investigator USE Originator
  • Joint author USE Author
  • Landscape architect lsa Use for the person or organization whose work involves coordinating the arrangement of existing and proposed land features and structures.
  • Lender len Use for a person or organization permitting the temporary use of a book, manuscript, etc., such as for photocopying or microfilming.
  • Libelant lil Use for the party who files a libel in an ecclesiastical or admiralty case.
  • Libelant-appellant lit Use for a libelant who takes an appeal from one ecclesiastical court or admiralty to another to reverse the judgment.
  • Libelant-appellee lie Use for a libelant against whom an appeal is taken from one ecclesiastical court or admiralty to another to reverse the judgment.
  • Libelee lel Use for the party against whom a libel has been filed in an ecclesiastical court or admiralty.
  • Libelee-appellant let Use for a libelee who takes an appeal from one ecclesiastical court or admiralty to another to reverse the judgment.
  • Libelee-appellee lee Use for a libelee against whom an appeal is taken from one ecclesiastical court or admiralty to another to reverse the judgment.
  • Librettist lbt Use for the writer of the text of an opera, oratorio, etc.
  • Licensee lse Use for the original recipient of the right to print or publish.
  • Licensor lso Use for the signer of the license, imprimatur, etc. (UF Imprimatur)
  • Lithographer ltg Use for the person who prepares the stone or plate for lithographic printing, including a graphic artist creating a design directly on the surface from which printing will be done.
  • Lyricist lyr Use for the writer of the text of a song.
  • Memorial USE Honoree
  • Metadata contact mdc Use for the person or organization primarily responsible for compiling and maintaining the original description of a metadata set (e.g., geospatial metadata set).
  • Metal-engraver mte
  • Moderator mod Use for the person who leads a program (often broadcast) where topics are discussed, usually with participation of experts in fields related to the discussion.
  • Monitor mon Use for a person or organization that supervises compliance with the contract and is responsible for the report and controls its distribution. Sometimes referred to as the grantee, or controlling agency.
  • Motion picture editor USE Film editor
  • Musician mus Use for the person who performs music or contributes to the musical content of a work when it is not possible or desirable to identify the function more precisely.
  • Narrator nrt Use for the speaker who relates the particulars of an act, occurrence, or course of events.
  • Originator org Use for the author or agency performing the work, i.e., the name of a person or organization associated with the intellectual content of the work. This category does not include the publisher or personal affiliation, or sponsor except where it is also the corporate author. Includes a person designated in the work as investigator or principal investigator. (UF Principal investigator)
  • Other oth Use for relator codes from other formats which have no equivalent in USMARC or for terms which have not been assigned a code.
  • Papermaker ppm
  • Patent holder pth
  • Patron pat Use for the person responsible for commissioning a work. Usually a patron uses his or her means or influence to support the work of artists, writers, etc. This includes those who commission and pay for individual works.
  • Performer prf User for a person who exhibits musical or acting skills i a musical or dramatic presentation or entertainment, if specific codes for those functions (act, dnc, itr, voc, etc.) are not used. If specific codes are used, prf is used for a person whose principal skill is not known or specified.
  • Photographer pht Use for the person or organization responsible for taking photographs, whether they are used in their original form or as reproductions.
  • Plaintiff ptf Use for the party who complains or sues in court in a personal action, usually in a legal proceeding.
  • Plaintiff-appellant ptt Use for a plaintiff who takes an appeal from one court or jurisdiction to another to reverse the judgment, usually in a legal proceeding.
  • Plaintiff-appellee pte Use for a plaintiff against whom an appeal is taken from one court or jurisdiction to another to reverse the judgment, usually in a legal proceeding.
  • Platemaker plt
  • Plates, Printer of USE Printer of Plates
  • Principal investigator USE Originator
  • Printer prt Use for the person or organization who prints texts, whether from type or plates.
  • Printer of plates pop Use for the person or organization who prints illustrations from plates. (UF Plates, Printer of)
  • Process contact prc Use for a person or organization primarily responsible for performing or initiating a process, such as is done with the collection of metadata sets.
  • Producer pro Use for a person who is responsible for the making of a motion picture, including business aspects, management of the productions, and the commercial success of the work.
  • Producer of book USE Book producer
  • Production personnel prd Use for a person who is associated with the production (props, lighting, special effects, etc.) of a musical or dramatic presentation or entertainment.
  • Programmer prg Use for a person or corporate body responsible for the creation and/or maintenance of computer program design documents, source code, and machine-executable digital files and supporting documentation.
  • Promoter USE Thesis advisor
  • Proofreader pfr Use for a person who corrects printed matter. For manuscripts, use Corrector crr.
  • Publisher pbl
  • Publishing director pbd Use for a person who presides over the elaboration of a collective work to ensure its coherence or continuity. This includes editors-in-chief, literary editors, editors of series, etc.
  • Recipient rcp Use for the person to whom correspondence is addressed.
  • Recording engineer rce Use for a person who supervises the technical aspects of a sound or video recording session.
  • Redactor red Use for a person who writes or develops the framework for an item without being intellectually responsible for its content.
  • Renderer ren Use for the draftsman who prepares drawings of architectural designs (i.e., renderings) in accurate, representational perspective to show what the project will look like when completed.
  • Respondent rsp Use for the party who makes an answer to the courts pursuant to an application for redress, usually in an equity proceeding.
  • Respondent-appellant rst Use for a respondent who takes an appeal from one court or jurisdiction to another to reverse the judgment, usually in an equity proceeding.
  • Respondent-appellee rse Use for a respondent against whom an appeal is taken from one court or jurisdiction to another to reverse the judgment, usually in an equity proceeding.
  • Reviewer rev Use for a person or corporate body responsible for the review of book, motion picture, performance, etc.
  • Rubricator rbr
  • Scenarist sce Use for the author of a motion picture screenplay.
  • Scientific advisor sad Use for a person who brings scientific, pedagogical, or historical competence to the conception and realization on a work, particularly in the case of audio-visual items.
  • Scribe scr Use for a person who makes pen-facsimiles of printed matter, as well as for an amanuensis, and for a writer of manuscripts proper.
  • Sculptor scl Use when the more general term Artist art is not desired.
  • Secretary sec Use for a recorder, redactor, or other person responsible for expressing the views of a corporate body.
  • Signer sgn Use for the person whose signature appears without a presentation or other statement indicative of provenance. When there is a presentation statement, use Inscriber ins.
  • Singer sng Use for a person who uses his or her voice with or without instrumental accompanyment to produce music. A singer's performance may or may not include actual words.
  • Speaker spk Use for a person who participates in a program (often broadcast) and makes a formalized contribution or presentation generally prepared in advance.
  • Sponsor spn Use for the person or agency that issued a contract or under the auspices of which a work has been written, printed, published, etc.
  • Stereotyper str
  • Supposed name USE Attributed name
  • Surveyor srv Use for a person or organization who does measurements of tracts of land, etc. to determine location, forms, and boundaries.
  • Thesis advisor ths Use for the person under whose supervision a degree candidate develops and presents a thesis, memoire, or text of a dissertation. (UF Promoter)
  • Transcriber trc Use for a person who prepares a handwritten or typewritten copy from original material, including from dictated or orally recorded material. For makers of pen-facsimiles, use Scribe scr.
  • Translator trl Use for a person who renders a text from one language into another, or from an older form of a language into the modern form.
  • Type designer tyd Use for the person who designed the type face used in a particular item. (UF Designer of type)
  • Typesetter USE Compositor
  • Typographer tyg Use for the person primarily responsible for choice and arrangement of type used in an item. If the typographer is also responsible for other aspects of the graphic design of a book (e.g., Book designer bkd), codes for both functions may be needed.
  • Vocalist voc Use for a person who principally exhibits singing skills in a musical or dramatic presentation or entertainment.
  • Wood-engraver wde
  • Writer of accompanying material wam Use for a person who writes significant material which accompanies a sound recording or other audiovisual material.

31. The Bible Technology Group

BTG is a joint effort that has been supported most tangibly by the American Bible Society and the Society for Biblical Literature, as well as by the United Bible Societies, numerous national Bible Societies, the Summer Institute of Linguistics, and othe organizations.

Among the contributors to this work have been:

  • Patrick Durusau, SBL (primary editor)
  • Steve Derose (BTG Chair and co-editor)
  • Kees DeBlois, UBS (BTG Vice-chair)
  • Kirk Lowery, Westminster Hebrew Institute (chair, Linguistic Annotation WG)
  • Troy Griffiths, Crosswire (co-editor)
  • Chris Little, Crosswire (co-editor)
  • Todd Tillinghast, Contentframeworks (co-editor)
  • Adina Hamik, Nida Institute
  • Harry Plantinga, Calvin College/CCEL
  • Mike Perez, American Bible Society
  • Dennis Drescher, SIL
  • Nathan Miles, SIL
  • Robert Hodgson, Nida Institute
  • John Walters, American Bible Society

The work of BTG has also been greatly enhanced by many other members of these and other organizations, who have responded to drafts, made numerous, useful, and sometimes essential recommendations, and encoded texts to test the schemas for usability, consistency, and other virtues. Especially notable among these have been Robin Cover, Jonathan Robie, and Bob Pritchett.

The official Website for BTG is http://www.bibletechnologies.net, and much additional information can be found there.

32. Errata Contributors

Andrew R. Proper, (2)

Andrew was the first person to spot a bug, two in fact. You could be the next person.



Date: (revised 2003:11:15)  Author: (revised pld).
© Bible Technologies Group.




Home - OSIS Information - OSIS Text - About Bible Tech Group -


American Bible Society
ForMinistry free church hosting and Bible study tools provided as a free service of the American Bible Society.
The content of this website is the responsibility of this website's editor and
does not necessarily reflect the views of the American Bible Society.
© 2014







Progress