The B·N·S Vocabulary
Abstract
The Branching Notational System (B·N·S) provides a means of
categorizing works and their constituent parts in an ordered,
branching tree.
1. Introduction
1.1 Purpose and Scope
The B·N·S vocabulary is the culmination of over a decade
of work attempting to catalogue multiple revisions of (primarily,
altho not exclusively, textual) works with potentially complex
inter·relationships and internal structure.
The initial version used semver‐inspired numeric identifiers
for project, version, and draft; this was soon
expanded to allow for non‐numeric identifiers as well as
volume and part divisions.
The current system uses a strict branching structure of potentially as
many as 12 levels, which are as follows :—
This system is known as the Branching Notational System (B·N·S), and
the B·N·S vocabulary provides the terms necessary for
describing it.
The namespace for the B·N·S vocabulary is
https://ns.1024.gdn/BNS/#.
1.2 Relationship to Other Vocabularies
The B·N·S is built upon various core metadata vocabularies
common to the web, like D·C·M·I, and makes use
of P·C·D·M for structural modelling.
In this document, the following prefixes are used to represent the
following strings :—
1.3 Term Status
Terms in this document are categorized according to one the five
following term statuses :—
- stable (✅)
-
The term has widely‐accepted usage.
- testing (🔬)
-
The term is currently being used in some applications, but its exact
meaning has not yet settled.
- dependency (📥)
-
The term is not currently being used directly, but its definition
informs the usage of a stable or testing term.
(This value is not a part of the original term status
definition.)
- unstable (🚧)
-
The term is not currently being used in a widespread fashion, but
experiments into its utility are taking place.
Its usage may change significantly in the future.
- archaic (🦖)
-
The term was once widely‐used, but such usage is considered outdated
and is discouraged.
1.4 Definitions for Computers
There is an Owl ontology for the B·N·S
vocabulary available in a J·son‐L·D format
suitable for viewing with, e·g, Protégé.
The term definitions seen on this page are derived from the Owl
definitions.
1.5 Using this Vocabulary
The B·N·S vocabulary is designed for use with R·D·F/X·M·L.
The marrus-sh/Corpora repository on Github
provides tools for creating and rendering B·N·S corpora.
Properties from the B·N·S namespace may also be useful in
other contexts, for example in federating works between systems.
2 Overview of Concepts
2.1 Corpora and Pseuds
In short, the B·N·S describes Corpora, which are collections
of works by a particular Pseud organized into a particular
branching structure.
The term Corpus refers not just to the works but also to the
branching structure itself:
Two Corpora which contain exactly the same works might still be
different if they have different structures.
Corpora are formally identified by a combination of a name
tag and a date tag, which together should
signify a domain name controlled by the person managing the Corpus at
the given date.
This can be represented using the syntax of a Tag U·R·I as
follows :—
tag:<nameTag>,<dateTag>:B@N/
—: where B@N/ is a magic string meant to indicate that the
tagged resource is a B·N·S Corpus.
The combination of name tag and date tag help to identify whether
backwards‐incompatible changes to a Corpus have been made:
Two Corpora with the same name tag and date tag must not contradict
each other.
This is easy to ensure if one always gives a Corpus a domain one
controls (ideally, the domain it is hosted at) and simply updates the
date after every backwards‐incompatible change.
In general, one should strive not to introduce
backwards‐incompatible changes, and maintain Corpora with their
existing name tags and date tags while expanding their contents.
Corpora describe the works of a single Pseud, who may not have any
relation to the person managing the Corpus or to the domain signified
in the name tag.
Pseuds are an abstraction for a notion of authorship which is
intentionally divorced from real individuals:
A Pseud could indicate any number of people, and people may be
represented by any number of Pseuds.
In general, the concept of Pseud exists to answer the question of “why
are these works being aggregated together?”, with the answer being
that they have some shared particularities of authorship which the
Pseud stands to represent.
The relationship between Pseuds and works collected in a Corpus need
not be exhaustive:
Works may have other authors or provenances provided they broadly fall
under the umbrella of a Project that the Pseud played a
significant role in.
2.2 Projects and Branches
Each broad endeavour in a Corpus is termed a
Project.
Projects must have both an integral, non·negative index
and an N·C·Name identifier, neither of which is
allowed to change after project creation.
Typically, projects are ordered in rough order of creation, starting
from 001.
In the creative arts, a Project corresponds roughly with the idea of a
“universe”, in that it may contain many different works across many
different mediums, but generally speaking there are shared concepts,
events, or esthetic qualities between the works which allow them to
be treated as belonging together.
The B·N·S cannot accommodate a work existing in multiple
Projects at once, so the person managing the Corpus will have to make
some decisions in cases of cross·over.
Projects, in turn, are broken up across several Branches,
which they include and which are included in each
other.
Branches come in two varieties, Division and
Revision.
Divisions are used to divide a work up into smaller parts, and are
often optional.
Revisions, on the other hand, indicate alternate expressions of the
same portion of a work, and are fundamental to its branch structure.
The available Divisions and Revisions are summarized in the table
below :—
| Branch Name |
Branch Kind |
Abbreviated Prefix |
Numeric Format |
| Book |
Division |
Bbl: |
Α, Β, Γ, Δ… |
| Concept |
Revision |
Ccp: |
1°, 2°, 3°, 4°… |
| Volume |
Division |
Vol: |
Ⅰ, ⅠⅠ, ⅠⅠⅠ, ⅠⅤ… |
| Arc |
Division |
Arc: |
α, β, γ, δ… |
| Version |
Revision |
Vsn: |
1′, 2′, 3′, 4′… |
| Side |
Division |
Vol: |
A, B, C, D… |
| Chapter |
Division |
Chp: |
01, 02, 03, 04… |
| Draft |
Revision |
Dft: |
1″, 2″, 3″, 4″… |
| Section |
Division |
Sec: |
a, b, c, d… |
| Verse |
Division |
Vrs: |
ⅰ, ⅰⅰ, ⅰⅰⅰ, ⅰⅴ… |
Projects themselves must include Books, which signify a single work
of potentially multiple parts.
From there, each branch may include any branch beneath it in the table,
up to the next Revision.
Books can only include Concepts, but Concepts can include Volumes,
Arcs, or Versions (but not Sides, Chapters, or Drafts).
This allows Divisions to be “skipped” if the work in question does not
make use of them.
Revisions must not be skipped, as that would make them impossible
to re·introduce later.
There is another restriction in addition to the above:
Within a Revision, the branching structure must be kept consistent,
up to the next Revision descendant, so (for example) if a Version
includes a Side which includes a Chapter, all of the Sides it
includes must include Chapters.
Another way of expressing this requirement is to say that whenever the
branch structure changes, it is necessary to introduce a new Revision
which encapsulates the change.
Like projects, each Branch has an index.
Branch indices may be negative, or in place of an integer they may be
an N·C·Name, a year~month (YYYY-MM), or a date (YYYY-MM-DD).
(Plain years are not allowed as they would be, in many cases,
indistinguishable from integers.)
When the index is a positive integer, it is often formatted specially.
This allows for a concise description of an Branch’s location within
a corpus; for example, 008:Γ:2°:ⅤⅠⅤ:δ:1′:E:06:3″:g:ⅰⅴ indicates the
fourth Verse of the seventh Section of the third Draft of the sixth
Chapter of the fifth Side of the first Version of the fourth Arc of
the ninth Volume of the second Concept of the third Book of the
eighth Project of some Corpus.
Note that logically, “Side E” still has an index of 5 (not "E",
which would instead be formatted as “Side 'E”).
Each branch type also has an associated prefix, which can be used in
the construction of file paths or Tag U·R·I’s.
For example,
tag:bns.example,2000:B@N/Prj:8/Bbl:3/Ccp:2/Vol:9/Arc:4/Vsn:1/Sde:5/Chp:3/Dft:3/Sec:7/Vrs:4.
2.3 Attaching Files
Some Branches have digital
manifestations, which can be either
Files or File Sequences.
File Sequences are provided for the case in which the Digital
Manifestation is paginated across multiple
files of the same type, for example a comic which is represented as
multiple images.
There is no way to represent complex file trees in the
B·N·S vocabulary; if files are not all of the same type,
they must first be encoded in some kind of container format (like a
Zip archive).
Every Digital Manifestation must have a media type from
the I·A·N·A media types registry, which indicates the
kind of file(s) it represents.
It is recommended that they also be assigned a type from the
D·C·M·I Type vocabulary, for example
Text.
Finally, if the Digital Manifestation is a File Sequence, it should be
identified as either a Bag or Sequence,
depending on whether it is unordered or ordered.
It is expected that fetching the I·R·I of a File, or of a File
Sequence’s members, will yield a binary
representation corresponding to its media type.
As each Digital Manifestation can be associated with exactly one thing,
this means that these I·R·I’s should be Branch‐specific.
Symbolic links or other mechanisms may be used in the case where the
same binary file needs to appear in the Digital Manifestation of
multiple Branches.
Only Branches which cannot include further
Revisions can have digital manifestations.
This limits them to Drafts, Sections, and
Verses.
Typically, if a Branch has a digital manifestation, it does not branch
further.
Regardless of whether a thing is a Pseud, a
Corpus, a Project, a Branch, or
indeed anything else, it is good to provide it with a full
title.
In space‐constrained environments, sometimes the full title is not
entirely necessary, and a short title can be provided
for these situations.
Resources can also have a description.
Descriptions are modelled in the B·N·S
vocabulary as Content Resources, whose
contents provide the actual description.
Contents can be provided as a string or as X·M·L; in the latter case,
it is recommended to use the @xml:lang attribute to specify the
language of the contents.
2.5 Complementary Resources
Corpora, Projects, and Branches can
be complemented by zero or more Complementary
Resources—Objects which are
related in some manner and aggregated together with a thing.
Like other Objects, Complementary Resources can have
descriptions and have digital
manifestations.
They can also be Content Resources and directly
include their contents.
The most important kind of Complementary Resource is the Note.
Notes are typically considered part of the branching structure of a
Corpus, and require identifiers for identification.
Other kinds of Complementary Resource include the Cover,
which provides cover artwork for a thing.
3. Dictionary of Terms
3.1 Class Definitions
3.1.20 ✅ Division (bns:Division)
- I·R·I
-
https://ns.1024.gdn/BNS/#Division
- Equivalent Class
-
bns:in some (bns:includes only bns:Division)
- Subclass Of
-
bns:Branch
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
stable
A Branch signifying a division within a work.
Date indicies and non·positive numeric indices for
Divisions are typically rendered verbatim, while N·C·Name
indices are rendered with a preceding straight single
quote :—
The rendering of positive numeric indices varies depending on the
type of Division, to make it more obvious which kind of
Division it is without needing to know the details of the
Branch structure.
3.1.25 🔬 File Sequence (bns:FileSequence)
- I·R·I
-
https://ns.1024.gdn/BNS/#FileSequence
- Subclass Of
-
rdf:Bag or rdf:Seq
-
bns:DigitalManifestation
- Disjoint With
-
pcdm:File
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
testing
An sequence of files (all having the same media type) which forms
the Digital Manifestation of some
thing.
A type of either Bag or Sequence should
be specified to distinguish whether the sequence is ordered or
unordered.
This class is useful in the case where an object is digitally
represented in a paginated format, for example as a sequence of
images or audio files.
It is not intended to represent more complicated digital
structures, which should instead be conveyed through some
manner of digital “wrapper” (e·g as a Zip file).
3.1.37 ✅ Pseud (bns:Pseud)
- I·R·I
-
https://ns.1024.gdn/BNS/#Pseud
- Subclass Of
-
dcterms:Agent
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
stable
An (abstract) creator of projects.
The term “pseud” derives from “pseudonym” and is meant to
emphasize the fact that corpora do not describe “people”
proper, but rather abstract people‐as‐authors, i·e acting in a
particular authorship capacity.
3.1.47 ✅ Text (dcmitype:Text)
- I·R·I
-
http://purl.org/dc/dcmitype/Text
- Is Defined By
-
https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
- Term Status
-
stable
A thing consisting primarily of words for reading.
Things are Texts even if they are being conveyed in a media type
which is graphic (for example, a scan of a text document as an
image/png is still a Text).
3.2 Object Property Definitions
3.3 Data Property Definitions
3.3.2 ✅ contents (bns:contents)
- I·R·I
-
https://ns.1024.gdn/BNS/#contents
- Range
-
rdf:PlainLiteral or rdf:XMLLiteral or xsd:string
- Functional?
-
yes
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
stable
The textual contents of this thing, as either plaintext or X·M·L.
3.3.6 ✅ date tag (bns:dateTag)
- I·R·I
-
https://ns.1024.gdn/BNS/#dateTag
- Range
-
xsd:string[pattern "-?([1-9][0-9]{3,}|0[0-9]{3})(-(0[1-9]|1[0-2])(-(0[1-9]|[12][0-9]|3[01]))?)?"]
- Functional?
-
yes
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
stable
A date at which the provided name tag was owned by
the authority wot assigned it.
O·W·L 2 does not properly support dates explicitly lacking
any timezone, so this property is defined as a string.
(This is fine, since it should be compared as a string and not a
date anyway.)
The year should be a positive four‐digit number for compliance
with R·F·C 4151.
3.3.11 ✅ index (bns:index)
- I·R·I
-
https://ns.1024.gdn/BNS/#index
- Range
-
xsd:NCName or xsd:integer or xsd:string[pattern "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])(-(0[1-9]|[12][0-9]|3[01]))?"]
- Functional?
-
yes
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
stable
A numeric index, date, year~month pair, or N·C·Name.
Indices which are dates or year~month pairs should be interpreted
as xsd:dates and
xsd:gYearMonths; this is not formally
specified due to limitations in O·W·L 2.
Indices are considered ordered in relation to other indices of
the same type, with the exception of N·C·Name, which is
semantically unordered.
By convention, if an NCName begins with an underscore followed by
an integer, date, or year~month pair and then another N·C·Name,
it is considered a variant of the item with an index of the
corresponding integer, date, or year~month pair.
The remainder is often rendered superscript, so that _3c is
rendered like 3c and sorted between 3
and 4.
There is as of yet no corresponding standard means of denoting
variants of N·C·Name indicies.
Numeric indicies are often rendered using a special syntax, for
example roman numerals.
When this happens, N·C·Name should be quoted in some manner to
distinguish.
3.4 Annotation Property Definitions
3.4.2 🔬 label (bns:textLabel)
- I·R·I
-
https://ns.1024.gdn/BNS/#textLabel
- Subproperty Of
-
rdfs:label
- Range
-
rdf:PlainLiteral or rdf:XMLLiteral or xsd:string
- Is Defined By
-
https://ns.1024.gdn/BNS/
- Term Status
-
testing
An explicitly textual label for this thing.
Text labels are used to provide convenient user‐facing
disambiguatory hints on objects which otherwise might not be
obviously different, for example two Files with the same
media type.