linked-rolls 0.29.0 → 0.31.0

package/README.md

@@ -40,8 +40,24 @@ Files written by linked-rolls 0.1 load unchanged: `importJsonLd`
 recognises their shapes and brings them to the current format, in
 which versions and conditions carry a typology key beside their type,
 the keeper and the production metadata are nodes with a name and
-authority links, and the roll names its reproducing system. Exports
-are always in the current format.
+authority links, and the roll names its reproducing system. A date
+written as a value of its own is read as the day the event falls
+within. Exports are always in the current format.
+
+## How a date is stated
+
+A date is the time-span of the event rather than a value on it.
+`within` gives the day it falls within, and `after` and `before` give
+the bounds where nobody can give the day. A bound the edition does not
+know is left out, so `after` alone says "not before". In RDF the three
+become `P82 at some time within`, `P82a begin of the begin` and `P82b
+end of the end` on the `E52 Time-Span` the event has. `assignDate`,
+`notBefore` and `notAfter` build the three shapes, and `dateOf`,
+`earliestOf` and `latestOf` read them.
+
+Note that `before` and `after` mean something else on a perforation,
+where they order two onsets. The context defines them for a date
+within the date itself, so the two never meet.
 
 ## What a version derives from
 

package/lib/Assumption.d.ts

@@ -144,16 +144,20 @@ export type ObjectAssumption<O extends object> = Assumption & O;
  */
 export type ActorAssignment = ObjectAssumption<Person>;
 /**
- * A date value wrapped as an assumption, so that the date
- * can be annotated with a belief about its certainty and source.
+ * When something happened, as far as the edition can state it: the day
+ * it falls `within`, or the bounds it lies between. A bound nobody can
+ * give is left out, so `after` alone says "not before".
+ * @see crm:E52 Time-Span
  */
-export type DateAssignment = ValueAssumption<Date> & {
-    /**
-     * The datatype of the value. Written on export so that
-     * RDF reads the value as a date rather than a string.
-     */
-    '@type'?: 'xsd:date';
-};
+export type DateAssignment = Assumption & ({
+    within: Date;
+} | {
+    after: Date;
+    before?: Date;
+} | {
+    before: Date;
+    after?: Date;
+});
 export declare function valueOf<ValueT>(assumption: ValueAssumption<ValueT>): ValueT;
 export declare function valuesOf<ValueT>(assumptions: ValueAssumption<ValueT>[]): ValueT[];
 export declare function idOf(assumption: ReferenceAssumption): string;
@@ -161,3 +165,15 @@ export declare function idsOf(assumptions: ReferenceAssumption[]): string[];
 export declare function assignValue<ValueT>(value: ValueT): ValueAssumption<ValueT>;
 export declare function assignReference(id: string): ReferenceAssumption;
 export declare function assignObject<O extends object>(obj: O): ObjectAssumption<O>;
+/** A date the edition states: the day the event falls within. */
+export declare const assignDate: (within: Date) => DateAssignment;
+/** A date the edition can only bound from below, as in "not before 1924". */
+export declare const notBefore: (after: Date) => DateAssignment;
+/** A date the edition can only bound from above. */
+export declare const notAfter: (before: Date) => DateAssignment;
+/** The day the event falls within, where the edition states one. */
+export declare const dateOf: (assignment: DateAssignment) => Date | undefined;
+/** The earliest the event can have happened, as far as the edition states it. */
+export declare const earliestOf: (assignment: DateAssignment) => Date | undefined;
+/** The latest the event can have happened, as far as the edition states it. */
+export declare const latestOf: (assignment: DateAssignment) => Date | undefined;

package/lib/Assumption.js

@@ -41,3 +41,15 @@ export function assignObject(obj) {
         ...obj
     };
 }
+/** A date the edition states: the day the event falls within. */
+export const assignDate = (within) => ({ within });
+/** A date the edition can only bound from below, as in "not before 1924". */
+export const notBefore = (after) => ({ after });
+/** A date the edition can only bound from above. */
+export const notAfter = (before) => ({ before });
+/** The day the event falls within, where the edition states one. */
+export const dateOf = (assignment) => 'within' in assignment ? assignment.within : undefined;
+/** The earliest the event can have happened, as far as the edition states it. */
+export const earliestOf = (assignment) => 'within' in assignment ? assignment.within : assignment.after;
+/** The latest the event can have happened, as far as the edition states it. */
+export const latestOf = (assignment) => 'within' in assignment ? assignment.within : assignment.before;

package/lib/Edition.d.ts

