A JSONPath query to a MarkerContent, Usj, or property within a USJ document and
additional information that point to a specific location in that USJ document.
This type does not include a verse reference because the JSONPath is relative to a specific USJ
document; that USJ document may have a book, a chapter, or something else in it. Use
UsjLocation to specify which USJ document this location is relative to, making the
location an absolute verse reference location. The closest equivalent concept in USFM to this
relative document location is a string character index in a USFM document; such an index is
relative to a specific USFM document rather than indicating an absolute position in a Scripture
text.
This type intends to represent USFM positions (UsfmVerseLocation) in USJ space. However,
there are some USFM positions that are not currently representable with these types:
The second slash in optbreak's USFM representation // (literally not representable)
Nested marker prefix on opening markers like + for character markers (literally not
representable)
The bar | that indicates the start of closing marker attributes (no official representation)
The equals sign for closing marker attributes (no official representation)
The quotes around closing marker attribute values (no official representation)
The space between closing marker attributes (no official representation)
Also note that the following types do not specify a concrete location that is actually in the USJ
document but represent a USFM location relative to the most similar thing in USJ that there is:
UsjClosingMarkerLocation - there are no distinct closing objects in JSON; there is a
common syntax for closing every object, but it is only one character and is on every single
object as opposed to USFM closing markers which are multiple characters long and are only
sometimes present.
UsjAttributeKeyLocation - when the attribute whose key is being pointed to is an attribute
marker in USFM, the keyOffset does not apply to the USJ attribute name (e.g. altnumber) but
to the USFM attribute marker name (e.g. ca).
UsjAttributeMarkerLocation - attribute markers are just properties in JSON; they do not
have their own object such that they would have an opening that can be pointed to in the JSON
like they have their own opening in USFM.
A JSONPath query to a MarkerContent, Usj, or property within a USJ document and additional information that point to a specific location in that USJ document.
This type does not include a verse reference because the JSONPath is relative to a specific USJ document; that USJ document may have a book, a chapter, or something else in it. Use UsjLocation to specify which USJ document this location is relative to, making the location an absolute verse reference location. The closest equivalent concept in USFM to this relative document location is a string character index in a USFM document; such an index is relative to a specific USFM document rather than indicating an absolute position in a Scripture text.
This type intends to represent USFM positions (UsfmVerseLocation) in USJ space. However, there are some USFM positions that are not currently representable with these types:
optbreak's USFM representation//(literally not representable)+for character markers (literally not representable)|that indicates the start of closing marker attributes (no official representation)Also note that the following types do not specify a concrete location that is actually in the USJ document but represent a USFM location relative to the most similar thing in USJ that there is:
keyOffsetdoes not apply to the USJ attribute name (e.g.altnumber) but to the USFM attribute marker name (e.g.ca).To see many examples of the same point represented by both USFM and USJ locations, go to https://github.com/paranext/paranext-core/tree/main/lib/platform-bible-utils/src/scripture/usj-reader-writer-test-data/testUSFM-2SA-1-locations.ts