@intellectual-frontiers/rdf 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Intellectual Frontiers
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @intellectual-frontiers/rdf
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ RDF as algebraically typed values: IRIs, namespaces, typed vocabularies, class schemas, code lists, and the writers of N-Triples, N-Quads, canonical Turtle and JSON-LD; pure, no host, the same code on Bun, Node 26 and in a browser.
4
+
5
+ ```sh
6
+ bun add @intellectual-frontiers/rdf # or: npm install @intellectual-frontiers/rdf
7
+ ```
8
+
9
+ Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/rdf
package/dist/mod.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ /**
2
+ * RDF as algebraically typed values and the writers of its syntaxes (commons rdf 0001-rdf): IRIs branded once checked, namespaces and typed vocabularies, named nodes, literals typed by language or datatype,
3
+ * class schemas, code lists, the checks a type cannot state, and N-Triples, N-Quads, canonical Turtle and expanded JSON-LD. The one entry of the package `@intellectual-frontiers/rdf`: every module of `src/` is
4
+ * exported from here, so that a harness states its ontology as TypeScript with one import.
5
+ *
6
+ * @example
7
+ * ```ts
8
+ * import { classSchema, en, namespace, one, OwlClass, range, rdfs, term, triplesOf, turtle, vocabulary } from "@intellectual-frontiers/rdf";
9
+ * const EX = namespace("ex", "https://example.org/terms#");
10
+ * const ex = vocabulary(EX, { Tool: "owl:Class", runs: "owl:DatatypeProperty" });
11
+ * const Tool = classSchema(ex.Tool, { label: one(rdfs.label, range.langString), runs: one(ex.runs, range.string) });
12
+ * turtle({ prefixes: [EX], triples: triplesOf([OwlClass.make(ex.Tool, { label: en("Tool") })]) });
13
+ * ```
14
+ *
15
+ * @module
16
+ */
17
+ export * from "./rdf-term.js";
18
+ export * from "./rdf-schema.js";
19
+ export * from "./rdf-vocabularies.js";
20
+ export * from "./rdf-write.js";
21
+ export * from "./rdf.js";
package/dist/mod.js ADDED
@@ -0,0 +1,22 @@
1
+ // Spec: 0001-rdf FR-008
2
+ /**
3
+ * RDF as algebraically typed values and the writers of its syntaxes (commons rdf 0001-rdf): IRIs branded once checked, namespaces and typed vocabularies, named nodes, literals typed by language or datatype,
4
+ * class schemas, code lists, the checks a type cannot state, and N-Triples, N-Quads, canonical Turtle and expanded JSON-LD. The one entry of the package `@intellectual-frontiers/rdf`: every module of `src/` is
5
+ * exported from here, so that a harness states its ontology as TypeScript with one import.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { classSchema, en, namespace, one, OwlClass, range, rdfs, term, triplesOf, turtle, vocabulary } from "@intellectual-frontiers/rdf";
10
+ * const EX = namespace("ex", "https://example.org/terms#");
11
+ * const ex = vocabulary(EX, { Tool: "owl:Class", runs: "owl:DatatypeProperty" });
12
+ * const Tool = classSchema(ex.Tool, { label: one(rdfs.label, range.langString), runs: one(ex.runs, range.string) });
13
+ * turtle({ prefixes: [EX], triples: triplesOf([OwlClass.make(ex.Tool, { label: en("Tool") })]) });
14
+ * ```
15
+ *
16
+ * @module
17
+ */
18
+ export * from "./rdf-term.js";
19
+ export * from "./rdf-schema.js";
20
+ export * from "./rdf-vocabularies.js";
21
+ export * from "./rdf-write.js";
22
+ export * from "./rdf.js";
@@ -0,0 +1,190 @@
1
+ import { type Iri, type LangString, type Named, type NamedOf, type Namespace, type Triple, type Value, type VocabularyTerm } from "./rdf-term.js";
2
+ /** What a field's values may be: a plain string, a string in a language, either, a boolean, an integer, or a reference. */
3
+ export type RangeKind = "string" | "lang" | "text" | "boolean" | "integer" | "ref";
4
+ /** A field's range, with the TypeScript type `V` of its values for the compiler. */
5
+ export type Range<V> = {
6
+ readonly kind: RangeKind;
7
+ readonly words?: readonly string[];
8
+ readonly "@ifc/rdf-value": V;
9
+ };
10
+ /** The ranges of a field. `ref<"a" | "b">()` accepts an individual of either class. */
11
+ export declare const range: {
12
+ /** A plain string (`xsd:string`). */
13
+ readonly string: Range<string>;
14
+ /** A string in a language. */
15
+ readonly langString: Range<LangString>;
16
+ /** A plain string or a string in a language. */
17
+ readonly text: Range<string | LangString>;
18
+ /** A boolean (`xsd:boolean`). */
19
+ readonly boolean: Range<boolean>;
20
+ /** An integer (`xsd:integer`); one that is not a safe integer is found by `validate`. */
21
+ readonly integer: Range<number>;
22
+ /** A reference to an individual of one of the classes `C`. */
23
+ readonly ref: <C extends string>() => Range<NamedOf<C>>;
24
+ /** A plain string that is one of `words`: the union of the words is the field's type. */
25
+ readonly oneOf: <const W extends readonly [string, ...string[]]>(words: W) => Range<W[number]>;
26
+ };
27
+ /** How many values a field holds: exactly one, at most one, or any number in order. */
28
+ export type Cardinality = "one" | "optional" | "many";
29
+ /** A field of a schema: its property, its range and its cardinality. */
30
+ export type Field<V, K extends Cardinality> = {
31
+ readonly property: Named;
32
+ readonly range: Range<V>;
33
+ readonly cardinality: K;
34
+ };
35
+ /** A field holding exactly one value. */
36
+ export declare function one<V>(property: Named, r: Range<V>): Field<V, "one">;
37
+ /** A field holding at most one value. */
38
+ export declare function optional<V>(property: Named, r: Range<V>): Field<V, "optional">;
39
+ /** A field holding any number of values, in the order given. */
40
+ export declare function many<V>(property: Named, r: Range<V>): Field<V, "many">;
41
+ /** The fields of a schema, by the names its individuals' values are written with. */
42
+ export type Fields = Readonly<Record<string, Field<unknown, Cardinality>>>;
43
+ type ValueOf<F> = F extends Field<infer V, Cardinality> ? V : never;
44
+ type Keys<S extends Fields, K extends Cardinality> = {
45
+ readonly [N in keyof S]: S[N] extends Field<unknown, K> ? N : never;
46
+ }[keyof S];
47
+ /** The values of an individual of a schema with the fields `S`: a required field's value, an optional one's, a list for `many`. */
48
+ export type ValuesOf<S extends Fields> = {
49
+ readonly [N in Keys<S, "one">]: ValueOf<S[N]>;
50
+ } & {
51
+ readonly [N in Keys<S, "optional">]?: ValueOf<S[N]>;
52
+ } & {
53
+ readonly [N in Keys<S, "many">]?: readonly ValueOf<S[N]>[];
54
+ };
55
+ /** One predicate of an individual and its values in order: what its triples are made from. */
56
+ export type Statement = {
57
+ readonly predicate: Named;
58
+ readonly objects: readonly Value[];
59
+ readonly words?: readonly string[];
60
+ };
61
+ /** An individual: a named node of its class `C`, with the class, its values `V` and the statements they make (its type first). */
62
+ export type Individual<C extends string, V> = Named<C> & {
63
+ readonly class: Named;
64
+ readonly values: V;
65
+ readonly statements: readonly Statement[];
66
+ };
67
+ /** An individual of any class, as a writer or a check takes it. */
68
+ export type AnyIndividual = Named & {
69
+ readonly class: Named;
70
+ readonly statements: readonly Statement[];
71
+ };
72
+ /** A class schema: the class, its CURIE, its fields, and how an individual of it is made. */
73
+ export type ClassSchema<C extends string, S extends Fields> = {
74
+ /** The class. */
75
+ readonly class: Named;
76
+ /** The class's CURIE, the brand of its individuals. */
77
+ readonly curie: C;
78
+ /** The fields, in the order their triples are made. */
79
+ readonly fields: S;
80
+ /** An individual of the class: the subject and its values. */
81
+ readonly make: (subject: Named<C>, values: ValuesOf<S>) => Individual<C, ValuesOf<S>>;
82
+ };
83
+ /** The schema of a class (a term of a vocabulary, whose CURIE brands the individuals) with its fields. */
84
+ export declare function classSchema<const C extends string, const S extends Fields>(cls: VocabularyTerm<never, C>, fields: S): ClassSchema<C, S>;
85
+ /** The schema of an ontology's own description: `owl:Ontology` with its label, description and version. */
86
+ export declare const OwlOntology: ClassSchema<"owl:Ontology", {
87
+ readonly label: Field<LangString, "optional">;
88
+ readonly comment: Field<LangString, "optional">;
89
+ readonly description: Field<LangString, "optional">;
90
+ readonly versionInfo: Field<string, "optional">;
91
+ readonly versionIri: Field<Named<"owl:Ontology">, "optional">;
92
+ }>;
93
+ /** The schema of a class: its label, comment, SKOS definition and superclasses. */
94
+ export declare const OwlClass: ClassSchema<"owl:Class", {
95
+ readonly label: Field<LangString, "optional">;
96
+ readonly comment: Field<LangString, "optional">;
97
+ readonly subClassOf: Field<Named<"owl:Class"> | Named<"rdfs:Class">, "many">;
98
+ readonly definition: Field<LangString, "optional">;
99
+ }>;
100
+ /** The schema of an object property: its label, comment, domain, range and SKOS definition. */
101
+ export declare const ObjectProperty: ClassSchema<"owl:ObjectProperty", {
102
+ readonly label: Field<LangString, "optional">;
103
+ readonly comment: Field<LangString, "optional">;
104
+ readonly domain: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
105
+ readonly range: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
106
+ readonly definition: Field<LangString, "optional">;
107
+ }>;
108
+ /** The schema of a datatype property: its label, comment, domain, range and SKOS definition. */
109
+ export declare const DatatypeProperty: ClassSchema<"owl:DatatypeProperty", {
110
+ readonly label: Field<LangString, "optional">;
111
+ readonly comment: Field<LangString, "optional">;
112
+ readonly domain: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
113
+ readonly range: Field<Named<"owl:Class"> | Named<"rdfs:Class"> | Named<"rdfs:Datatype">, "optional">;
114
+ readonly definition: Field<LangString, "optional">;
115
+ }>;
116
+ /** The named node of the ontology a namespace's terms belong to (`https://example.org/terms` for `https://example.org/terms#`). */
117
+ export declare function ontologyOf(ns: Namespace): Named<"owl:Ontology">;
118
+ /** A code list: individuals of one class keyed by their local names, whose keys' union is the type code branches on. */
119
+ export type CodeList<C extends string, V, K extends string> = {
120
+ readonly [N in K]: Individual<C, V>;
121
+ };
122
+ /** The code list of a schema's class in a namespace: each key is a local name, each value the individual's values. */
123
+ export declare function codes<C extends string, S extends Fields, const E extends Readonly<Record<string, ValuesOf<S>>>>(schema: ClassSchema<C, S>, ns: Namespace, entries: E): CodeList<C, ValuesOf<S>, keyof E & string>;
124
+ /** The key of a code list that names an individual, or nothing where none does. */
125
+ export declare function codeOf<K extends string>(list: {
126
+ readonly [N in K]: Named;
127
+ }, node: Named): K | undefined;
128
+ /** The schema of a SKOS concept scheme: its label and definition. */
129
+ export declare const ConceptSchemeSchema: ClassSchema<"skos:ConceptScheme", {
130
+ readonly prefLabel: Field<LangString, "one">;
131
+ readonly definition: Field<LangString, "optional">;
132
+ }>;
133
+ /** The schema of a SKOS concept: its scheme, notation, label and definition. */
134
+ export declare const ConceptSchema: ClassSchema<"skos:Concept", {
135
+ readonly inScheme: Field<Named<"skos:ConceptScheme">, "one">;
136
+ readonly notation: Field<string, "one">;
137
+ readonly prefLabel: Field<LangString, "one">;
138
+ readonly definition: Field<LangString, "optional">;
139
+ }>;
140
+ /** What one concept of a scheme says beside its notation: its local name in the namespace, its label and its definition. */
141
+ export type ConceptEntry = {
142
+ readonly local: string;
143
+ readonly label: LangString;
144
+ readonly definition?: LangString;
145
+ };
146
+ /** A SKOS concept scheme: the scheme, its concepts by notation, and every individual it states. */
147
+ export type ConceptScheme<N extends string> = {
148
+ /** The scheme itself. */
149
+ readonly scheme: Individual<"skos:ConceptScheme", ValuesOf<typeof ConceptSchemeSchema.fields>>;
150
+ /** Its concepts, by notation. */
151
+ readonly concepts: {
152
+ readonly [K in N]: Individual<"skos:Concept", ValuesOf<typeof ConceptSchema.fields>>;
153
+ };
154
+ /** The scheme and its concepts, in order. */
155
+ readonly individuals: readonly AnyIndividual[];
156
+ };
157
+ /** A SKOS concept scheme in a namespace, its concepts keyed by their notations, whose union is the type of a notation. */
158
+ export declare function conceptScheme<const E extends Readonly<Record<string, ConceptEntry>>>(ns: Namespace, local: string, head: {
159
+ readonly label: LangString;
160
+ readonly definition?: LangString;
161
+ }, entries: E): ConceptScheme<keyof E & string>;
162
+ /** One file of an ontology: its name, the prefixes its Turtle may write, and the individuals it states, in order. */
163
+ export type OntologyFile = {
164
+ readonly name: string;
165
+ readonly prefixes: readonly Namespace[];
166
+ readonly individuals: readonly AnyIndividual[];
167
+ };
168
+ /** The triples of individuals: each individual's statements in order, each triple once, where first stated. */
169
+ export declare function triplesOf(individuals: readonly AnyIndividual[]): readonly Triple[];
170
+ /** What a type cannot state about individuals (or what a run without the type checker lets through): an integer that is not a safe integer, a word not of its field's list, or a subject stated twice. */
171
+ export type RdfFinding = {
172
+ readonly kind: "not-an-integer";
173
+ readonly subject: Iri;
174
+ readonly predicate: Iri;
175
+ readonly value: number;
176
+ } | {
177
+ readonly kind: "not-one-of";
178
+ readonly subject: Iri;
179
+ readonly predicate: Iri;
180
+ readonly value: string;
181
+ readonly words: readonly string[];
182
+ } | {
183
+ readonly kind: "stated-twice";
184
+ readonly subject: Iri;
185
+ };
186
+ /** The sentence a finding is told with. */
187
+ export declare function formatRdfFinding(f: RdfFinding): string;
188
+ /** Every finding about the individuals, in the order they are stated. */
189
+ export declare function validate(individuals: readonly AnyIndividual[]): readonly RdfFinding[];
190
+ export {};
@@ -0,0 +1,215 @@
1
+ // Spec: 0001-rdf FR-003
2
+ /**
3
+ * Class schemas and the individuals they make (commons 0012-ontology FR-003 to FR-005). A schema names a class and its fields, each a
4
+ * property, a range and a cardinality; the type of an individual's values is derived from it, so a required field left out, a value of
5
+ * the wrong range or a reference to an individual of another class does not compile. An individual is a named node of its class, used
6
+ * wherever a reference to that class is asked for, and its triples are its type and then its fields in the schema's order. The schemas an
7
+ * ontology states about itself (OWL's ontology, class and properties), code lists keyed by local name and SKOS concept schemes keyed by
8
+ * notation are here too, and `validate` names what a type cannot state.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import { classSchema, many, one, range } from "./rdf-schema.ts";
13
+ * import { en, namespace, term, vocabulary } from "./rdf-term.ts";
14
+ * import { rdfs } from "./rdf-vocabularies.ts";
15
+ * const EX = namespace("ex", "https://example.org/terms#");
16
+ * const ex = vocabulary(EX, { Shelf: "owl:Class", Book: "owl:Class", holds: "rdf:Property" });
17
+ * const Book = classSchema(ex.Book, { label: one(rdfs.label, range.langString) });
18
+ * const Shelf = classSchema(ex.Shelf, { holds: many(ex.holds, range.ref<"ex:Book">()) });
19
+ * const iliad = Book.make(term(EX, "iliad"), { label: en("The Iliad") });
20
+ * Shelf.make(term(EX, "top"), { holds: [iliad] }); // a Shelf given where a Book is asked for does not compile
21
+ * ```
22
+ *
23
+ * @module
24
+ */
25
+ import { absurd } from "@intellectual-frontiers/core";
26
+ import { named, nTriplesTerm, ontologyIri, RDF_TYPE, term, termOf, } from "./rdf-term.js";
27
+ import { dcterms, owl, rdfs, skos } from "./rdf-vocabularies.js";
28
+ function rangeOf(kind, words) {
29
+ return (words === undefined ? { kind } : { kind, words });
30
+ }
31
+ /** The ranges of a field. `ref<"a" | "b">()` accepts an individual of either class. */
32
+ export const range = {
33
+ /** A plain string (`xsd:string`). */
34
+ string: rangeOf("string"),
35
+ /** A string in a language. */
36
+ langString: rangeOf("lang"),
37
+ /** A plain string or a string in a language. */
38
+ text: rangeOf("text"),
39
+ /** A boolean (`xsd:boolean`). */
40
+ boolean: rangeOf("boolean"),
41
+ /** An integer (`xsd:integer`); one that is not a safe integer is found by `validate`. */
42
+ integer: rangeOf("integer"),
43
+ /** A reference to an individual of one of the classes `C`. */
44
+ ref: () => rangeOf("ref"),
45
+ /** A plain string that is one of `words`: the union of the words is the field's type. */
46
+ oneOf: (words) => rangeOf("string", words),
47
+ };
48
+ /** A field holding exactly one value. */
49
+ export function one(property, r) {
50
+ return { property, range: r, cardinality: "one" };
51
+ }
52
+ /** A field holding at most one value. */
53
+ export function optional(property, r) {
54
+ return { property, range: r, cardinality: "optional" };
55
+ }
56
+ /** A field holding any number of values, in the order given. */
57
+ export function many(property, r) {
58
+ return { property, range: r, cardinality: "many" };
59
+ }
60
+ function isValue(x) {
61
+ return typeof x === "string" || typeof x === "number" || typeof x === "boolean" || (typeof x === "object" && x !== null && "kind" in x);
62
+ }
63
+ function valuesIn(x) {
64
+ if (x === undefined)
65
+ return [];
66
+ if (Array.isArray(x))
67
+ return x.filter(isValue);
68
+ return isValue(x) ? [x] : [];
69
+ }
70
+ /** The schema of a class (a term of a vocabulary, whose CURIE brands the individuals) with its fields. */
71
+ export function classSchema(cls, fields) {
72
+ const klass = named(cls.iri);
73
+ return {
74
+ class: klass,
75
+ curie: cls.curie,
76
+ fields,
77
+ make: (subject, values) => {
78
+ const own = values;
79
+ const statements = [{ predicate: named(RDF_TYPE), objects: [klass] }];
80
+ for (const [name, f] of Object.entries(fields)) {
81
+ const objects = valuesIn(own[name]);
82
+ if (objects.length === 0)
83
+ continue;
84
+ statements.push(f.range.words === undefined ? { predicate: f.property, objects } : { predicate: f.property, objects, words: f.range.words });
85
+ }
86
+ const made = { ...named(subject.iri), class: klass, values, statements };
87
+ return made;
88
+ },
89
+ };
90
+ }
91
+ /** The schema of an ontology's own description: `owl:Ontology` with its label, description and version. */
92
+ export const OwlOntology = classSchema(owl.Ontology, {
93
+ label: optional(rdfs.label, range.langString),
94
+ comment: optional(rdfs.comment, range.langString),
95
+ description: optional(dcterms.description, range.langString),
96
+ versionInfo: optional(owl.versionInfo, range.string),
97
+ versionIri: optional(owl.versionIRI, range.ref()),
98
+ });
99
+ /** The schema of a class: its label, comment, SKOS definition and superclasses. */
100
+ export const OwlClass = classSchema(owl.Class, {
101
+ label: optional(rdfs.label, range.langString),
102
+ comment: optional(rdfs.comment, range.langString),
103
+ subClassOf: many(rdfs.subClassOf, range.ref()),
104
+ definition: optional(skos.definition, range.langString),
105
+ });
106
+ const PROPERTY = {
107
+ label: optional(rdfs.label, range.langString),
108
+ comment: optional(rdfs.comment, range.langString),
109
+ domain: optional(rdfs.domain, range.ref()),
110
+ range: optional(rdfs.range, range.ref()),
111
+ definition: optional(skos.definition, range.langString),
112
+ };
113
+ /** The schema of an object property: its label, comment, domain, range and SKOS definition. */
114
+ export const ObjectProperty = classSchema(owl.ObjectProperty, PROPERTY);
115
+ /** The schema of a datatype property: its label, comment, domain, range and SKOS definition. */
116
+ export const DatatypeProperty = classSchema(owl.DatatypeProperty, PROPERTY);
117
+ /** The named node of the ontology a namespace's terms belong to (`https://example.org/terms` for `https://example.org/terms#`). */
118
+ export function ontologyOf(ns) {
119
+ return named(ontologyIri(ns));
120
+ }
121
+ /** The code list of a schema's class in a namespace: each key is a local name, each value the individual's values. */
122
+ export function codes(schema, ns, entries) {
123
+ const out = {};
124
+ for (const [local, values] of Object.entries(entries))
125
+ out[local] = schema.make(term(ns, local), values);
126
+ return out;
127
+ }
128
+ /** The key of a code list that names an individual, or nothing where none does. */
129
+ export function codeOf(list, node) {
130
+ for (const key of Object.keys(list))
131
+ if (list[key].iri === node.iri)
132
+ return key;
133
+ return undefined;
134
+ }
135
+ /** The schema of a SKOS concept scheme: its label and definition. */
136
+ export const ConceptSchemeSchema = classSchema(skos.ConceptScheme, {
137
+ prefLabel: one(skos.prefLabel, range.langString),
138
+ definition: optional(skos.definition, range.langString),
139
+ });
140
+ /** The schema of a SKOS concept: its scheme, notation, label and definition. */
141
+ export const ConceptSchema = classSchema(skos.Concept, {
142
+ inScheme: one(skos.inScheme, range.ref()),
143
+ notation: one(skos.notation, range.string),
144
+ prefLabel: one(skos.prefLabel, range.langString),
145
+ definition: optional(skos.definition, range.langString),
146
+ });
147
+ /** A SKOS concept scheme in a namespace, its concepts keyed by their notations, whose union is the type of a notation. */
148
+ export function conceptScheme(ns, local, head, entries) {
149
+ const scheme = ConceptSchemeSchema.make(term(ns, local), {
150
+ prefLabel: head.label,
151
+ ...(head.definition === undefined ? {} : { definition: head.definition }),
152
+ });
153
+ const concepts = {};
154
+ for (const [notation, c] of Object.entries(entries)) {
155
+ concepts[notation] = ConceptSchema.make(term(ns, c.local), {
156
+ inScheme: scheme,
157
+ notation,
158
+ prefLabel: c.label,
159
+ ...(c.definition === undefined ? {} : { definition: c.definition }),
160
+ });
161
+ }
162
+ const typedConcepts = concepts;
163
+ return { scheme, concepts: typedConcepts, individuals: [scheme, ...Object.values(concepts)] };
164
+ }
165
+ /** The triples of individuals: each individual's statements in order, each triple once, where first stated. */
166
+ export function triplesOf(individuals) {
167
+ const out = [];
168
+ const seen = new Set();
169
+ for (const i of individuals) {
170
+ const subject = named(i.iri);
171
+ for (const s of i.statements) {
172
+ for (const v of s.objects) {
173
+ const object = termOf(v);
174
+ const key = `${i.iri} ${s.predicate.iri} ${nTriplesTerm(object)}`;
175
+ if (seen.has(key))
176
+ continue;
177
+ seen.add(key);
178
+ out.push({ subject, predicate: named(s.predicate.iri), object });
179
+ }
180
+ }
181
+ }
182
+ return out;
183
+ }
184
+ /** The sentence a finding is told with. */
185
+ export function formatRdfFinding(f) {
186
+ switch (f.kind) {
187
+ case "not-an-integer":
188
+ return `<${f.subject}> <${f.predicate}>: ${f.value} is not an integer this code can write exactly`;
189
+ case "not-one-of":
190
+ return `<${f.subject}> <${f.predicate}>: ${JSON.stringify(f.value)} is not one of ${f.words.join(", ")}`;
191
+ case "stated-twice":
192
+ return `<${f.subject}> is stated by two individuals`;
193
+ default:
194
+ return absurd(f);
195
+ }
196
+ }
197
+ /** Every finding about the individuals, in the order they are stated. */
198
+ export function validate(individuals) {
199
+ const out = [];
200
+ const seen = new Set();
201
+ for (const i of individuals) {
202
+ if (seen.has(i.iri))
203
+ out.push({ kind: "stated-twice", subject: i.iri });
204
+ seen.add(i.iri);
205
+ for (const s of i.statements) {
206
+ for (const v of s.objects) {
207
+ if (typeof v === "number" && !Number.isSafeInteger(v))
208
+ out.push({ kind: "not-an-integer", subject: i.iri, predicate: s.predicate.iri, value: v });
209
+ if (s.words !== undefined && typeof v === "string" && !s.words.includes(v))
210
+ out.push({ kind: "not-one-of", subject: i.iri, predicate: s.predicate.iri, value: v, words: s.words });
211
+ }
212
+ }
213
+ }
214
+ return out;
215
+ }
@@ -0,0 +1,162 @@
1
+ /**
2
+ * RDF terms as typed values (commons 0012-ontology FR-001, FR-002): an IRI branded once checked, a namespace that pairs a prefix with
3
+ * its IRI, a named node branded with the classes its term is an individual of, blank nodes, literals typed by their language or their
4
+ * datatype, and triples and quads of them. A vocabulary is a typed value made from a namespace and the local names of its terms, so a
5
+ * term it does not list does not compile. Generalized from erga's ontology DSL (`erga 248-ontology-in-typescript`) and stolos' RDF export.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { en, namespace, vocabulary } from "./rdf-term.js";
10
+ * const ex = vocabulary(namespace("ex", "https://example.org/terms#"), { Widget: "rdfs:Class", size: "rdf:Property" });
11
+ * ex.Widget.iri; // "https://example.org/terms#Widget"
12
+ * en("a widget"); // { kind: "lang", value: "a widget", language: "en" }
13
+ * ```
14
+ *
15
+ * @module
16
+ */
17
+ import { type Result } from "@intellectual-frontiers/core";
18
+ import type { Brand } from "@intellectual-frontiers/core";
19
+ /** An absolute IRI, checked by `parseIri` or made from a namespace. */
20
+ export type Iri = Brand<string, "rdf/Iri">;
21
+ /** Why a text is not an IRI: it has no scheme, or holds a character an IRI may not hold in N-Triples. */
22
+ export type IriError = {
23
+ readonly kind: "not-absolute";
24
+ readonly text: string;
25
+ } | {
26
+ readonly kind: "forbidden-character";
27
+ readonly text: string;
28
+ readonly at: number;
29
+ };
30
+ /** The text as an IRI, or why it is not one. */
31
+ export declare function parseIri(text: string): Result<Iri, IriError>;
32
+ /** The sentence an IRI error is told with. */
33
+ export declare function formatIriError(e: IriError): string;
34
+ /** A fault of the code: a constant namespace or term whose IRI does not parse. It is thrown where the constant is made. */
35
+ export declare class RdfFault extends Error {
36
+ /** The fault, told as a sentence. */
37
+ constructor(message: string);
38
+ }
39
+ /** The classes a named node is an individual of, as the compiler sees them: one key for each class's name. */
40
+ export type Classes<C extends string> = {
41
+ readonly [K in C]: true;
42
+ };
43
+ /**
44
+ * A named node: an IRI, branded with the classes its term is an individual of (by their CURIEs, `"pm:PackageManager"`). A
45
+ * `Named<"a" | "b">` is an individual of both, so it is accepted where either is asked for; a `Named<"a">` is not accepted where `"b"` is,
46
+ * and a `Named` of no known class (`Named`, which is `Named<never>`) is not accepted where any one class is asked for: every named node is
47
+ * a `Named`, so it is the type of a predicate or of any node at all.
48
+ */
49
+ export type Named<C extends string = never> = {
50
+ readonly kind: "named";
51
+ readonly iri: Iri;
52
+ readonly "@ifc/rdf-classes": Classes<C>;
53
+ };
54
+ /** A named node of any one of the classes `C` (`NamedOf<"a" | "b">` is a `Named<"a">` or a `Named<"b">`). */
55
+ export type NamedOf<C extends string> = C extends string ? Named<C> : never;
56
+ /** The named node of an IRI, as an individual of the classes `C`; the brand is for the compiler alone. */
57
+ export declare function named<C extends string = never>(iri: Iri): Named<C>;
58
+ /** A namespace: a prefix and the IRI its terms' local names are appended to. */
59
+ export type Namespace<P extends string = string> = {
60
+ readonly prefix: P;
61
+ readonly iri: Iri;
62
+ };
63
+ /** A namespace; one whose prefix or IRI is not well formed is a fault of the code, thrown as an `RdfFault`. */
64
+ export declare function namespace<const P extends string>(prefix: P, iri: string): Namespace<P>;
65
+ /** The IRI of a local name in a namespace; one that does not parse is a fault of the code, thrown as an `RdfFault`. */
66
+ export declare function iriIn(ns: Namespace, local: string): Iri;
67
+ /**
68
+ * The named node of a local name in a namespace, as an individual of the classes `C`, which the compiler takes from where it is used.
69
+ * It is how a term no module here states is named (an individual of another ontology); a term this code states comes from its schema.
70
+ */
71
+ export declare function term<C extends string = never>(ns: Namespace, local: string): Named<C>;
72
+ /** The IRI of the ontology a namespace's terms belong to: the namespace's IRI without its last `#` or `/`. */
73
+ export declare function ontologyIri(ns: Namespace): Iri;
74
+ /** A term of a vocabulary: a named node of its class, with its CURIE. */
75
+ export type VocabularyTerm<C extends string, Curie extends string> = Named<C> & {
76
+ readonly curie: Curie;
77
+ };
78
+ /** A typed vocabulary: each local name of `T` gives a term of the class `T` names for it. */
79
+ export type Vocabulary<P extends string, T extends Readonly<Record<string, string>>> = {
80
+ readonly [K in keyof T & string]: VocabularyTerm<T[K], `${P}:${K}`>;
81
+ };
82
+ /** The vocabulary of a namespace: its terms by local name, each of the class given (`{ label: "rdf:Property" }`). */
83
+ export declare function vocabulary<const P extends string, const T extends Readonly<Record<string, string>>>(ns: Namespace<P>, terms: T): Vocabulary<P, T>;
84
+ /** A language tag, checked against BCP 47's shape (letters, then subtags of letters and digits, joined by `-`). */
85
+ export type LanguageTag = Brand<string, "rdf/LanguageTag">;
86
+ /** The text as a language tag, in lower case, or nothing where it is not one. */
87
+ export declare function languageTag(text: string): LanguageTag | undefined;
88
+ /** A string in a language: `"install"@en`. */
89
+ export type LangString = {
90
+ readonly kind: "lang";
91
+ readonly value: string;
92
+ readonly language: LanguageTag;
93
+ };
94
+ /** A literal with its datatype (a plain string is an `xsd:string`). */
95
+ export type TypedLiteral = {
96
+ readonly kind: "typed";
97
+ readonly value: string;
98
+ readonly datatype: Iri;
99
+ };
100
+ /** A literal: a string in a language, or a lexical form with its datatype. */
101
+ export type Literal = LangString | TypedLiteral;
102
+ /** A blank node, by its label. */
103
+ export type Blank = {
104
+ readonly kind: "blank";
105
+ readonly label: string;
106
+ };
107
+ /** A node of the default graph's name. */
108
+ export type DefaultGraph = {
109
+ readonly kind: "default";
110
+ };
111
+ /** Any RDF term. */
112
+ export type Term = Named | Blank | Literal;
113
+ /** What a triple may be about. */
114
+ export type Subject = Named | Blank;
115
+ /** A triple. */
116
+ export type Triple = {
117
+ readonly subject: Subject;
118
+ readonly predicate: Named;
119
+ readonly object: Term;
120
+ };
121
+ /** A triple in a named graph, or in the default graph. */
122
+ export type Quad = Triple & {
123
+ readonly graph: Named | DefaultGraph;
124
+ };
125
+ /** Why a literal or a blank node could not be made. */
126
+ export type TermError = {
127
+ readonly kind: "language";
128
+ readonly tag: string;
129
+ } | {
130
+ readonly kind: "blank-label";
131
+ readonly label: string;
132
+ };
133
+ /** The sentence a term error is told with. */
134
+ export declare function formatTermError(e: TermError): string;
135
+ /** A string in the language of a tag, or why the tag is not one. */
136
+ export declare function lang(value: string, tag: string): Result<LangString, TermError>;
137
+ /** A string in English: `en("install")`. */
138
+ export declare function en(value: string): LangString;
139
+ /** The IRI of `xsd:string`. */
140
+ export declare const XSD_STRING: Iri;
141
+ /** The IRI of `xsd:integer`. */
142
+ export declare const XSD_INTEGER: Iri;
143
+ /** The IRI of `xsd:boolean`. */
144
+ export declare const XSD_BOOLEAN: Iri;
145
+ /** The IRI of `rdf:type`. */
146
+ export declare const RDF_TYPE: Iri;
147
+ /** A literal of a datatype: `typed("2026-11-16", xsd.date)`. */
148
+ export declare function typed(value: string, datatype: Named): TypedLiteral;
149
+ /** A plain string, an `xsd:string`. */
150
+ export declare function plain(value: string): TypedLiteral;
151
+ /** A blank node, or why its label is not one. */
152
+ export declare function blank(label: string): Result<Blank, TermError>;
153
+ /** The default graph. */
154
+ export declare const defaultGraph: DefaultGraph;
155
+ /** One value of a field: a plain string, an integer, a boolean, a literal or a named node. */
156
+ export type Value = string | number | boolean | Literal | Named;
157
+ /** The term of a value: a string is an `xsd:string`, a number an `xsd:integer` (in its canonical form), a boolean an `xsd:boolean`. */
158
+ export declare function termOf(v: Value): Term;
159
+ /** A string's characters escaped as N-Triples and Turtle write them, in quotes: `\b \t \n \f \r \" \\` and `\uXXXX` for the other controls. */
160
+ export declare function quoted(s: string): string;
161
+ /** A term as N-Triples writes it: `<iri>`, `_:label`, or a quoted literal with its language or its datatype (none for `xsd:string`). */
162
+ export declare function nTriplesTerm(t: Term): string;