@@ -68,7 +68,7 @@ export interface RecordingEvent {
      * The recording date of the roll. This is a date
      * assignment so that we can state e.g. the catalogue
      * or the roll label which indicates the date of the recording.
-     * @see dcterms:date
+     * @see crm:P4 has time-span
      */
     date: DateAssignment;
     /**

package/lib/FeatureSource.d.ts

@@ -98,8 +98,7 @@ export interface FeatureSource extends WithNote {
     instrument?: ObjectAssumption<Instrument>;
     /**
      * When the capture took place.
-     * @format date
-     * @see dcterms:date
+     * @see crm:P4 has time-span
      */
     date?: DateAssignment;
 }

package/lib/RollCopy.d.ts

@@ -90,7 +90,7 @@ export interface ProductionEvent {
     paper?: Concept;
     /**
      * The date of production, if known.
-     * @see dcterms:date
+     * @see crm:P4 has time-span
      */
     date?: DateAssignment;
     /**
@@ -124,7 +124,7 @@ export type Modification = Partial<{
     actor: ActorAssignment;
     /**
      * When the modification took place.
-     * @see dcterms:date
+     * @see crm:P4 has time-span
      */
     date: DateAssignment;
 }> & ({
@@ -274,8 +274,10 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      */
     conditions: RollConditionAssignment[];
     /**
-     * A short siglum to identify the copy, e.g. "W1" or "S2". A copy
-     * without one is named by its keeper.
+     * A short siglum to identify the copy, e.g. "St1" or "Wi1": letters
+     * for the collection the copy was read in, and a number counting the
+     * copies of the roll held there. A copy without one is named by its
+     * keeper.
      * @see reo:siglum
      */
     siglum?: string;

package/lib/Version.d.ts

@@ -47,7 +47,7 @@ export interface VersionCreation {
     actor?: ActorAssignment;
     /**
      * When it took place.
-     * @see dcterms:date
+     * @see crm:P4 has time-span
      */
     date?: DateAssignment;
     /**
@@ -66,7 +66,11 @@ export interface VersionCreation {
  */
 export interface Version extends WithId, WithType<'Version'> {
     /**
-     * A short siglum to identify the version, e.g. "A", "B1", "B2_rev", etc.
+     * A short siglum to identify the version, e.g. "A" or "B2". A siglum
+     * is given once and not changed: its letter names the line the version
+     * was first recognised in, its number counts the versions admitted to
+     * that line. Where later work places the version elsewhere in the
+     * stemma, `basedOn` changes and the siglum stays.
      * @see reo:siglum
      */
     siglum: string;

package/lib/asJsonLd.js

@@ -35,9 +35,6 @@ const asJsonLdEntity = (obj) => {
             result[key] = value;
         }
     }
-    if ('@value' in obj && obj['@value'] instanceof Date) {
-        result['@type'] = 'xsd:date';
-    }
     return result;
 };
 /**

package/lib/editionOps.js

@@ -637,6 +637,19 @@ export const removeVersion = (view, versionId) => {
 };
 /** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
 export const removeSymbols = (versionId, symbolIds) => onVersion(versionId, version => dropInsertions(version, new Set(symbolIds)));
+/**
+ * The siglum for a version derived from this one: the line the siglum
+ * names, and the next number free in it. A number already given stays
+ * given, whatever the stemma does later.
+ */
+const nextInLine = (versions, siglum) => {
+    const [line] = siglum.match(/^\D*/) ?? [siglum];
+    const numbers = versions.flatMap(other => {
+        const match = other.siglum.match(/^(\D*)(\d*)$/);
+        return match && match[1] === line ? [Number(match[2] || 1)] : [];
+    });
+    return `${line}${Math.max(1, ...numbers) + 1}`;
+};
 /** Moves the edits into a new version based on this one. */
 export const deriveVersion = (versionId, editIds) => onVersion(versionId, (version, draft) => {
     const chosen = new Set(editIds);
@@ -646,7 +659,7 @@ export const deriveVersion = (versionId, editIds) => onVersion(versionId, (versi
     draft.versions.push({
         type: 'Version',
         id: v4(),
-        siglum: `${version.siglum}_derived`,
+        siglum: nextInLine(draft.versions, version.siglum),
         system: stateOf(version).system,
         basedOn: [assignReference(versionId)],
         edits: moved,

package/lib/importJsonLd.js

@@ -1,8 +1,5 @@
 import { migrate } from "./migrate";
-const isDate = (value) => {
-    const datePattern = /^\d{4}-\d{1,2}-\d{1,2}$/;
-    return datePattern.test(value);
-};
+import { isDateString } from "./utils";
 export const importDate = (str) => {
     const [y, m, d] = str.split('-').map(s => parseInt(s, 10));
     if ([y, m, d].some(n => isNaN(n))) {
@@ -13,7 +10,7 @@ export const importDate = (str) => {
 /** A value as the edition holds it: a date read, an entity converted, anything else as it stands. */
 const fromJsonLdValue = (value) => {
     if (typeof value === 'string')
-        return isDate(value) ? importDate(value) : value;
+        return isDateString(value) ? importDate(value) : value;
     if (Array.isArray(value))
         return value.map(fromJsonLdValue);
     if (value !== null && typeof value === 'object')

package/lib/migrate.js

@@ -3,6 +3,7 @@ import { rollConditions } from "./RollCopy";
 import { systemIdIn, systemOf, translationBetween } from "./TrackerBar";
 import { trackerBars } from "./systems";
 import { welteT100 } from "./systems/welteT100/bar";
+import { isDateString } from "./utils";
 const retiredVersionTypes = new Set(['edition', 'unicum']);
 const conditionTypeValues = new Set([...rollConditions, ...Object.values(conditions).flat()]);
 const renamedKeys = {
@@ -94,8 +95,19 @@ const withoutEmptyKeeper = (node) => {
     const { keeper: _unnamed, ...rest } = node;
     return rest;
 };
+/**
+ * A date was a value of its own before it was the time-span the event
+ * falls within. The datatype goes with it: the context now types each
+ * bound, and a `@type` left on the node would read as a class.
+ */
+const withTimeSpanDates = (node) => {
+    if (!isDateString(node['@value']))
+        return node;
+    const { '@value': within, '@type': _typed, ...rest } = node;
+    return { ...rest, within };
+};
 const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withReferences, withKeeper, withoutEmptyKeeper, withProductionNodes, withScale,
-    withDerivationList, withReadingKind]
+    withDerivationList, withReadingKind, withTimeSpanDates]
     .reduce((result, step) => step(result), node);
 /** The items each walked, or the very same list where the walk changed none. */
 const walked = (items) => {

package/lib/schema.json

@@ -256,43 +256,111 @@
             "ontology": "crm:E55 Type"
         },
         "DateAssignment": {
-            "description": "A date value wrapped as an assumption, so that the date can be annotated with a belief about its certainty and source.",
-            "properties": {
-                "@annotation": {
-                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+            "anyOf": [
+                {
                     "properties": {
-                        "belief": {
-                            "$ref": "#/definitions/Belief",
-                            "description": "The belief held about the annotated statement.",
-                            "ontology": "crminf:J4i is subject of"
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement.",
+                                    "ontology": "crminf:J4i is subject of"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
                         },
-                        "@id": {
-                            "description": "A unique identifier for this object.",
+                        "within": {
+                            "format": "date",
                             "type": "string"
                         }
                     },
                     "required": [
-                        "belief",
-                        "@id"
+                        "within"
                     ],
                     "type": "object"
                 },
-                "@type": {
-                    "const": "xsd:date",
-                    "description": "The datatype of the value. Written on export so that RDF reads the value as a date rather than a string.",
-                    "type": "string",
-                    "ontology": "rdf:type"
+                {
+                    "properties": {
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement.",
+                                    "ontology": "crminf:J4i is subject of"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
+                        },
+                        "after": {
+                            "format": "date",
+                            "type": "string"
+                        },
+                        "before": {
+                            "format": "date",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "after"
+                    ],
+                    "type": "object"
                 },
-                "@value": {
-                    "description": "The assumed value.",
-                    "format": "date",
-                    "type": "string"
+                {
+                    "properties": {
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement.",
+                                    "ontology": "crminf:J4i is subject of"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
+                        },
+                        "after": {
+                            "format": "date",
+                            "type": "string"
+                        },
+                        "before": {
+                            "format": "date",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "before"
+                    ],
+                    "type": "object"
                 }
-            },
-            "required": [
-                "@value"
             ],
-            "type": "object"
+            "description": "When something happened, as far as the edition can state it: the day it falls `within`, or the bounds it lies between. A bound nobody can give is left out, so `after` alone says \"not before\".",
+            "ontology": "crm:E52 Time-Span"
         },
         "Derivation": {
             "description": "A derivation names the version another one was derived from, together with the tolerance the two were collated at. How precisely the copies put a symbol depends on what they are and on how their features were obtained, so the tolerance can differ from derivation to derivation.",
@@ -638,8 +706,7 @@
                 "date": {
                     "$ref": "#/definitions/DateAssignment",
                     "description": "When the capture took place.",
-                    "format": "date",
-                    "ontology": "dcterms:date"
+                    "ontology": "crm:P4 has time-span"
                 },
                 "device": {
                     "$ref": "#/definitions/Concept",
@@ -1074,7 +1141,7 @@
                         "date": {
                             "$ref": "#/definitions/DateAssignment",
                             "description": "When the modification took place.",
-                            "ontology": "dcterms:date"
+                            "ontology": "crm:P4 has time-span"
                         },
                         "purpose": {
                             "enum": [
@@ -1113,7 +1180,7 @@
                         "date": {
                             "$ref": "#/definitions/DateAssignment",
                             "description": "When the modification took place.",
-                            "ontology": "dcterms:date"
+                            "ontology": "crm:P4 has time-span"
                         },
                         "purpose": {
                             "const": "delabeling",
@@ -1951,7 +2018,7 @@
                 "date": {
                     "$ref": "#/definitions/DateAssignment",
                     "description": "The date of production, if known.",
-                    "ontology": "dcterms:date"
+                    "ontology": "crm:P4 has time-span"
                 },
                 "paper": {
                     "$ref": "#/definitions/Concept",
@@ -2001,7 +2068,7 @@
                 "date": {
                     "$ref": "#/definitions/DateAssignment",
                     "description": "The recording date of the roll. This is a date assignment so that we can state e.g. the catalogue or the roll label which indicates the date of the recording.",
-                    "ontology": "dcterms:date"
+                    "ontology": "crm:P4 has time-span"
                 },
                 "place": {
                     "$ref": "#/definitions/Place",
@@ -2271,7 +2338,7 @@
                     "ontology": "crm:P138i has representation"
                 },
                 "siglum": {
-                    "description": "A short siglum to identify the copy, e.g. \"W1\" or \"S2\". A copy without one is named by its keeper.",
+                    "description": "A short siglum to identify the copy, e.g. \"St1\" or \"Wi1\": letters for the collection the copy was read in, and a number counting the copies of the roll held there. A copy without one is named by its keeper.",
                     "type": "string",
                     "ontology": "reo:siglum"
                 },
@@ -2446,7 +2513,7 @@
                     "type": "array"
                 },
                 "siglum": {
-                    "description": "A short siglum to identify the version, e.g. \"A\", \"B1\", \"B2_rev\", etc.",
+                    "description": "A short siglum to identify the version, e.g. \"A\" or \"B2\". A siglum is given once and not changed: its letter names the line the version was first recognised in, its number counts the versions admitted to that line. Where later work places the version elsewhere in the stemma, `basedOn` changes and the siglum stays.",
                     "type": "string",
                     "ontology": "reo:siglum"
                 },
@@ -2487,7 +2554,7 @@
                 "date": {
                     "$ref": "#/definitions/DateAssignment",
                     "description": "When it took place.",
-                    "ontology": "dcterms:date"
+                    "ontology": "crm:P4 has time-span"
                 },
                 "procedure": {
                     "$ref": "#/definitions/Concept",

package/lib/spec/context.json

@@ -103,8 +103,21 @@
         },
         "place": "crm:P7_took_place_at",
         "date": {
-            "@id": "dcterms:date",
-            "@type": "xsd:date"
+            "@id": "crm:P4_has_time-span",
+            "@context": {
+                "within": {
+                    "@id": "crm:P82_at_some_time_within",
+                    "@type": "xsd:date"
+                },
+                "after": {
+                    "@id": "crm:P82a_begin_of_the_begin",
+                    "@type": "xsd:date"
+                },
+                "before": {
+                    "@id": "crm:P82b_end_of_the_end",
+                    "@type": "xsd:date"
+                }
+            }
         },
         "created": "lrmoo:R17_created",
         "copies": "reo:witness",
@@ -148,7 +161,11 @@
                 "value": "crm:P90_has_value",
                 "measuredBy": "crmdig:L23_used_software_or_firmware",
                 "software": "rdfs:label",
-                "version": "owl:versionInfo"
+                "version": "owl:versionInfo",
+                "date": {
+                    "@id": "dcterms:date",
+                    "@type": "xsd:date"
+                }
             }
         },
         "production": {

package/lib/utils.d.ts

@@ -12,6 +12,8 @@ export type WithId = {
      */
     readonly id: string;
 };
+/** Whether a value is a date as the format writes one, `YYYY-MM-DD`. */
+export declare const isDateString: (value: unknown) => value is string;
 export type WithNote = {
     /**
      * A free-text note providing additional context.

package/lib/utils.js

@@ -1 +1,2 @@
-export {};
+/** Whether a value is a date as the format writes one, `YYYY-MM-DD`. */
+export const isDateString = (value) => typeof value === 'string' && /^\d{4}-\d{1,2}-\d{1,2}$/.test(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {