The OSIS project began as at breakfast meeting organized by Dennis Drescher (SIL) at the XML 2000 meeting in Washington, D.C. Unlike many such meetings about an encoding standard for Bibles and related literature, this one resulted in a coalition thatt produced both the OSIS schema and the following documentation.
There have been meetings, teleconferences, email discussions numbering in the thousands of posts, as each part of the OSIS schema was developed and tested against the needs of those who are interested in using XML in tasks such as publishing, translating and studying the Bible. Work on additional capabilities for OSIS and more documentation is ongoing and newcomers are welcome to the effort. Any volunteers, or comments, corrections, supplied omissions/examples, should be addressed to to osis-editors@bibletechnologieswg.org.
Over the long process to this point, the OSIS project has been supported by the American Bible Society (special thanks to Dr. Eugene Harbecker, and Rev. Trevon Gross), CrossWire.org, SIL, the Society of Biblical Liteature (special thanks to Dr. Kent Harold Richards), and the United Bible Societies. These organizations have contributed staff, resources, organized meetings, paid teleconference bills and supported in other ways the development of OSIS. Suffice it to say that OSIS would not have been possible but for their support.
Organizations played an important role in this effort, but then so did a very large number of individuals. Any listing of individuals will be incomplete but it would be remiss to not name some of the key figures who are responsible for the schema and documentation you see today:
Eric Albright: Eric spent several days at the first OSIS meeting in Rome enlightening the OSIS core group on the choices and decisions made in the creation of XSEM. Eric's insight into the problems faced by translators is profound and was instrumental in shaping core features of the OSIS schema.
Jim Albright: The common last name with Eric Albright is no accident as Jim is Eric's father. Jim has commented extensively on the various drafts of OSIS and saved the reader from both substantive as well as typographical errors on any number of occassions.
Alan Connor: What I would define as a great manager. Rather than look for paperwork or forms, Alan has always looked for solutions. Alan's friendship and assistance in OSIS meetings at SIL have been, are and always will be deeply appreciated.
Peter Constable: Peter has been deeply involved in enabling people to speak with their own voices as part of the Non-Roman Scripts Initiative at SIL for many years. We have valued Peter's advice on character set issues so that OSIS will continue that tradition.
Kees DeBlois: Kees is the long time head of technical development at UBS and OSIS was quite fortunate when Kees agreed to serve as co-chair with Steve DeRose. Kees contributed a much needed "translators" view to the encoding practices found in the OSIS schema.
Dennis Drescher: The source of the idea that became the OSIS schema. He is not to blame for any shortcomings you see in the realization of that idea. Dennis has been a long time supporter of OSIS and a participant in our discussions.
Steve DeRose: Steve agreed to become the co-chair of the Bible Technologies Group (the 'official' activity that lead to OSIS) along with Kees DeBlois in the Spring of 2001. The author of more international standards that can be easily listed, Steve has been both a source of technical work as well as keeping the more excitable members of the core group under control.
John Edwards: John's proof reading of one of the drafts of this manual made me wonder if I had read any of it while I was typing it. If the following manual is readable at all, it is due to the efforts of John and others to filter the output of my keyboard.
Darrell Eppler: Darrell has helped OSIS to be mindful of the need to go from some file on a computer system to something that the average reader would recognize as a Bible. Abstract markup is all well and good, but at some point, some people anyway, want a physical object called a Bible in their hands. To the extent that is possibe, Darrell and Jim Vevries are responsible for that being possible.
Troy Griffitts: Founder of Crosswire.org, one of the largest community projects for developing free Bible software. Troy was one of the early adopters of OSIS and has tirelessly worked on numerous drafts and test conversions of data into proposed OSIS markup.
Adina Hamik: Adina was an early booster for OSIS within the ABS and helped organize OSIS meetings. Her wit and charm helped keep the various organizations and individuals going in a common direction.
Bob Hodgson: Bob has been involved in OSIS since the early days of 2001. He wears so many hats at the ABS that it is difficult to describe which one he had on while supporting OSIS. I think it was the general, support Bible engagement one but I can't say for sure.
Chris Little: Chris is also involved in Crosswire.org (along with Troy Griffitts) and has been a long term participant in OSIS. Chris is one of the calmer members of the core team, a much needed presence more often than you would think. He has contributed to both testing and substantive development of the schema.
Kirk Lowery: Kirk is a Hebrew linguistics expert who has been helping to shape OSIS so that linguistic markup can be added to OSIS texts. Almost there Kirk! I promise!
Nathan Miles: A very good friend and colleague who is charged with no only supporting new formats, such as OSIS, but also supporting old formats as well. A gifted programmer whose suggestions have shaped and refined OSIS.
Harry Plantinga: Harry developed ThML, a language for encoding theological texts but found the time to convert materials into OSIS, to chair OSIS meetings, developed an OSIS editing tool and is now converted ThML texts into OSIS.
Todd Tillinghast: Todd writes the stylesheets that enable OSIS documents to suddenly appear like something that an average user might want to read. Among other things, Todd has created numerous test encodings and other material that has assisted in the development of OSIS.
Jim Vevries: Jim has participated in several OSIS meetings at SIL and along with Darrell Eppler, helped the OSIS team become aware of publication issues. Simply not enough to be elegant, it has to result in printed output as well.
John Walter: If others served in the trenches of writing encoding schemas and documentation, John served an equally important role of advocate for OSIS both within the ABS and to the larger Bible community. It is due in no small part to his efforts that OSIS is now being adopted by the ABS in many of its activities.
There is one name missing from the list of participants and it was not due to oversight. Mike Perez, who is now serving his country on active duty, was the critical person in OSIS moving from a breakfast conversation to the schema and documentation we have today. Mike organized and patiently attended every OSIS meeting and teleconference, while the markup specialists argued about issues too obscure to be repeated here. Mike's focus was always on getting a useable result and hopefully we have not disappointed him too badly with the current schema and users manual.
Claiming author's privilege in a foreword, I would like to publicly thank all of the participants in the OSIS project for their time, efforts and faith that has brought OSIS to this point. In a time when faith often treated with disdain, it has been my privilege to work with men and women of great faith in this project.
Patrick Durusau OSIS Technical Lead Covington, Georgia, October 2004
Welcome to the OSIS (Open Scriptural Information Standard™) User's Manual. OSIS is an XML schema 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 potential publisher;
publishers, who will incur lower costs by not converting texts from authors in a wide variety of formats, and by having texts in a format useable by electronic-book system vendors;
and software vendors, who can avoid writing code to manage different formats, and thus make their programs smaller, faster, and more reliable.
The OSIS development team studied previous Bible encoding proposals, as well as literary encoding in general. We tried to avoid the weaknesses and gain some of the strengths of each one. 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. A list of participants may be found in Appendix *****.
Users familiar with the Text Encoding Initiative (TEI) will find OSIS markup quite familiar. The bulk of the elements we define correspond directly to TEI elements, and often have the same name (often with simplified content models). 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.
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 was 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.
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 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 XML 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 only slightly larger 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 their ease of use varies greatly.
The basic answer is no, you do not need any special software. You can use any text editor you like to create OSIS documents. 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 programs are available for various computers; some are available as Web services. (See 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 schema and an appropriate stylesheet.
An OSIS-aware text editor will do this checking for you, either on demand or continuously. A better OSIS-aware text editor will provide help by showing you just which elements are permitted at any given place. The best 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.
Note on examples: This manual offers a number of examples of OSIS markup. The formatting of those examples (indenting, line breaks, etc.) is for ease of reading only. XML processors don't care if all the elements were run on after the other, although XML encoders would find that difficult to read. Do not spend time trying to make your markup match the indents, line breaks, etc., in this manual.
For future reference: From time to time you will see paragraphs that start: For future reference:. On your first (or even second) reading of this manual you can safely skip those paragraphs. They contain information that you may need later as you become more experienced in using XML or for solving a particular problem.
3. Some authoring tools
The OSIS team is working 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 kind 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 render the OSIS text. An OSIS file can also be rendered to HTML or PDF, for example, by using XSLT stylesheets.
There are also more word-processor-like XML editors, which primarily show a formatted view defined by some style sheet. These are mainly commercial. Commercial editors include: XML Spy (http://www.xmlspy.com/); XMetal (http://www.corel.com), and Serna Editor (http://www.syntext.com). Free editors and other XML tools can be found at Free XML Tools (http://www.garshol.priv.no/download/xmltools/), as well as other XML sites on the WWW.
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/). A free XSL-FO processor, FOP (Formatting Objects Processor) is available from the Apache Foundation, (http://xml.apache.org/fop/. Non-XML-based composition systems such as Quark™ and TeX 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 is followed by the actual text content. The header identifies the file as being XML, and that it uses the OSIS schema. It also provides places to declare a bibliographical description of the text and of any other works cited; and a place to record a history of editing changes. Here is a short, but valid, OSIS document:
BibleBible.en.CEV.1995Copyright 1995 American Bible SocietyEsth.1.1-Esth.1.4BibleBibleBible
King Xerxes of Persia lived in his capital city of Susa and ruled one hundred twenty-seven provinces from India to Ethiopia.
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.
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.
5. XML and OSIS declarations
The first line above identifies the document as being XML and its encoding declaration, in this case UTF-8. The encoding declaration tells the parser (part of the software that reads the file) what character set has been used with this document. Other encoding declarations are possible but this will be the most common one.
The second through third lines are a very long start-tag for the outermost OSIS element, which is called . 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 :
OSIS Namespace, Method 2: Copy the following lines just after :
Note with the second method, the last closing element must be: . The first method is simpler but both are legitimate.
For future reference: The first method declares that the OSIS namespace is the default namespace. The second allows use of the OSIS namespace only if you have the prefix "osis" before the element where the namespace will be used. Namespaces are inherited from their parent elements so there is no practical impact on how you would author an OSIS document.
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:
The osisText element does have more attributes than are shown here but these are the most important ones for a basic OSIS document.
Every osisText element is required to supply an osisIDWork attribute and value. The value will 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 text, described later.
Every osisText also needs to specify what reference or versification system any osisRefs within it use. In the case of the Contemporary English Version, that would be the NRSV (New Revised Standard Version). The following is a list of names for reference systems to be used in OSIS documents:
AV Authorized Version (same as KJV)
KJV King James Version (same as AV)
Loeb Classical literature
LXX Septuagint
MT Masoretic Text
NA27 Nestle-Aland, 27th Edition of the Greek New Testament
NRSVA New Revised Standard Version with Apocrypha
SamPent Samaritan Pentateuch
Synodal Russian
Vugl Vulgate
The xml:lang attribute is required on all osisText elements. While the language element in osisWork allows a wide range of language classification systems to be documented, be aware that xml:lang is much more restrictive. The xml:lang attribute will only recognize ISO 639-1 two letter codes and those from IANA. To use anything else with this attribute, you must first prepend a "x-" to the value.
The canonical attribute is available on all elements. It has a ‘default’ value so it does not have to be entered by the encoder if the default value is acceptable. Here it is shown with its default value of true on osisText so the reader can see it in operation.
When canonical="true", it means that the content of that element 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. Therefore, the default value for elements such as note is false, as the content of that element has been added by an editor or author to the text being encoded. It should be explicitly noted that the value of the canonical attribute should not be used to reflect theological judgment about the content of a text, but merely to distinguish between what has been added to the text and what has not.
In most cases use of the canonical attribute is straightforward, and 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.
6. The OSIS text header
The first element following osisText is required to be header. The header contains the revisionDesc, work, and workPrefix elements for a particular work. These elements must entered in that order, although each may occur an unlimited number of times.
In other words, an OSIS text header may have:
a date
description of revision
a date
description of revision
...more elements... elements for workelements for work
...more elements attributes only, an empty elementattributes only, an empty element
...more
An OSIS text header may NOT have:
a date
description of revision
elements for worka date
description of revision
attributes only, an empty elementelements for work
...more elements attributes only, an empty element
In other words, the order always is:
elements (any number of them), followed by:
elements (any number of them), followed by:
elements (any number of them.
6.1. revisionDesc
To record changes or edits to the text, authors and editors are encouraged to insert a revisionDesc element every time significant editing is done. Each revisionDesc 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 revisionDesc element.
Recommended practice is that more recent revisionDesc elements appear earlier in the document. That is, entries should occur in reverse chronological order. For example:
2003.09.11
sjd: Filling in the gaps. Adding some info for 2.0 as defined at the Calvin College meetings.
2003.07.01
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.
2003.06.17
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.
6.2. work
A work element 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 in the header with an osisWork attribute that matches the osisIDWork in the osisText element identifies the work in which it occurs -- much like the title page in a printed work. For example:
Note that the match between osisIDWork="CEV" in osisText and osisWork="CEV" in the work element links this osisText to this particular work element.
Other work elements (ones that follow the first one) identify other works -- much like a citation in a footnote or bibliography in a printed work. Each assigns a local name to that work, using the osisWork attribute. Works so declared can then be referred to in 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 above). No periods, hyphens, spaces, or colons are allowed in short names.
6.3. osisWork
The osisWork attribute of each work element provides a short name used to refer that work and its declaration as a whole. As of version 2.1, OSIS specifies the recommended format described below for those short names. Also, when using this format within the Dublin Core identifier element, the type attribute must be set to "OSIS".
6.4. Work Prefix Defaults
Each work defined in the header is required to provide a short name for itself in the osisWork attribute. These can then be used as prefixes (similar to XML namespace prefixes) on osisID, osisRef, and other attributes throughout the rest of the document.
In OSIS versions through 2.0, specific attributes were provided to set a default work prefix for osisIDs (osisIDWork on the osisText element) and for osisRefs (osisRefWork on the osisText element). These attributes remain available in OSIS 2.1, but a more general defaulting mechanism has been added.
From OSIS 2.1 on, a defaults element is allowed at the end of the header, after all the work elements. It contains any number of workPrefix elements, each of which sets the default work prefix for a particular attribute on a particular element type. For example:
This declaration indicates that the default work prefix on all annotateRef attributes of note elements is to be "Bible.KJV". No colon is to be included (the colon is used to separate a work prefix from the rest of a reference when the work prefix is explicit rather than defaulted).
The syntax of the path attribute is taken directly from the W3C XPath Recommendation, and can be correctly interpreted by any conforming XPath processor. However, the form shown above is the only form permitted at this time; more complex XPaths are not permitted. In other words, the path attribute must consist of "//", an element type name, "/@", and an attribute name. If a more detailed defaulting mechanism is required in the future, it will likely be provided by permitting a wider range of XPath's features.
A particularly useful application of this defaulting mechanism, is for the morph and lemma attributes of the w element (which provides for word-level linguistic annotation). Because the w element is so frequent when used, defaulting the prefix (which points to a work defining the morphological of lexical system used) can save a lot of space.
7. work
7.1. Introduction
The work element is introduced with two short examples and then each of the elements that may occur in the work element are treated separately. Note that the elements in the work element are split into two sections, those that also occur in Dublin Core metadata and ones specific to OSIS.
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 elements in work may be repeated as necessary, but must be encoded in the order shown here. For example:
Alan GardinerFrancis Llewellyn Griffith19272003GrammarGriffith Institute, Ashmolean Museum, OxfordENEG-ancient090041635195230980
Clarence Jordan19692003BibleAssociation Press New York, NYEN080961725069-18840
7.2. Dublin Core Elements
7.2.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.2.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 along with the complete set appears in the appendices under USMARC Relator Codes.
7.2.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.
7.2.4. date
Date elements in the work element record significant dates in the production or publication process. Use the event attribute to identify the particular date contained in each date element. The defined events 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 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.
For example:
17492003-12-30
For processing purposes, OSIS compliant software will assume Gregorian dates unless the type attribute indicates otherwise. See "Date Formats" for further details on the encoding of date information.
7.2.5. publisher
The publisher element in the work element is used to identify 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 should be used. For cases where full identification of a publication history is essential, use of multiple work elements is suggested.
7.2.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 code. 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.2.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, ).
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 occur on any OSIS element, to distinguish relevant subdivisions of the type).
7.2.8. identifier
The identifier element provides one formal identifier 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 Dewey and you will get an error message.
A work, represented by a work element, can have more than one identifier element. That is to say it may have different identifiers in different identification systems. For example, a book could have recorded in its work element, as having two identifier elements, one for its ISBN, 0-310-92955-5, and one for its Library of Congress Control Number, 2002107776.
DEWEY Dewey Decimal System
DOI Digital Object Identifier
ISBN International Standard Book Number
ISSN International Standard Serial Number
LCCN Library of Congress Control Number (also known as "Library of Congress Card 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 element 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:
080961725069-18840
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.2.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.2.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.2.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.2.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.2.13. rights
Information about rights held in and over the resource.
Typically, the rights element 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 content of 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.2.14. subject
A topic of the content of the resource.
Typically, the subject will contain 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.2.14.1. subject classification systems
The type attribute on subject allows the user to specify the classification system the subject entered can be found.
Fathers of the Church
The above 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 has been prepared by the OSIS project. Those systems with their abbreviations for use with an OSIS encoded text are as follows:
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.2.14.2. source
A reference to a resource from which the present resource is derived.
The present resource may be derived from the resource identified by the source element 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.2.14.3. type
The nature or genre of the content of the resource.
The type element contains 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. Non-Dublin Core Elements and Attributes in the Work Declaration
7.3.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.3.2. castList
The castList element is just one of many places where OSIS reveals its reliance on prior Bible encoding proposals. This particular element was chosen based upon analysis of XSEM.
The castList element is composed of any number of castGroup elements.
7.3.2.1. castGroup
The castGroup element provides an easy way to consolidate information about the characters in a dramatic text for later reference in the encoding of that text. The castGroup element is composed of actor, role, and roleDesc elements. See the material under Dramatic Texts for details and examples on using the castList and related elements.
7.3.2.2. teiHeader
The content of a teiHeader element is not processed as part of the OSIS schema. It is provided for cases where a TEI header file or portion of a text needs to accompany a text that is now being encoded in OSIS markup.
7.3.2.3. refSystem
Since versification systems differ between Bible translations (the original texts had no versification at all), it is important to note here which versification system is being followed for a particular edition of the Bible that is being encoded. Works of classical authors as well may have differing reference systems.
The value here should be the the osisWork attribute value from a work declared in a work element in the header of the document.
7.4. Elements allowed in elements
The work element contains the following elements, which must appear in this order, although they can each be repeated as many times as necessary:
title
contributor
creator
subject
date
description
publisher
type
format
identifier
source
language
relation
coverage
rights
scope
castList
teiHeader
refSystem
8. 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 three standard date formats; the prefixes that identify them are reserved, and may not be redefined via the osisWork 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 four 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 a retrievable portion of that work. The value should the the applicable time in one of the formats just shown.
Typically, such works are organized in chronological order of the times specified; however, that is a user or publisher requirement and not one imposed by OSIS.
9. 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 header and a 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.1. Elements allowed in the elements
The titlePage element contains the following elements, which may appear in any order, and may be repeated as many times as necessary:
title
contributor
creator
subject
date
description
publisher
type
format
identifier
source
language
relation
coverage
figure
milestone
p
10. The
Element
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 also must commonly be marked.
It is possible to encode a Bible using only book, chapter, and paragraph markup. However, most encoders also want to also represent sections, verses, 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,
1585160555Copyright 1995, 2003 American Bible SocietyBibleBible
Genesis
1In the beginning,...The earth was formless and void...
...
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).
The books of the New Testament would be grouped as follows:
New Testament...
s for individual books here...
Within each div of
type="bookGroup"
, there will typically be book division types corresponding to each included Canonical or deutero-canonical book. The book division type,
>, may contain
> (such as the sub-books in Psalms),
> (typically topical divisions with headings), and
> (occasional minor divisions within sections).A specific chapter element is provided and encouraged, though a
> is also permissible.
Expanding the New Testament example to include the first two Gospels:
New Testament
Matthew
Chapter 1...text of chapter 1...
Mark
Chapter1...text of chapter 1...
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 commonly begins to interact with verse markup.
Use of one of the types defined (provided) for div is mandatory when a provided type is applicable. For example, a colophon must be marked up as
. If a type is needed but not provided, it may be added but must begin with "x-", to distinguish it 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. Given the prevalence of book/chapter/paragraph divisions in modern translations, that is the hierarchy that prevails in all cases of conflict. Most cases of conflict will be with the marking of verses. Some translations do not follow the modern practice of using paragraphs in translation and therefore there is no conflict between verses and paragraphs. So long as verses and chapters do not cross the boundaries of other elements, they may be expressed in as shown in the following example (NASB):
Mark Chapter 10
DivorceJesus 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. Some Pharisees came and tested him by asking, "Is it lawful for a man to divorce his wife?" "What did Moses command you?" he replied. They said, "Moses permitted a man to write a certificate of divorce and send her away." "It was because your hearts were hard that Moses wrote you this law," Jesus replied. "But at the beginning of creation God 'made them male and female.' 'For this reason a man will leave his father and mother and be united to his wife,and the two will become one flesh.' So they are no longer two, but one. Therefore what God has joined together, let man not separate."When they were in the house again, the disciples asked Jesus about this. He answered, "Anyone who divorces his wife and marries another woman commits adultery against her. And if she divorces her husband and marries another man, she commits adultery."
...
The quotes that appear in this example present a special problem as they do cross the boundaries of verses in an edition. Rather than introduce the mechanism for such cases here, the traditional quotation marks are used in this example. See the section Elements that cross other elements for details on dealing with such quotations.
In cases where the translation follows the modern practice of using paragraphs in the translation that cross verse boundaries, it is necessary that all verses be marked using the techniques described in Elements that cross other elements. That may seem like a burden but in order to have easy processing for a text, it is necessary that all similar parts of it be marked in the same way. As work on OSIS and other XML editors continue, it will become easier concentrate on the substance of the text and allow automatic mechanisms to deal with the technical niceties of the underlying markup. Until then, however, you will need to compenstate for the weaknesses of XML processors so that your Bible text can be easily produced for the WWW, print, cellphones and other devices.
10.1. Elements that may occur in
elements
The div element allows the following elements to occur within it:
• a • abbr • chapter • closer • date • div • divineName • figure • foreign • hi • index • inscription • lb • lg • list • mentioned • milestone • milestoneEnd (depracated, don't use) • milestoneStart (depracated, don't use) • name • note • p • q • reference • salute • seg • signed • speaker • speech • table • title • transChange • verse • w
It is a milestoneable element. It also allows for mixed (text and element) content.
11. Paragraphs, 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 have an osisID attribute value for the set of verses it contains, since they are typically provided on the verse elements themselves.
11.1.
The p element is the basic holder of prose in a text. As noted above, the paragraph is used in modern translations in preference to traditional verse division of the text of Bibles. There are cases where paragraphs and verses do not conflict, but there are enough cases where they do that verses should always be represented, for entire Bibles at any rate, using the milestonable version of the verse element. For short passages in another work, for example, where verses do not cross the boundaries of paragraphs, they can be represented as containers, as shown below:
...
Then Esther spoke to Hathach, and gave him a command for Mordecai: 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.So they told Mordecai Esther's words.
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.
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?"
Note that in this example that all the paragraphs and quotations still enclose an exact number of verses. This is the exception rather than the rule. Caution is urged in deciding to follow this example other than for small portions of text that are known to nest properly. (Nest is an example of XML abuse of the English language. Means simply that each element fits within the one above it, in this case, the verse elements "nest" withing the p elements. Next time you are at a church social you can talk about how the elements in your documents "nest" to the wonder and amazement of those listening.
The following are some illustrations of material in a text that you would encode using the
element:
The first gray section would be encoded as follows:
...
This is the good news about Jesus Christ, the Son of God.It began just as God has said in the book written by Isaish the prophet, ....
Note the marking of the milestoneable form of the verse element. The paragraph actually continues to the end of verse 3 but we can anticipate that other verses are going to cross boundaries and so to be consistent and conformant with OSIS, all verses should be marked using the milestoneable form of the element.
Another example of paragraphs.
11.1.1. Elements that may occur in
elements
The p element allows the following elements to occur within it:
a
abbr
catchWord
chapter (only in milestone form)
closer
date
divineName
figure
foreign
hi
index
inscription
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
rdg
rdgGrp
reference
salute
seg
signed
speaker
speech
table
title
transChange
verse
w
It is not a milestoneable element. It allows for mixed (text and element) content.
11.2.
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 providing value for the type attribute of the q element, with values such as initial, medial, and final.
Some translations render quotes differently depending upon the speaker. A good example of that are "red letter" editions that render the words of Jesus in red. Those are all quotations and so should be marked with the q element, so how does it get rendered as red rather than with quotation marks?
The q element has an attribute called who. In cases where it is important to mark who is being quoted in a q element, the encoder puts the speaker's name in the who attribute. For example:
Then Jesus asked them, When I sent you without purse, bag or sandals, did you lack anything?
This is a good illustration of how markup enables different rendering of a text. It is certainly possible to simply render this quote like all others in the text with traditional quotation marks. But, following the traditional rendering is often desired by publishers as well as readers. Not to mention that we all attend to some quotations in the Bible more than others.
Rendering the words of Jesus in red, such as the ones quoted above, is a matter of selecting the words of Jesus and not quotes from others for this rendering. That is the job of an XSLT stylesheet, that is the mechanism that takes your OSIS XML file and renders it to HTML, PDF or other format. A snippet of XSLT (there would be more involved in an actual stylesheet) that would do this rendering, could be written as follows:
Roughly translated (Bible translators aren't the only ones with translation problems, theirs are just more important) this means:
Find all the q elements
Of all the q elements select the ones where who="Jesus"
For each one with who="Jesus" print:
Then print the content of the q element
For each one, print
Used in its proper context, this snippet will render all the words of Jesus in red. Note that you could also use this to extract all the words of Jesus (well, you would also want to capture their verse location but that is another story). Once you have all the words of Jesus marked using the q element, the rendering, extraction, use, etc., of the words so marked are limited only by your imagination and XSLT stylesheet writing skills.
An example of two quotes.
11.2.1. Elements that may occur in elements
The q element allows the following elements to occur within it:
a
abbr
closer
date
divineName
foreign
hi
index
inscription
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
salute
seg
signed
speaker
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
11.3.
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; however, that capability is not provided at this time.
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 meaning 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.
It is worth mentioning that although a note element is physically contained in the OSIS document, at the point where it applies, it is not logically "contained" there. For example, a user who searches for the phrase "undivided devotion" should find it in 1 Corinthians 7.35 of the NIV, even though there is a (cross-reference) note at the end of "undivided", between the words. Software that handles such cases correctly is not commonplace at this time; however, by using explicit XML markup to identify relevant components such as note, such software is made feasible.
The note element can appear in any element that can contain text outside of the header element. When you first start to use the note it may seem strange that the note is located "inline" where you normally see a footnote number or other reference to help you find the note. That is a normal reaction and what is happening when you encode a text, is that you are behind the scenes so to speak, before the text has been rendered. In some cases, you may want the material held in the note elements to be printed at the bottom of a column or page, in other cases you want to gather them up to the end of a chapter (common in some commentaries) or for a Sunday School class, you may want to suppress them altogether. Once your text is in OSIS markup, all of those possibilities and more are open to you.
The following is a fairly complex example of different types of notes in a text. The encoded text is from the Contemporary English Version, the Book of Esther, chapter 1, verses 1 and 2. Don't Panic! This example is explained line by line below.
Ezra 4:6
King Xerxes
XerxesThe Hebrew text has Ahasuerus, who was better known as King Xerxes I (485-465 B.C.).
of Persia lived in his capital city of Susa
in his capital city of SusaOr in his royal fortress in the city of Susa. Susa was a city east of Babylon and a winter home for Persian kings.
and ruled one hundred twenty-seven provinces from India to Ethiopia.
EthiopiaThe Hebrew text has Cush, which was a region south of Egypt that included parts of the present countries of Ethiopia and Sudan.
Now for the explanation:
This line starts the first verse of the first chapter of the Book of Esther. Note that it uses the milestoneable version of the verse element. As such, it has the sID attribute with the value of "Esth.1.1-Esth.1.2" to match the eID attribute you see on line 11.
It also has an osisID attribute that indicates this verse contains both "Esth.1.1" and "Esth.1.2." There is only one osisID attribute but the verses identified by it are both listed, separately. You cannot have a range, like, Esth.1.1-2 for an osisID. Ranges are permitted for osisRef artributes, which we will meet on the next line.
The final attribute you see is the n attribute. This is most commonly used to record some numbering that was present in an original text that may or may not have any relationship to the structure being encoded. In other words, the CEV translations inserted "1-2" here and OSIS provides a mechanism to record the fact of "1-2" occuring here.
The second line of the encoding has not (yet) reached the text of Esther. The translators have inserted a note to direct the reader to other material. This is marked using the note element with several attributes. First, there is the type attribute that records this note is a cross reference to another text, using the type of crossReference. (Recall our earlier discussion about XML being case sensitive? Well, "cross reference," "crossreference" and "CrossReference" will all cause errors if used. Use "crossReference" only. It is written in "camel case," that is the first letter of the first word is in lower case and the beginning of each following word (no spaces) is in upper case. Another tidbit for the church picnic.)
The next thing to notice is that the note has an osisRef attribute and value. The value Esth.1.1-Esth.1.2 means that this note is pointing at the material in this text that has the osisID of Esth.1.1-Esth.1.2. In practice this means that no matter where I put these notes, physically speaking, they are always "pointing" at this particular place in the text.
The third thing to notice is that the note has an osisID attribute and value. The note element is not required to have an osisID but it can be useful.
This line starts inside the note element itself, that is, the content of the note as it appeared in the original text. In a printed text, one would see Ezra 4:6, but the OSIS markup provides greater abilities from the same information. The reference element, that is inside the note, has an osisRef attribute. That attribute points at Ezra 4:6, but written as Ezra.4.6. The reason for that pointing is to allow applications to present the reader with a hypertext link to that text or even display it automatically (if the user so chooses) along with the main text. Note that the traditional rendering of the Ezra citation is also preserved for the reader.
Finally, the first word in the text! Does look like a lot to get this far, but recall that the encoding compensates for how dumb computers are as compared to a human reader. The advantages for publishing, distribution and study are well known, so lets see if we can get to the end of the first two verses!
Arrgh! Another note! Well, any well translated Bible is going to have lots of notes so we start with an example that has four of them.
The second note element is different from the first one. Can you see how? This note element has a different type attribute, that of translation. Translation notes usually indicate additional information for the reader to consider in evaluating the translation.
Inside this note element, we encounter the catchWord element. The catchWord element contains text that occurs in the main text and works like a pointer for a human reader as to which word or phrase the note applies to in the text. In this case, the note is concerned with the name, "Xerces," which we just encountered as the first word in the text. The note goes on to inform the reader that the Hebrew text differs from that which appears in the translation, along with an explanation for that difference.
This note element also contains a q element that has quoted material that appears in the note. The q element has a level attribute that is used to indicate the type of quotation marks that should appear in rendering this particular quote. Think of it as being an indication of where you have a quote that is inside another quote. Normally the outside quote has double quotation marks, while the inner quote has only single quotation marks. The level attribute is used to preserve that sort of rendering information, when automatic rendering is not used.
Well! Another line of text!
The third note element to appear for this passage. It has all the same attributes as those covered at line 5, so that discussion is not repeated here.
The content of the third note is similar to that covered at line 6. Note that the content of catchWord can be an entire phrase.
The last line of text that we will encounter here.
The fourth (and final) note element in this passage. See lines 5 and 6 for the meaning of the various parts.
The milestoneable verse element that marks the end of this passage. Note that the eID value matches that found at line 1.
That may seem like a lot of markup but look at the explanation again. Note how as we moved through the markup, the less and less explanation was needed? That is because once you master some basic elements and concepts of markup, you can combine those to make a richly encoded text that will serve many purposes.
11.4. Summary
As you can see, fairly complex markup can be based on just a handful of elements. Except for the verse elements in the last example, all of the elements were traditional containers. That is to say, an element opens, contains text and perhaps other elements, then closes, fully surrounding all the text and elements inside. But, that is not always the case, particularly in Bible translations.
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.4.1. Examples of Notes
11.4.1.1. Alternative Readings
An alternative reading in a note.
Another alternative reading in a note.
11.4.1.2. Notes with
The bold text is encoded with the element to show that it appears in the main text. Only the first and last word of the phrase are shown.
The bold text here is also encoded with a element. The following for today, for tomorrow should be encoded with the element.
11.4.1.3. Note Markers
The grayed area is a marker that appears in the text. Note this is not encoded as part of the note.
Another example of a note marker. Note markers are produced by the stylesheet that is used with an OSIS document. This allows large print markers for visually impaired users or other forms of presentation.
11.4.1.4. Notes with References
This note contains references that are encoded using the element.
Another example where elements should be used.
11.4.1.5. Notes with Verses
A fairly complex note, which has a
element, which contains a element. Note that the content of the element itself does not use the
element.
11.4.2. Elements that may occur in elements
The note element allows the following elements to occur within it:
a
abbr
catchWord
date
divineName
figure
foreign
hi
index
inscription
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
rdg
rdgGrp
reference
seg
table
title
verse
w
It is not a milestoneable element. It does allows for mixed (text and element) content.
12. Elements that cross other elements
The normal form of an element is a start tag and an end tag: .... 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 "" rather than or . 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 appear as follows:
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. 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.
Hegai was put in charge of all the women, 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.
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.
13. 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.
13.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:
13.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):
The First Epistle to TimothyFROM: 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.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....
...
13.1.1.1. Elements that may occur in elements
The salute element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
salute
seg
speaker
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.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:
I Tertius salute you which wrote this epistle in the Lorde.
[English, Tyndale, 1525/1530]
I, Paul, write this greeting with my own hand.
[English, RSV]
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:
[English, Webster]
See with what large letters I am writing to you with my own hand.
[English, RSV]
Paul, an apostle of Christ Jesus through the will of God, to the saints that are at Ephesus, and the faithful in Christ Jesus:
[English, American Standard Version, 1901]
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.
[English, RKJNT]
Paul, an apostle of Jesus Christ, according to the commandment of God our Savior, and of Christ Jesus our hope:
[English, Douay-Rheims Bible, Challoner Revision]
Mimi Paulo, mfungwa kwa ajili ya Kristo Yesu, na ndugu Timotheo, ninakuandikia wewe Filemoni mpendwa, mfanyakazi mwenzetuna kanisa linalokutana nyumbani kwako, na wewe dada Afia, na askari mwenzetu Arkupo.
[Swahili NT]
13.1.2.1. Elements that may occur in elements
The signed element allows the following elements to occur within it:
a
abbr
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
reference
seg
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.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:
Dear children, keep away from anything that might take God's place in your hearts. Amen. Sincerely, John
[LBP]
13.1.3.1. Elements that may occur in elements
The closer element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
seg
signed
speaker
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.1.4. Benedictions
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 . For example:
The grace of the Lord Jesus Christ, and the love of God, and the communion of the Holy Spirit, be with you all. Amen.
OSIS provides two main features for marking up dramatic texts such as plays. The first main feature for drama is a way to declare the list of characters, or castList; the second is a way to identify speeches and their 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. A similar approach might be taken 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 element is shown below, perhaps for a dramatic re-enactment of Job:
Cast of charactersPatrick DurusauJobA man of God who suffers greatly(a whirlwind)GodThe Almighty, who permits Job's suffering, and responds to his questions about it.(a disembodied voice)SatanThe instigator of Job's sufferingTodd TillinghastEliphazThe first of Job's friends to speakChris LittleBildadThe second of Job's friends to speakSteve DeRoseZopharThe third of Job's friends to speakTroy GriffithsElihuThe youngest and last of Job's friends to speak, who was slightly less clueless than the rest.
The castList element contains the entire casting list, and consists of one or more castGroup elements. Multiple castGroup elements, 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 cast of Song of Songs and that 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 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 should 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".
13.2.1. Elements that may occur in elements
The castList element allows the following elements to occur within it:
castGroup
It is not a milestoneable element. It only has the castGroup element as its content.
13.2.2. Elements that may occur in elements
The castGroup element allows the following elements to occur within it:
actor
role
roleDesc
It is not a milestoneable element. It only allows actor, role, and roleDesc elements as its content.
13.2.3. Elements that may occur in elements
The actor element allows the following elements to occur within it:
a
abbr
foreign
index
note
reference
seg
w
It is not a milestoneable element. It only allows the listed elements as its content.
13.2.4. Elements that may occur in elements
The role element allows the following elements to occur within it:
a
abbr
foreign
index
note
reference
seg
w
It is not a milestoneable element. It only allows the listed elements as its content.
13.2.5. Elements that may occur in elements
The roleDesc element allows the following elements to occur within it:
a
abbr
foreign
index
note
reference
seg
w
It is not a milestoneable element. It only allows the listed elements as its content.
13.3. speaker
The speaker element is used to identify the person or role that is uttering the content of an associated speech. A formal pointer should be included, connecting the speaker element to a castItem in the header. For example:
womanI am a rose of Sharon, a lily of the valleys.
Which is the equivalent to:
I am a rose of Sharon, a lily of the valleys.
Either method is correct, but a given text should be consistent in using one method or the other. It is not required that the who attribute be provided, or that it have a prefix tieing it to a castList; however, this is the recommended best practice because it enables computer software to assist with error-checking.
The defaults element added in OSIS 2.1 may be used to specify the default prefix for the who attribute on speech, by specifying path='//speech/@who'.
13.3.1. Elements that may occur in elements
The speaker element allows the following elements to occur within it:
a
abbr
divineName
foreign
index
name
note
reference
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
13.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:
Stephen's Speech to the SanhedrinThen the high priest asked him, Are these charges true?To this he replied: 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. 'Leave your country and your people,' God said, 'and go to the land I will show you.'"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. 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. 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. 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.'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.
...
you who have received the law that was put into effect through angels but have not obeyed it.
...
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 represented with milestoneable verse elements. The reason for this is quite simple, if the encoding jumps from using containers for verses and only on occasion 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 of them is represented via milestones.
13.4.1. Elements that may occur in elements
The speech element allows the following elements to occur within it:
a
abbr
chapter
closer
date
divineName
foreign
hi
index
inscription
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
salute
seg
signed
speaker
table
title
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.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, as in 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.
These three elements for marking up poetic material work as follows:
13.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; these may be distinguished via the type attribute. No pre-defined types are provided; any types used should begin with "x-" so as not to conflict with standard values that may be agreed upon later and added to OSIS.
Line groups can contain smaller line groups as well.
13.5.1.1. Elements that may occur in elements
The lg element allows the following elements to occur within it:
chapter
index
l
lb
lg
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
q
verse
It is a milestoneable element. In its container form, it allows only for element content.
13.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 poetry 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.
You, LORD God,are my protector.Rescue me and keep me safefrom all who chase me.Or else they will rip me apartlike lionsattacking a victim,and no one will save me.
A particular use of the l element is for marking the Hebrew term "Selah" which occurs in many Psalms. "Selah" (however it is translated or transliterated) should be marked up like this:
Selah
13.5.2.1. Elements that may occur in elements
The l element allows the following elements to occur within it:
a
abbr
chapter
date
divineName
foreign
hi
index
lb
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
speaker
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.5.3. lb
The lb element, or "line break", is an empty element 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 line might be broken to fit into a narrow column.
The lb element is also used to mark where line 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 the lb element. 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.
With the addition of the editions global attribute, it is also an option to define separate narrow and wide editions, and mark the preferred line breaks for each, indicating their applicability using the editions attribute.
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 important, but must be marked up using the milestone element instead.
The lb element marks a point in the text and so have no content, either in the way of text or elements. It does have the attribute values described above but those are not considered to be element content.
13.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 dictionary 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.
13.6.1. list
All types of lists are marked using the list element; they can be distinguished by type attribute values such as "ordered", "unordered", "compact", and "definition." A list consists of any number of item elements, preceded by optional label elements, which corresponded to the definition-terms of definition lists in various schemas.
The list element in OSIS is a good deal broader in application than the similar element found in TEI. It functions to organize any number of item elements but can also serve as a list of other containers.
13.6.1.1. Elements that may occur in elements
Elements that can occur in list are as follows:
chapter (only in milestoneable form)
head: use to provide a heading for list
index
item
lb
list: A list can hold another list
milestone
milestoneEnd (depracated, do not use)
milestoneStart (depracated, do not use)
q
verse
13.6.2. label
A leading label for a given listitem. Label elements are optional. Encoders are cautioned, however, to be consistent in their use of Label elements as incosistent usage may lead to unexpected results when formatting a text for print or display.
13.6.2.1. Elements that may occur in
The label element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
transChange
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.6.3. item
The main content or description for each list item.
A list element can be used for outlines that sometimes preceed or follow a biblical passage, such as:
Outline The Feasts of Xerxes (1:1-2.18) Vashti Deposed (ch. 1) Esther Made Queen (2:1-18)
A more intuiative way to encode the same list would be:
Outline The Feasts of Xerxes (1:1-2.18) Vashti Deposed (ch. 1) Esther Made Queen (2:1-18)
In the second example, the second list element is wholly contained within a item element. This corresponds to the normal TEI practice. The odds are against you ever needing any of the other elements allowed by list other than item but they are there should the need arise.
13.6.3.1. Elements that may occur in elements
The item element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lg
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
title
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
13.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.
You can specify how many rows and columns there are with the attributes rows and cols, but this is optional. In the head element you can give the table a title or small description.
Demonstration ............
A detailed example is given under cell below.
Note again: OSIS provides no attributes or elements to layout the table, rows and cells, like "width", "cellspacing" or "align" in (X)HTML. All this has to be done by the rendering software or the browser. Here is an example out of an XSL-file for XHTML output:
13.6.5. row
The row element binds together a number of cells for a line. The use is similar to the (X)HTML element .
13.6.6. cell
Due to the fact that table cells in printed publications can contain nearly anything, nearly anything is allowed in OSIS cells even verses and other tables. For example:
Settlement of the three patriarchs The group ofsettled nearbybelonged to the tribe ofAbrahamMamre
nearby
Hebron
(eg. Gen 18, Gen 13:18 or Gen 14:13. And more in the south: Gen 12:9 or Gen 13:1) Caleb ( Num 13) and later: Judah). IsaacBeersheba
(Gen 26:23-33 ) and Beerlahairoi
in the South (Gen 24:62 ) Simeon
in the South and
Joseph
in the North
JacobPeni'el-Mahanaim-Succoth, Sichem
and BethelReuben, later Ephraim-Manasseh
This example shows the use of table, row and cell. You see that in a cell you are free to use other elements from the OSIS scheme. Here esp. name and reference.
13.6.7. figure
The figure element is used to insert graphic non-textual materials, in other words, maps, pictures, drawings into an encoded text.
An example of a figure in an OSIS text might be:
Christ and the Woman Taken in Adultery by Max Beckmann, 1917
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.
Another example for figure showing the use of the osisRef attribute.
The Agony in the Garden by Gustave Dore, 1855 DORE, Gustave, grafic artist, painter and sculptor, born 1/6/1832 in Strasburg, died 1/23/1883 in Paris. - For over 90 books of world literature he has created woodcutten illustrations and is especially known for his illustraions of the bible. This work here is an example for his extraordinary talent.
13.6.7.1. Elements that may occur in elements
caption
index
note
13.6.8. caption
The caption element is used with figure to provide the caption shown with a map, illustration or image.
13.6.8.1. Elements that may occur in elements
The caption element allows the following elements to occur inside it:
a
abbr
divineName
foreign
hi
index
lb
milestone
name
note
q
reference
seg
w
14. milestone
The milestone element is an empty element, and so is represented as 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:
The Lord said to Eliphaz:
What my servant Job has said about me is true,
but I am angry with you and your two friends for
not telling the truth. So I want you to go over to
Job and offer seven bulls and seven goats on an
alter as a sacrifice to please me. After this, Job
will pray, and I will agree not to punush you for your foolishness.Eliphaz, Bildad, and Zophar obeyed the Lord, and he answered Job's prayer.
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 the attribute n on a milestone, it should indicate the number of the unit starting, not the unit ending. For example, 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 simply 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
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.
15. Common elements in all texts
The elements found in this section can be found in almost any encoded text.
15.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:
See Edwards' famous treatise on religious affections for additional information.
a element allows a mixture of text and the following elements to occur within it:
index
15.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:
On 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:
No separate "see also" type is provided at this time.
The index element represents a point in the text and therefore does not allow any content, either text or elements. For that same reason, it is not milestoneable.
15.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:
A reference element was used in the note example above. To refresh your memory, here is just the reference element part of that example:
Ezra 4:6
Note that since there is no osisWork prefix (there is no "name:" in front of Ezra.4.6 in the osisRef attribute, it is conclusively presumed that this reference can be found in this text. If you want to point to another text, you must declare that in by a work element and use the value of the osisWork attribute from it to make references to it. For example, let's assume that the text has a work element declared for David Clines commentary on Job. It has an osisWork attribute value of "dclines_job." Here is how to use that value to make a reference to that work:
Clines, , at p. 28
15.3.1. Elements that may occur in elements
reference element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
seg
title
w
15.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:
JBL
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 choose to display the expansion instead of the abbreviation or to display it upon request by the reader.
15.4.1. Abbreviation Examples
The highlighted text, in this case, BC is an abbreviation for Before Christ. That may seem too 'well known' to encode, but how many readers would recognize BWL? (hint, usually cited in studies on Job) In all the most common cases, abbreviations should be marked and the expansions included.
The highlighted text, in this case, NIV, KJV, and, NLT are abbreviations for New Internaltional Version, King James Version, and New Living Translation, respectively.
15.4.2. Elements allowed in
abbr element allows the following elements to occur within it:
a
divineName
foreign
index
name
note
reference
w
It is a milestoneable element. It also allows for mixed (text and element) content.
15.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:
When she saw that she was thwarted, that her hope was lost, she took another of her cubs and made him a young lion.It is uncertain to which king another of her cubs refers....
15.5.1. catchWord Examples
The bold text is encoded with the element to show that it appears in the main text. Only the first and last word of the phrase are shown.
The bold text here is also encoded with a element. The following for today, for tomorrow should be encoded with the element.
15.5.2. Elements allowed in
catchWord element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
inscription
lb
list
mentioned
milestone
milestoneEnd (depracated don't use)
milestoneStart (depracated don't use)
name
note
q
reference
seg
speaker
title
transChange
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
15.6. divineName
divineName is only for the Deity. Angels, demons, idols, and the like should be tagged with For example:
El Shaddai
15.6.1. divineName Examples
The divine name is rendered differently in some translations when the Tetragrammaton is encountered as opposed to Adonai.
Another example of the divine name.
15.6.2. Elements allowed in
divineName element allows the following elements to occur within it:
a
abbr
foreign
index
note
reference
seg
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
15.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:
He took her by the hand and said to her: Talitha cum, which means, Little girl, get up!
15.7.1. foreign Examples
An example of a foreign phrase that is retained in a translation. Note that the foreign phrase is contained in a quotation so both and elements would be used to mark this phrase.
Another example of a foreign phrase.
15.7.2. Elements that may occur in elements
foreign element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
name
note
reference
seg
title
w
It is a milestoneable element. It also allows for mixed (text and element) content.
15.8. hi
The hi element provides a simple text highlighting mechanism. If the reason why a particular portion of text is highligted in a text, such as marking a foreign word, a header, etc., then a more specific OSIS element must be used. In the two cases cited, a foreign word would be encoded with the foreign element and a header would be encoded with the head element. The more specific marking of words in a text allows for better searching and rendition of the text than simply highlighting the text. The hi element is reserved for cases where the purpose of the highlighting or other typographic distinction is unknown.
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.
the child with his mother Mary
15.8.1. hi Examples
15.8.2. Elements that may occur in elements
hi element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
reference
seg
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
15.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.
W:R74W.XA
Don't worry if you don't recognize the word or its notation. This was taken from the MORPH database produced by the Westminster Hebrew Institute.
15.9.1. Elements that may occur in elements
seg element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
transChange
w
It is a milestoneable element. It also allows for mixed (text and element) content.
15.10. inscription
inscriptions should not also be tagged as quotations. For example, where Paul refers to an alter inscription in Athens (NIV):
For as I walked around and looked carefully at your objects of worship, I even found an altar with this inscription:| To an unknown god
But you his son, O Belshazzar, have not humbled yourself, though you knew all this.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.Therefore he sent the hand that wrote the inscription.
This is the inscription that was written: Mene, Mene, Tekel, Parsin
Note the use of an empty tag to represent the start of Daniel's quotation, which ends at the end of verse 28 (where 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.
15.10.1. Elements that may occur in elements
inscription element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
speaker
speech
transChange
w
It is not a milestoneable element. It allows for mixed (text and element) content.
15.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:
He brought Simon to Jesus, who looked at him and said, Your are Simon son of John. You are to be called Cephas (which is translated Peter).
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.
15.11.1. Elements that may occur in elements
mentioned element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
transChange
w
It is not a milestoneable element. It allows for mixed (text and element) content.
15.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
There once was a man in the land of Uz whose name was Job. That man was blameless and upright, one who feared God and turned away from evil.
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.
15.12.1. Elements that may occur in elements
name element allows the following elements to occur within it:
a
abbr
foreign
index
note
reference
seg
w
It is not a milestoneable element. It allows for mixed (text and element) content.
15.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."
Then Peter remembered the word Jesus has spoken to him: Before the rooster crows twice you will disown me three times. And he broke down and wept.
15.13.1. Elements that may occur in elements
q element allows the following elements to occur within it:
a
abbr
closer
date
divineName
foreign
hi
index
inscription
lb
lg
list
mentioned
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
salute
seg
signed
speaker
transChange
verse
w
It is a milestoneable element. It also allows for mixed (text and element) content.
15.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:
I am a roseHeb crocus of Sharon, a lily of the valleys.
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.
15.14.1. Elements that may occur in elements
rdg element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
lg
list
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
p
q
reference
seg
transChange
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
15.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 Amplified 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)
15.15.1. Elements that may occur in elements
transChange element allows the following elements to occur within it:
a
abbr
date
divineName
foreign
hi
index
lb
milestone
milestoneEnd (depracated, don't use)
milestoneStart (depracated, don't use)
name
note
q
reference
seg
w
It is not a milestoneable element. It does allow for mixed (text and element) content.
15.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 comments 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 transliteration of a word.
(examples forthcoming)
15.16.1. Elements that may occur in elements
word element allows the following elements to occur within it:
a
index
note
seg
It is not a milestoneable element. It does allow for mixed (text and element) content.
A canonical reference scheme is a system of agreed names and/or numbers 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, >....
To identify a reference into a Biblical or other passage, that is not contained at the point of reference. For example, "
The correctness of my exegesis is incontrovertibly proven by the first verse of Matthew.
"
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.
16.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.
16.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).
16.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.
16.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:
...
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.
16.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.
16.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):
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.
17. OSIS references
An osisRef is very much like an osisID. The fundamental difference is that while an osisIDidentifies 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:
The same interpretive method applies also in the first verse of Luke.
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 osisRefs, 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:
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:
See also John 3:14-16, 18; 4:1-2; 4:1-2; .
It is permissible for osisRef values, including those on either side of a hyphen in a range reference, to use osisID values that include the work-specific extension fields ("!" followed by a name, e.g. osisRef="!steve-!todd")).
17.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).
18. 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.
Appendix A 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
Appendix B Alphabetical list of Attributes and normative values
Appendix B.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 broad 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.
Appendix B.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.
Appendix B.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 meditation 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 study guide on the reference given by the annotateRef attribute.
translation A translation of the reference given by the annotateRef attribute.
Appendix B.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
Appendix B.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.
Appendix B.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
Appendix B.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
Appendix B.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.
Appendix B.2.6.1 type attribute on
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).
Appendix B.2.6.2 use attribute on
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 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.
Appendix B.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.
Appendix B.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.
Appendix B.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.
Appendix B.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.
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
Appendix B.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 titles 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.
Appendix C 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.
Appendix C.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.
Appendix D 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.
Appendix D.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 Stuttgartensia
NA Nestle-Aland Greek New Testament (may suffix edition number, such as "NA27")
LXX Greek Septuagint
Appendix D.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
Appendix D.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
Appendix E USMARC Relator Codes
For ease of use a selected set of USMARC Relator Codes have been extracted from the larger complete list of such codes. This short listing, which should be sufficient for basic encoding needs, is followed by the complete list of USMARC Relator Codes. Both listings are based upon: MARC Code List: Relator Codes -- Term Sequence (http://lcweb.loc.gov/marc/relators/re0002r1.html).
Appendix E.1 Selected Contributor Roles
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 responsible for 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.
Appendix E.2 Complete 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 or 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, or 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 or 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 of 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.
Appendix F Identifying a Work given a work declaration element
The elements title, creator, publisher, date, identifier, and date, are the primary means of identifying a referenced work.
If a publication matches all of the above elements within a work element, 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), and publishers may change the name of the work, 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.
Appendix G Special Case: Two References Systems
It is unlikely that most encoders will ever encounter a text with two references systems, much less ones that do not start and end at the same points. Unless you are facing that situation or just like difficult explanations, please skip this section.
Can't say you were not given fair warning! There are two types of cases that are likely to arise when there are two (or more) reference systems in use with one text.
The two (or more) reference systems share start/end points, or
The two (or more) reference system have different start/end points.
The simpler case, where start and end points coincide is treated first, followed by the more complex one with differing start and end points (also known as overlapping).
In the case were two reference systems share start and end points, the OSIS best practice solution is to encode each osisID twice, once for each element. That is to say that a verse, for example, would have an osisID just like it would for any other text, and, it will have a second osisID that has a work prefix. That is to say there is no defaulting of the work prefix on the second osisID. An example of such an encoding is:
text text texttext text text
text text text text
Note that the material that begins with "h:" is the second reference system and the prefix, must be a reference to a work found in the header of the document. (Last chance to bail before we get to the really ugly one.)
A more complex case is presented when the two reference systems do not agree where elements start and end. While alternatives do exist, the OSIS method for dealing with this problem is called milestones. A milestone, like the ones along side a highway, simply mark a location in a particular spot. OSIS milestones, also tell you if they are the starting or ending milestone, plus carry other attributes associated with the element they are representing.
Using OSIS milestones, the case where two reference systems do not agree on start and end points can be shown as:
text text
text text
text text
text text
While the display may look rather confusing, it actually works quite simply. Start at line 2, for example. The osisID is Ps.1.1 with no prefix. That indicates that this is in the declared default reference system for this work. Now look down the list until you see an attribute called eID on a verse that has a value that matches that of line 2. That's correct, line six has a verse with eID="A" so it matches the verse at the beginning of line 2.
In full the matching is as follows:
matches line 11
matches line 6
matches line 4
matches line 3
matches line 8
matches line 2
matches line 10
matches line 6
matches a line not shown
matches line 7
matches line 1
Appendix H Encoding textual and edition variation
Bibles and other ancient works frequently differ in different surviving manuscripts. Sometimes this variation must be represented in printed, electroinc, or other editions, even in translation. For such cases, OSIS provides the rdg ("reading") element, corresponding to the TEI element of the same name. This element is used to identify each variation of a particular portion of the text, and may identify each variant with the set of textual witnesses that support it and with a type such as primary, secondary, etc. For example,
The pre-defined values for the type attribute are:
Primary: The preferred reading, supported by the preponderance of evidence.
Secondary: A less well supported, but still reasonably well-supported reading.
Tenuous: A poorly-supported reading, such as one included for completeness.
Alternate: A reading of approximately equal probability compared to others.
WordDiv: A reading derived by a different word-division of the source text (applicable primarily when the source text was written in scripto continuo.
These categories are not exact, such as could be assigned by a computer, but are intended to reflect categories commonly expressed in notes or typography in study Bibles.
Works are sometimes also published in multiple editions with slightly differing content. For example, Bibles may be published in Catholic and Protestant editions, which differ in the selection of Deutero-canonical books and possibly in other ways as well. Such differences should be expressed using the editions attribute (added in OSIS version 2.1), which is available on all OSIS elements.
When using the editions attribute, its value should contain one or more osisWorkIDs, each associated with a specific edition declared by a work element in the header. These are the editions for which the content of the element is to be included. Any elements that are not in the scope of a non-null editions attribute, default to being included in all editions.
For example, to indicate that the book of Sirach is to be included in the "Catholic" and "Study" editions, but not others, the book would begin:
Appendix I osisIDs: Construction Rules
The really adventurous 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.
Appendix I.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:
Appendix I.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
Appendix I.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 others 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?
Appendix J osisRefs: Construction Rules
The osisRef regex is over twice as long as the osisID regex, in part because of the additional 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.
Appendix J.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:
Appendix J.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
Appendix J.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?
Appendix J.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 minimum, 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 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@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 brackets. That limitation 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.
Appendix J.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.
Appendix K Conformance requirements
Appendix K.1 Conformance levels
There are 4 levels of OSIS conformance for the markup in OSIS documents:
Appendix K.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 actually 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).
Appendix K.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.
Appendix K.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.
Appendix K.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.
Appendix K.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":
Appendix K.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.
Appendix K.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.
Appendix K.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.
Appendix K.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).
Appendix L 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. Implementers 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.
Appendix M 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.
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.
