linked-rolls 0.41.0 → 0.43.0

package/lib/Agent.d.ts

@@ -67,10 +67,15 @@ export type WithActor = {
 export interface Place extends Named {
 }
 /**
- * A term from a vocabulary, such as a roll system or a kind of
- * paper. A term the type vocabulary knows carries its IRI as `id`.
+ * A term from a vocabulary, such as a roll system, a procedure or a
+ * kind of paper.
+ *
+ * A term the type vocabulary declares is named by its IRI, and what it
+ * is called stands in the vocabulary rather than in the edition, so it
+ * needs no name of its own; `nameOf` reads one either way. A term the
+ * vocabulary does not have is given by name, which is then all there is
+ * to go on.
  * @see crm:E55 Type
  */
-export interface Concept extends Named, Partial<WithId> {
-}
+export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
 export {};

package/lib/Feature.d.ts

@@ -131,36 +131,46 @@ export interface OnAFace {
      */
     side?: 'recto' | 'verso';
 }
+export declare const techniques: readonly ['print', 'handwriting', 'stamp'];
+/** How a trace was put on the paper. */
+export type Technique = typeof techniques[number];
+export declare const media: readonly ['ink', 'pencil', 'crayon'];
+/** What a trace was put on with. */
+export type Medium = typeof media[number];
 /**
  * A trace is a visible mark or writing on the roll surface.
  * Traces may fade over time.
  */
 export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions[T][number]>, OnAFace {
+    /**
+     * How the trace was put on the paper.
+     * @see reo:technique
+     */
+    technique?: Technique;
+    /**
+     * What it was put on with, where it can be told. A date may be
+     * known to be handwritten where the pencil cannot be told from
+     * the ink, and a stamp leaves its ink as much as a pen does,
+     * which is why the two are stated apart.
+     * @see reo:medium
+     */
+    medium?: Medium;
 }
-export declare const writingMethods: readonly ['print', 'handwriting', 'stamp'];
-/**
- * The method by which a writing was produced on the roll:
- * printed, handwritten, or stamped.
- */
-export type WritingMethod = typeof writingMethods[number];
-export declare const markMethods: readonly ['ink', 'pencil', 'crayon'];
-/** The medium a mark was drawn in. */
-export type MarkMethod = typeof markMethods[number];
 /** The text a writing carries. It names no carriers of its own, the writing being its carrier. */
 export type Transcription = Omit<Text, 'carriers'>;
 /**
  * A piece of writing found on the roll, such as a label,
- * catalogue number, or annotation. Writings have a method
- * of production and a transcription of their content.
+ * catalogue number, or annotation. Writings state how they were made
+ * and a transcription of their content.
  * @see reo:Writing
  */
 export interface Writing extends Trace<'Writing'> {
     /**
-     * The method by which this writing was produced
-     * (e.g. through print, handwriting, or stamping).
-     * @see reo:method
+     * A writing always states how it was put on the paper, which can
+     * be read off it where the medium cannot.
+     * @see reo:technique
      */
-    method: WritingMethod;
+    technique: Technique;
     /**
      * A transcription of the text content of the writing.
      * This is an object assumption so that the transcription
@@ -186,11 +196,6 @@ export interface Writing extends Trace<'Writing'> {
  * @see reo:Mark
  */
 export interface Mark extends Trace<'Mark'> {
-    /**
-     * The medium the mark was drawn in, where it can be told.
-     * @see reo:method
-     */
-    method?: MarkMethod;
 }
 /**
  * A piece of material (paper or tape) glued onto the roll surface.

package/lib/Feature.js

@@ -6,8 +6,8 @@ export const conditions = {
     Mark: ['faded'],
     GluedOn: ['detaching', 'ripped']
 };
-export const writingMethods = ['print', 'handwriting', 'stamp'];
-export const markMethods = ['ink', 'pencil', 'crayon'];
+export const techniques = ['print', 'handwriting', 'stamp'];
+export const media = ['ink', 'pencil', 'crayon'];
 export const isRollFeature = (obj) => {
     return 'type' in obj && isFeatureType(obj.type);
 };

package/lib/index.d.ts

@@ -18,6 +18,7 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './procedures';
+export * from './vocabulary';
 export * from './reservations';
 export * from './witnesses';
 export * from './alignment';

package/lib/index.js

@@ -18,6 +18,7 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './procedures';
+export * from './vocabulary';
 export * from './reservations';
 export * from './witnesses';
 export * from './alignment';

package/lib/migrate.js

@@ -1,4 +1,4 @@
-import { conditions, isFeatureType } from "./Feature";
+import { conditions, isFeatureType, media, techniques } from "./Feature";
 import { rollConditions } from "./RollCopy";
 import { systemIdIn, systemOf, translationBetween } from "./TrackerBar";
 import { trackerBars } from "./systems";
@@ -14,7 +14,7 @@ const renamedKeys = {
 const referenceKeys = ['alignedWith', 'pairedWith', 'basedOn'];
 /**
  * The five type terms that were capitalised while the rest of the
- * vocabulary was not, under the keys that carry them.
+ * vocabulary was not, under the keys that carried them then.
  */
 const lowerCasedTerms = {
     method: { Print: 'print', Handwriting: 'handwriting', Stamp: 'stamp' },
@@ -44,6 +44,24 @@ const withLowerCaseTerms = (node) => Object.entries(lowerCasedTerms).reduce((res
     const lowered = terms[result[key]];
     return lowered ? { ...result, [key]: lowered } : result;
 }, node);
+/** The key each term of the one-time `method` belongs under. */
+const splitMethods = {
+    ...Object.fromEntries(techniques.map(term => [term, 'technique'])),
+    ...Object.fromEntries(media.map(term => [term, 'medium']))
+};
+/**
+ * How a writing or a mark was put on the paper and what it was put on
+ * with stood under one key, which left a handwriting no room to say it
+ * was pencilled. A term the format no longer knows stays where it is,
+ * so that it fails validation rather than being filed under a guess.
+ */
+const withSplitMethod = (node) => {
+    const key = splitMethods[node.method];
+    if (!key)
+        return node;
+    const { method, ...rest } = node;
+    return { ...rest, [key]: method };
+};
 const withReferences = (node) => referenceKeys.reduce((result, key) => {
     const reference = result[key];
     if (reference && typeof reference === 'object' && '@value' in reference) {
@@ -203,7 +221,7 @@ const withTimeSpanDates = (node) => {
     const { '@value': within, '@type': _typed, ...rest } = node;
     return { ...rest, within };
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withLowerCaseTerms, withReferences, withKeeper, withoutEmptyKeeper,
+const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
     withProductionNodes, withScale, withDerivationList, withReadingKind, withTimeSpanDates, withoutFeatureKind,
     withBorneFeaturesNamed, withFeaturesInActs]
     .reduce((result, step) => step(result), node);

package/lib/schema.json

@@ -222,34 +222,66 @@
             "type": "object"
         },
         "Concept": {
-            "description": "A term from a vocabulary, such as a roll system or a kind of paper. A term the type vocabulary knows carries its IRI as `id`.",
-            "properties": {
-                "name": {
-                    "description": "The name, e.g. \"Grünfeld, Alfred\", \"Wien\", \"M. Welte & Söhne\".",
-                    "type": "string",
-                    "ontology": "rdfs:label"
-                },
-                "sameAs": {
-                    "description": "Authority records for the same thing: GND, Wikidata, geonames or similar.",
-                    "examples": [
-                        "https://d-nb.info/gnd/116888652"
-                    ],
-                    "items": {
-                        "type": "string"
+            "anyOf": [
+                {
+                    "properties": {
+                        "name": {
+                            "description": "The name, e.g. \"Grünfeld, Alfred\", \"Wien\", \"M. Welte & Söhne\".",
+                            "type": "string",
+                            "ontology": "rdfs:label"
+                        },
+                        "sameAs": {
+                            "description": "Authority records for the same thing: GND, Wikidata, geonames or similar.",
+                            "examples": [
+                                "https://d-nb.info/gnd/116888652"
+                            ],
+                            "items": {
+                                "type": "string"
+                            },
+                            "type": "array",
+                            "ontology": "owl:sameAs"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
                     },
-                    "type": "array",
-                    "ontology": "owl:sameAs"
+                    "required": [
+                        "@id"
+                    ],
+                    "type": "object"
                 },
-                "@id": {
-                    "description": "A unique identifier for this object.",
-                    "type": "string"
+                {
+                    "properties": {
+                        "name": {
+                            "description": "The name, e.g. \"Grünfeld, Alfred\", \"Wien\", \"M. Welte & Söhne\".",
+                            "type": "string",
+                            "ontology": "rdfs:label"
+                        },
+                        "sameAs": {
+                            "description": "Authority records for the same thing: GND, Wikidata, geonames or similar.",
+                            "examples": [
+                                "https://d-nb.info/gnd/116888652"
+                            ],
+                            "items": {
+                                "type": "string"
+                            },
+                            "type": "array",
+                            "ontology": "owl:sameAs"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "sameAs"
+                    ],
+                    "type": "object"
                 }
-            },
-            "required": [
-                "name",
-                "sameAs"
             ],
-            "type": "object",
+            "description": "A term from a vocabulary, such as a roll system, a procedure or a kind of paper.\n\nA term the type vocabulary declares is named by its IRI, and what it is called stands in the vocabulary rather than in the edition, so it needs no name of its own; `nameOf` reads one either way. A term the vocabulary does not have is given by name, which is then all there is to go on.",
             "ontology": "crm:E55 Type"
         },
         "DateAssignment": {
@@ -1024,10 +1056,10 @@
                     "description": "Horizontal span of the feature on the roll.",
                     "ontology": "crm:P43 has dimension"
                 },
-                "method": {
-                    "$ref": "#/definitions/MarkMethod",
-                    "description": "The medium the mark was drawn in, where it can be told.",
-                    "ontology": "reo:method"
+                "medium": {
+                    "$ref": "#/definitions/Medium",
+                    "description": "What it was put on with, where it can be told. A date may be known to be handwritten where the pencil cannot be told from the ink, and a stamp leaves its ink as much as a pen does, which is why the two are stated apart.",
+                    "ontology": "reo:medium"
                 },
                 "side": {
                     "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
@@ -1038,6 +1070,11 @@
                     "type": "string",
                     "ontology": "reo:side"
                 },
+                "technique": {
+                    "$ref": "#/definitions/Technique",
+                    "description": "How the trace was put on the paper.",
+                    "ontology": "reo:technique"
+                },
                 "vertical": {
                     "$ref": "#/definitions/VerticalSpan",
                     "description": "Vertical span of the feature on the roll.",
@@ -1063,15 +1100,6 @@
             "type": "object",
             "ontology": "reo:Mark"
         },
-        "MarkMethod": {
-            "description": "The medium a mark was drawn in.",
-            "enum": [
-                "ink",
-                "pencil",
-                "crayon"
-            ],
-            "type": "string"
-        },
         "MeaningComprehension": {
             "description": "A meaning comprehension interprets or disambiguates the meaning of symbols or features. For example, interpreting a pencil mark as an instruction to add or remove a perforation or as the dating of the roll.",
             "properties": {
@@ -1195,6 +1223,15 @@
             "type": "object",
             "ontology": "crm:E54 Dimension"
         },
+        "Medium": {
+            "description": "What a trace was put on with.",
+            "enum": [
+                "ink",
+                "pencil",
+                "crayon"
+            ],
+            "type": "string"
+        },
         "Millimeters": {
             "$ref": "#/definitions/Quantity%3C%22mm%22%3E",
             "description": "A place along the roll, or any length on the paper."
@@ -1451,10 +1488,10 @@
                             "description": "Horizontal span of the feature on the roll. Left out by a feature a patch bears.",
                             "ontology": "crm:P43 has dimension"
                         },
-                        "method": {
-                            "$ref": "#/definitions/WritingMethod",
-                            "description": "The method by which this writing was produced (e.g. through print, handwriting, or stamping).",
-                            "ontology": "reo:method"
+                        "medium": {
+                            "$ref": "#/definitions/Medium",
+                            "description": "What it was put on with, where it can be told. A date may be known to be handwritten where the pencil cannot be told from the ink, and a stamp leaves its ink as much as a pen does, which is why the two are stated apart.",
+                            "ontology": "reo:medium"
                         },
                         "rotation": {
                             "$ref": "#/definitions/Measure%3C%22deg%22%3E",
@@ -1470,6 +1507,11 @@
                             "type": "string",
                             "ontology": "reo:side"
                         },
+                        "technique": {
+                            "$ref": "#/definitions/Technique",
+                            "description": "A writing always states how it was put on the paper, which can be read off it where the medium cannot.",
+                            "ontology": "reo:technique"
+                        },
                         "transcription": {
                             "$ref": "#/definitions/ObjectAssumption%3CTranscription%3E",
                             "description": "A transcription of the text content of the writing. This is an object assumption so that the transcription can be annotated with a belief about its correctness.",
@@ -1493,7 +1535,7 @@
                     },
                     "required": [
                         "@id",
-                        "method",
+                        "technique",
                         "transcription",
                         "@type"
                     ],
@@ -1516,10 +1558,10 @@
                             "description": "Horizontal span of the feature on the roll. Left out by a feature a patch bears.",
                             "ontology": "crm:P43 has dimension"
                         },
-                        "method": {
-                            "$ref": "#/definitions/MarkMethod",
-                            "description": "The medium the mark was drawn in, where it can be told.",
-                            "ontology": "reo:method"
+                        "medium": {
+                            "$ref": "#/definitions/Medium",
+                            "description": "What it was put on with, where it can be told. A date may be known to be handwritten where the pencil cannot be told from the ink, and a stamp leaves its ink as much as a pen does, which is why the two are stated apart.",
+                            "ontology": "reo:medium"
                         },
                         "side": {
                             "description": "The face of the roll it lies on: the side that faces the reader as the roll plays, or the back of it.",
@@ -1530,6 +1572,11 @@
                             "type": "string",
                             "ontology": "reo:side"
                         },
+                        "technique": {
+                            "$ref": "#/definitions/Technique",
+                            "description": "How the trace was put on the paper.",
+                            "ontology": "reo:technique"
+                        },
                         "vertical": {
                             "$ref": "#/definitions/VerticalSpan",
                             "description": "Vertical span of the feature on the roll. Left out by a feature a patch bears.",
@@ -2888,6 +2935,15 @@
             ],
             "type": "string"
         },
+        "Technique": {
+            "description": "How a trace was put on the paper.",
+            "enum": [
+                "print",
+                "handwriting",
+                "stamp"
+            ],
+            "type": "string"
+        },
         "Text": {
             "description": "A textual symbol, e.g. a label or annotation found on the roll.",
             "properties": {
@@ -3068,7 +3124,7 @@
             "ontology": "crm:E54 Dimension"
         },
         "Writing": {
-            "description": "A piece of writing found on the roll, such as a label, catalogue number, or annotation. Writings have a method of production and a transcription of their content.",
+            "description": "A piece of writing found on the roll, such as a label, catalogue number, or annotation. Writings state how they were made and a transcription of their content.",
             "properties": {
                 "condition": {
                     "$ref": "#/definitions/ObjectAssumption%3CConditionState%3C(%22illegible%22)%3E%3E",
@@ -3085,10 +3141,10 @@
                     "description": "Horizontal span of the feature on the roll.",
                     "ontology": "crm:P43 has dimension"
                 },
-                "method": {
-                    "$ref": "#/definitions/WritingMethod",
-                    "description": "The method by which this writing was produced (e.g. through print, handwriting, or stamping).",
-                    "ontology": "reo:method"
+                "medium": {
+                    "$ref": "#/definitions/Medium",
+                    "description": "What it was put on with, where it can be told. A date may be known to be handwritten where the pencil cannot be told from the ink, and a stamp leaves its ink as much as a pen does, which is why the two are stated apart.",
+                    "ontology": "reo:medium"
                 },
                 "rotation": {
                     "$ref": "#/definitions/Measure%3C%22deg%22%3E",
@@ -3104,6 +3160,11 @@
                     "type": "string",
                     "ontology": "reo:side"
                 },
+                "technique": {
+                    "$ref": "#/definitions/Technique",
+                    "description": "A writing always states how it was put on the paper, which can be read off it where the medium cannot.",
+                    "ontology": "reo:technique"
+                },
                 "transcription": {
                     "$ref": "#/definitions/ObjectAssumption%3CTranscription%3E",
                     "description": "A transcription of the text content of the writing. This is an object assumption so that the transcription can be annotated with a belief about its correctness.",
@@ -3128,22 +3189,13 @@
             "required": [
                 "horizontal",
                 "@id",
-                "method",
+                "technique",
                 "transcription",
                 "@type",
                 "vertical"
             ],
             "type": "object",
             "ontology": "reo:Writing"
-        },
-        "WritingMethod": {
-            "description": "The method by which a writing was produced on the roll: printed, handwritten, or stamped.",
-            "enum": [
-                "print",
-                "handwriting",
-                "stamp"
-            ],
-            "type": "string"
         }
     }
 }

package/lib/spec/context.json

@@ -241,8 +241,13 @@
             "@type": "@vocab",
             "@context": { "@vocab": "https://w3id.org/reo/type/" }
         },
-        "method": {
-            "@id": "reo:method",
+        "technique": {
+            "@id": "reo:technique",
+            "@type": "@vocab",
+            "@context": { "@vocab": "https://w3id.org/reo/type/" }
+        },
+        "medium": {
+            "@id": "reo:medium",
             "@type": "@vocab",
             "@context": { "@vocab": "https://w3id.org/reo/type/" }
         },

package/lib/vocabulary.d.ts

@@ -0,0 +1,15 @@
+import { Concept } from "./Agent";
+/**
+ * The concepts the type vocabulary declares, whatever kind they are:
+ * the reproducing systems and the procedures. An edition names one of
+ * them by its IRI alone.
+ */
+export declare const vocabulary: readonly Concept[];
+/** The concept of that IRI, where the vocabulary declares one. */
+export declare const conceptOf: (id: string | undefined) => Concept | undefined;
+/**
+ * What a concept is called: the name it states, else the one the
+ * vocabulary gives it, else its IRI, so that a reader always has
+ * something to show.
+ */
+export declare const nameOf: (concept: Concept) => string;

package/lib/vocabulary.js

@@ -0,0 +1,20 @@
+import { procedures } from "./procedures";
+import { systemOf } from "./TrackerBar";
+import { trackerBars } from "./systems";
+/**
+ * The concepts the type vocabulary declares, whatever kind they are:
+ * the reproducing systems and the procedures. An edition names one of
+ * them by its IRI alone.
+ */
+export const vocabulary = [
+    ...trackerBars.map(systemOf),
+    ...procedures
+];
+/** The concept of that IRI, where the vocabulary declares one. */
+export const conceptOf = (id) => id === undefined ? undefined : vocabulary.find(concept => concept.id === id);
+/**
+ * What a concept is called: the name it states, else the one the
+ * vocabulary gives it, else its IRI, so that a reader always has
+ * something to show.
+ */
+export const nameOf = (concept) => concept.name ?? conceptOf(concept.id)?.name ?? concept.id ?? '';

package/package.json

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