About Verse References and Versification

Several methods and properties in the Paratext Plugin API work with IVerseRef objects. While the core of a verse ref is its book, chapter and verse, there is another element that needs to be considered to know for sure what a particular reference means. Every project or other Scripture-related data is based on a versification, represented by an IVersification object. Sometimes a particular chapter and verse in one versification can refer to a different chapter and verse in another versification. This is due to textual variants, denominational traditions and various other historical reasons. The objects that Paratext supplies that implement the IVerseRef and IVersification interfaces are aware of versification differences and take these into account when comparing references.

If plugins work with data that does not come from Paratext but is based on Scripture references, they need to consider which versification(s) might be reflected in that data.

Typically "resource" data representing external research (such as questions, commentaries, etc.) will be based on one of the standard versifications (e.g., "English" or "Vulgate"). The IPluginHost.GetStandardVersification method allows plugins to obtain the appropriate standard versification.

Project-specific data generated by a plugin user will typically be in that project's versification, which can be obtained using the IProject.Versification property. Once you have the desired IVersification object, you can generate a new IVerse using that versification using one of the CreateReference methods.

To avoid confusion, plugins will generally want to display references using the project versification. If you need to you can use either IVersification.ChangeVersification or IVerseRef.ChangeVersification. These methods will correctly and efficiently handle mapping between different versifications.

Finally, note that while plugins can create their own custom implementations of the IVersification interface, this is generally discouraged. It is typically difficult to be able to properly implement a custom versification. Especially mapping between a custom versification and a versification known to Paratext tends to be more-or-less impossible.