linked-rolls 0.25.0 → 0.25.1

package/README.md

@@ -24,6 +24,16 @@ https://pfefferniels.github.io/linked-rolls/reo/; the w3id.org
 identifiers are not registered yet. `ontology/README.md` records the
 naming decisions.
 
+Beliefs travel as JSON-LD-star annotations (`@annotation`), which state
+the triple they annotate. A reference the edition holds possible,
+unlikely or false is therefore written as an embedded node beside the
+document: RDF names the statement without stating it, and
+`importJsonLd` puts it back where it stood. A doubted value, such as a
+date or an attribution, stays annotated in place for now. Reading the
+beliefs needs a processor that implements JSON-LD-star, such as the
+Ruby `json-ld` gem; jsonld.js ignores `@annotation`, and every belief
+with it.
+
 ## Format revisions
 
 Files written by linked-rolls 0.1 load unchanged: `importJsonLd`

package/lib/Assumption.d.ts

@@ -6,6 +6,13 @@ export declare const certainties: readonly ['true', 'likely', 'possible', 'unlik
  * and some values in between.
  */
 export type Certainty = typeof certainties[number];
+/**
+ * Whether a statement held with this certainty is stated as a fact when
+ * the edition is read as RDF. One held possible, unlikely or false is
+ * only quoted, so that a reader who leaves the beliefs aside does not
+ * take a doubted statement for the edition's own.
+ */
+export declare const isAsserted: (certainty: Certainty) => boolean;
 /**
  * An argumentation provides reasons for a belief and
  * may be associated with a person carrying out that argumentation.

package/lib/Assumption.js

@@ -5,6 +5,13 @@ export const certainties = [
     'unlikely',
     'false'
 ];
+/**
+ * Whether a statement held with this certainty is stated as a fact when
+ * the edition is read as RDF. One held possible, unlikely or false is
+ * only quoted, so that a reader who leaves the beliefs aside does not
+ * take a doubted statement for the edition's own.
+ */
+export const isAsserted = (certainty) => certainty === 'true' || certainty === 'likely';
 export function valueOf(assumption) {
     return assumption['@value'];
 }

package/lib/asJsonLd.js

@@ -1,4 +1,6 @@
 import { systemIdIn } from "./TrackerBar";
+import { isAsserted } from "./Assumption";
+import context from "./spec/context.json";
 export const exportDate = (date) => {
     const year = date.getFullYear();
     const month = String(date.getMonth() + 1).padStart(2, "0");
@@ -62,9 +64,76 @@ const withSystemContexts = (node) => {
         ? { '@context': `https://w3id.org/reo/${system}/context.jsonld`, ...walked }
         : walked;
 };
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Terms the context sets to null, which say nothing when the edition is read as RDF. */
+const silentTerms = new Set(Object.entries(context['@context'])
+    .filter(([, definition]) => definition === null)
+    .map(([term]) => term));
+/**
+ * A reference its belief does not hold to be so: it names a node, states
+ * nothing RDF would read besides, and its belief is below likely.
+ */
+const isDoubtedReference = (value) => isRecord(value)
+    && typeof value['@id'] === 'string'
+    && isRecord(value['@annotation'])
+    && !isAsserted(value['@annotation'].belief?.certainty ?? 'true')
+    && Object.keys(value).every(key => key === '@id' || key === '@annotation' || silentTerms.has(key));
+/**
+ * The statement a doubted reference makes, as a JSON-LD-star embedded
+ * node: the triple is named without being stated, and the belief is
+ * about it. The annotation's own id goes along under a key RDF does not
+ * read, so that an import can put it back.
+ */
+const quote = (subject, key, reference, listed) => {
+    const { '@annotation': { '@id': annotation, ...about }, ...object } = reference;
+    return { '@id': { '@id': subject, [key]: listed ? [object] : object }, annotation, ...about };
+};
+/** The value a node states under a key, less the doubted references, and those references quoted. */
+const quotingValue = (subject, key, value) => {
+    if (Array.isArray(value)) {
+        return {
+            node: value.filter(item => !isDoubtedReference(item)),
+            quoted: value.filter(isDoubtedReference).map(item => quote(subject, key, item, true))
+        };
+    }
+    return isDoubtedReference(value)
+        ? { node: undefined, quoted: [quote(subject, key, value, false)] }
+        : { node: value, quoted: [] };
+};
+/**
+ * The document with every doubted reference taken off the node that
+ * states it, and quoted instead.
+ *
+ * An `@annotation` in JSON-LD-star states the triple it annotates and
+ * then says something about it, so a statement the edition holds
+ * possible, unlikely or false would reach RDF as a fact. Only references
+ * between nodes are quoted, since only they can be put back where they
+ * stood; a doubted date or attribution stays annotated in place.
+ */
+const withDoubtedReferencesQuoted = (value) => {
+    if (Array.isArray(value)) {
+        const quotings = value.map(withDoubtedReferencesQuoted);
+        return { node: quotings.map(({ node }) => node), quoted: quotings.flatMap(({ quoted }) => quoted) };
+    }
+    if (!isRecord(value))
+        return { node: value, quoted: [] };
+    const subject = value['@id'];
+    const entries = Object.entries(value).map(([key, child]) => {
+        const own = typeof subject === 'string' && !key.startsWith('@')
+            ? quotingValue(subject, key, child)
+            : { node: child, quoted: [] };
+        const below = withDoubtedReferencesQuoted(own.node);
+        return { key, node: below.node, quoted: [...own.quoted, ...below.quoted] };
+    });
+    return {
+        node: Object.fromEntries(entries.filter(({ node }) => node !== undefined).map(({ key, node }) => [key, node])),
+        quoted: entries.flatMap(({ quoted }) => quoted)
+    };
+};
 export const asJsonLd = (edition) => {
+    const { node, quoted } = withDoubtedReferencesQuoted(withSystemContexts(asJsonLdEntity(edition)));
     // The context is the export's own; one carried in from an import must not override it.
-    const { base, '@context': carried, ...rest } = withSystemContexts(asJsonLdEntity(edition));
+    const { base, '@context': carried, ...rest } = node;
     return {
         '@context': [
             'https://w3id.org/reo/context.jsonld',
@@ -74,6 +143,7 @@ export const asJsonLd = (edition) => {
         ],
         '@type': "Edition",
         '@id': edition.base,
-        ...rest
+        ...rest,
+        ...(quoted.length > 0 && { '@included': quoted })
     };
 };

package/lib/migrate.js

@@ -200,5 +200,51 @@ const withDerivationTolerance = (edition) => {
             : version)
     };
 };
-const editionSteps = [withSystems, withEditors, withDerivationTolerance];
+/** A statement an export quoted rather than stated: an included node whose id is a triple. */
+const isQuotedStatement = (node) => node !== null && typeof node === 'object' && node['@id'] !== null && typeof node['@id'] === 'object';
+/** The reference a quoted statement made, annotated again with the belief the export set beside it. */
+const referenceOf = (statement) => {
+    const { '@id': { '@id': subject, ...made }, annotation, ...about } = statement;
+    const [key, value] = Object.entries(made)[0];
+    const listed = Array.isArray(value);
+    return {
+        subject,
+        key,
+        listed,
+        reference: {
+            ...(listed ? value[0] : value),
+            '@annotation': { ...(annotation !== undefined && { '@id': annotation }), ...about }
+        }
+    };
+};
+/** The document with each quoted reference back on the node that makes it, a node being what has a type. */
+const withReferencesOn = (value, bySubject) => {
+    if (Array.isArray(value))
+        return value.map(item => withReferencesOn(item, bySubject));
+    if (!value || typeof value !== 'object')
+        return value;
+    const walked = Object.fromEntries(Object.entries(value).map(([key, child]) => [key, withReferencesOn(child, bySubject)]));
+    const references = typeof value['@id'] === 'string' && value['@type'] !== undefined
+        ? bySubject.get(value['@id']) ?? []
+        : [];
+    return references.reduce((node, { key, listed, reference }) => ({ ...node, [key]: listed ? [...(node[key] ?? []), reference] : reference }), walked);
+};
+/**
+ * Puts back what an export quoted. A reference the edition doubts goes
+ * out as a JSON-LD-star embedded node beside the document, so that RDF
+ * does not state it; in the edition it belongs on the node that makes
+ * it, under its belief. In a list it comes back after the references
+ * that were stated.
+ */
+const withQuotedStatementsInPlace = (edition) => {
+    const included = Array.isArray(edition['@included']) ? edition['@included'] : [];
+    const statements = included.filter(isQuotedStatement);
+    if (statements.length === 0)
+        return edition;
+    const others = included.filter(node => !isQuotedStatement(node));
+    const { '@included': _quoted, ...rest } = edition;
+    const bySubject = Map.groupBy(statements.map(referenceOf), ({ subject }) => subject);
+    return withReferencesOn({ ...rest, ...(others.length > 0 && { '@included': others }) }, bySubject);
+};
+const editionSteps = [withQuotedStatementsInPlace, withSystems, withEditors, withDerivationTolerance];
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/spec/context.json

@@ -84,6 +84,7 @@
             "@type": "xsd:date"
         },
         "collationTolerance": null,
+        "annotation": null,
         "roll": "lrmoo:R3i_realises",
         "catalogueNumber": "dcterms:identifier",
         "system": "crm:P2_has_type",
@@ -117,7 +118,12 @@
         "role": {
             "@id": "crm:P2_has_type",
             "@type": "@vocab",
-            "@context": { "@vocab": "https://w3id.org/reo/type/" }
+            "@context": {
+                "@vocab": "https://w3id.org/reo/type/",
+                "pianist": "https://w3id.org/reo/type/pianist",
+                "publisher": "https://w3id.org/reo/type/publisher",
+                "transcription": "https://w3id.org/reo/type/transcription"
+            }
         },
         "ops": null,
         "measurements": {
@@ -173,7 +179,11 @@
                 "kind": {
                     "@id": "crm:P2_has_type",
                     "@type": "@vocab",
-                    "@context": { "@vocab": "https://w3id.org/reo/type/" }
+                    "@context": {
+                        "@vocab": "https://w3id.org/reo/type/",
+                        "roll": "https://w3id.org/reo/type/roll",
+                        "scan": "https://w3id.org/reo/type/scan"
+                    }
                 },
                 "output": {
                     "@id": "crmdig:L11_had_output",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,9 @@
     "build:docs": "node schema/docs/generate.ts src/schema.json docs/index.html"
   },
   "devDependencies": {
+    "@types/jsonld": "^1.5.15",
     "@types/node": "^24.13.3",
+    "jsonld": "^9.0.0",
     "ts-json-schema-generator": "^2.9.0",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",