@ontology-kit/format 0.0.0-stage → 0.1.0-bootstrap.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 +9 -0
- package/README.md +35 -2
- package/dist/edge-types.d.ts +18 -0
- package/dist/edge-types.js +26 -0
- package/dist/errors.d.ts +3 -0
- package/dist/errors.js +3 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +16 -0
- package/dist/model.d.ts +96 -0
- package/dist/model.js +501 -0
- package/dist/naming.d.ts +25 -0
- package/dist/naming.js +50 -0
- package/dist/registry.d.ts +4 -0
- package/dist/registry.js +39 -0
- package/dist/relationships.d.ts +30 -0
- package/dist/relationships.js +205 -0
- package/dist/types.d.ts +225 -0
- package/dist/types.js +13 -0
- package/package.json +49 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alan B Smith
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,36 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @ontology-kit/format
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Read the file format of [Ontology Kit](https://ontology-kit.dev): an ontology folder of `okb.json`, `nodes.json` and `edges.json`. It gives another tool the typed nodes and edges, loading (with conversion of older formats), the edge types the format reserves and the relationship values, without the `okb` command line, the meta-KB or the skills.
|
|
4
|
+
|
|
5
|
+
Needs **Node.js 24+**. It has no runtime dependencies.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @ontology-kit/format
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { Ontology, isRelationship, isStructuralEdgeType } from "@ontology-kit/format";
|
|
13
|
+
|
|
14
|
+
const ont = Ontology.load("./my-ontology");
|
|
15
|
+
|
|
16
|
+
// Every relationship value of every instance, whichever end the edge is stored on.
|
|
17
|
+
for (const slot of ont.ofType("Slot").filter(isRelationship)) {
|
|
18
|
+
for (const instance of ont.ofType("Instance")) {
|
|
19
|
+
for (const target of ont.rel.values(instance.id, slot.id)) {
|
|
20
|
+
console.log(`${instance.name} ${slot.name} ${ont.label(target)}`);
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// An edge whose type okb doesn't reserve is a relationship value.
|
|
26
|
+
const links = ont.edges.filter((e) => !isStructuralEdgeType(e.type));
|
|
27
|
+
console.log(`${links.length} relationship edges`);
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This package reads. To change an ontology, use the [`okb`](https://www.npmjs.com/package/@ontology-kit/okb) command. The exports follow semver, and `docs/FORMAT.md` lists them and says what counts as a breaking change. Before 1.0 any release may break them.
|
|
31
|
+
|
|
32
|
+
**Docs: [the format reference](https://ontology-kit.dev/reference/format/)**. The source is at [github.com/alanbsmith/ontology-kit](https://github.com/alanbsmith/ontology-kit).
|
|
33
|
+
|
|
34
|
+
## License
|
|
35
|
+
|
|
36
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Every node type the format defines, in the order of the registry. */
|
|
2
|
+
export declare const NODE_TYPES: readonly string[];
|
|
3
|
+
/**
|
|
4
|
+
* Every edge type okb reserves for its own structure: IS_A, INSTANCE_OF, HAS_SLOT, RANGE, INVERSE_OF,
|
|
5
|
+
* DISJOINT_WITH, NEEDS, BECAME, ABOUT, CITES, PART_OF, GOVERNS, REFINES, FULFILLS. An edge whose type is
|
|
6
|
+
* not in this list is a relationship value, stored under a relationship slot's `relType`. Built from
|
|
7
|
+
* the format registry, so a new structural edge type shows up here without a code change.
|
|
8
|
+
*/
|
|
9
|
+
export declare const STRUCTURAL_EDGE_TYPES: readonly string[];
|
|
10
|
+
/**
|
|
11
|
+
* The structural edge types of the provenance and rule layer: CITES, PART_OF, GOVERNS, REFINES, FULFILLS.
|
|
12
|
+
* A subset of STRUCTURAL_EDGE_TYPES.
|
|
13
|
+
*/
|
|
14
|
+
export declare const PROVENANCE_EDGE_TYPES: readonly string[];
|
|
15
|
+
/** Whether an edge type is one okb reserves (as opposed to a relationship slot's `relType`). */
|
|
16
|
+
export declare const isStructuralEdgeType: (type: string) => boolean;
|
|
17
|
+
/** Whether an edge type belongs to the provenance and rule layer. */
|
|
18
|
+
export declare const isProvenanceEdgeType: (type: string) => boolean;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The node and edge types the format reserves, built from the registry data (registry.ts, which the
|
|
3
|
+
* okb meta-KB build generates from format.yaml). Kept apart from the public entry so the model can
|
|
4
|
+
* use it without importing the entry.
|
|
5
|
+
*/
|
|
6
|
+
import { EDGE_TYPE_NAMES, NODE_TYPE_NAMES, PROVENANCE_EDGE_TYPE_NAMES } from "./registry.js";
|
|
7
|
+
/** Every node type the format defines, in the order of the registry. */
|
|
8
|
+
export const NODE_TYPES = NODE_TYPE_NAMES;
|
|
9
|
+
/**
|
|
10
|
+
* Every edge type okb reserves for its own structure: IS_A, INSTANCE_OF, HAS_SLOT, RANGE, INVERSE_OF,
|
|
11
|
+
* DISJOINT_WITH, NEEDS, BECAME, ABOUT, CITES, PART_OF, GOVERNS, REFINES, FULFILLS. An edge whose type is
|
|
12
|
+
* not in this list is a relationship value, stored under a relationship slot's `relType`. Built from
|
|
13
|
+
* the format registry, so a new structural edge type shows up here without a code change.
|
|
14
|
+
*/
|
|
15
|
+
export const STRUCTURAL_EDGE_TYPES = EDGE_TYPE_NAMES;
|
|
16
|
+
/**
|
|
17
|
+
* The structural edge types of the provenance and rule layer: CITES, PART_OF, GOVERNS, REFINES, FULFILLS.
|
|
18
|
+
* A subset of STRUCTURAL_EDGE_TYPES.
|
|
19
|
+
*/
|
|
20
|
+
export const PROVENANCE_EDGE_TYPES = PROVENANCE_EDGE_TYPE_NAMES;
|
|
21
|
+
const structural = new Set(STRUCTURAL_EDGE_TYPES);
|
|
22
|
+
const provenance = new Set(PROVENANCE_EDGE_TYPES);
|
|
23
|
+
/** Whether an edge type is one okb reserves (as opposed to a relationship slot's `relType`). */
|
|
24
|
+
export const isStructuralEdgeType = (type) => structural.has(type);
|
|
25
|
+
/** Whether an edge type belongs to the provenance and rule layer. */
|
|
26
|
+
export const isProvenanceEdgeType = (type) => provenance.has(type);
|
package/dist/errors.d.ts
ADDED
package/dist/errors.js
ADDED
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ontology-kit/format: the okb file format, as a library.
|
|
3
|
+
*
|
|
4
|
+
* Everything another tool needs to read an okb ontology folder: the typed nodes, loading with
|
|
5
|
+
* migrations of older formats, the edge types okb reserves, reading relationship values, and the
|
|
6
|
+
* few name helpers the format's identities are built from. It's an explicit allowlist: nothing else
|
|
7
|
+
* in the package is public, and the write side, which @ontology-kit/okb uses, is tagged internal in the
|
|
8
|
+
* source and left out of the shipped type declarations. docs/FORMAT.md lists the
|
|
9
|
+
* API and says what counts as a breaking change.
|
|
10
|
+
*/
|
|
11
|
+
export { Ontology, FORMAT, MANIFEST, findRoot, nodeLabel, nameOrText, literalValue, literalValues } from "./model.js";
|
|
12
|
+
export { OkbError } from "./errors.js";
|
|
13
|
+
export { Relationships, isRelationship, edgeProps } from "./relationships.js";
|
|
14
|
+
export type { LinkSpec } from "./relationships.js";
|
|
15
|
+
export { NODE_TYPES, STRUCTURAL_EDGE_TYPES, PROVENANCE_EDGE_TYPES, isStructuralEdgeType, isProvenanceEdgeType } from "./edge-types.js";
|
|
16
|
+
export { fold, key, rawTokens, relType, slug, stripAccents, tokens } from "./naming.js";
|
|
17
|
+
export { CARDINALITIES, DISPOSITIONS, MODALITIES, VALUE_TYPES, VERIFICATION_STATUSES, } from "./types.js";
|
|
18
|
+
export type { Cardinality, ClassNode, CompetencyQuestionNode, Conventions, DesignDecisionNode, Disposition, EdgePropertyDecl, ExtractedFields, Facets, FacetOverride, GraphEdge, GraphNode, InstanceNode, Literal, LiteralType, Manifest, Modality, NodeOf, NodeType, OkbNode, OntologyNode, RelationshipSlot, ReusedOntologyNode, RuleNode, SlotNode, SourceLocationNode, SourceNode, StoredValue, TermNode, ValueType, Verification, VerificationStatus, } from "./types.js";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ontology-kit/format: the okb file format, as a library.
|
|
3
|
+
*
|
|
4
|
+
* Everything another tool needs to read an okb ontology folder: the typed nodes, loading with
|
|
5
|
+
* migrations of older formats, the edge types okb reserves, reading relationship values, and the
|
|
6
|
+
* few name helpers the format's identities are built from. It's an explicit allowlist: nothing else
|
|
7
|
+
* in the package is public, and the write side, which @ontology-kit/okb uses, is tagged internal in the
|
|
8
|
+
* source and left out of the shipped type declarations. docs/FORMAT.md lists the
|
|
9
|
+
* API and says what counts as a breaking change.
|
|
10
|
+
*/
|
|
11
|
+
export { Ontology, FORMAT, MANIFEST, findRoot, nodeLabel, nameOrText, literalValue, literalValues } from "./model.js";
|
|
12
|
+
export { OkbError } from "./errors.js";
|
|
13
|
+
export { Relationships, isRelationship, edgeProps } from "./relationships.js";
|
|
14
|
+
export { NODE_TYPES, STRUCTURAL_EDGE_TYPES, PROVENANCE_EDGE_TYPES, isStructuralEdgeType, isProvenanceEdgeType } from "./edge-types.js";
|
|
15
|
+
export { fold, key, rawTokens, relType, slug, stripAccents, tokens } from "./naming.js";
|
|
16
|
+
export { CARDINALITIES, DISPOSITIONS, MODALITIES, VALUE_TYPES, VERIFICATION_STATUSES, } from "./types.js";
|
package/dist/model.d.ts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { OkbError } from "./errors.js";
|
|
2
|
+
import { Relationships, edgeProps, isRelationship } from "./relationships.js";
|
|
3
|
+
import { DISPOSITIONS, VALUE_TYPES, type ClassNode, type Conventions, type Facets, type GraphEdge, type InstanceNode, type Manifest, type NodeOf, type NodeType, type OkbNode, type OntologyNode, type RuleNode, type StoredValue } from "./types.js";
|
|
4
|
+
export { DISPOSITIONS, VALUE_TYPES };
|
|
5
|
+
export declare const FORMAT: string;
|
|
6
|
+
export declare const MANIFEST = "okb.json";
|
|
7
|
+
export { OkbError };
|
|
8
|
+
/** What a node is called: its name, or a question's/term's text, or a decision's title. */
|
|
9
|
+
export declare function nodeLabel(n: OkbNode): string;
|
|
10
|
+
export { isRelationship };
|
|
11
|
+
export declare function findRoot(start: string): string | null;
|
|
12
|
+
export declare class Ontology {
|
|
13
|
+
root: string;
|
|
14
|
+
manifest: Manifest;
|
|
15
|
+
private _nodes;
|
|
16
|
+
private _edges;
|
|
17
|
+
private byId;
|
|
18
|
+
/** Relationship values and the edges that store them (see relationships.ts). */
|
|
19
|
+
readonly rel: Relationships;
|
|
20
|
+
private outIdx;
|
|
21
|
+
private incIdx;
|
|
22
|
+
constructor(root: string, manifest: Manifest, nodes: readonly OkbNode[], edges: readonly GraphEdge[]);
|
|
23
|
+
get nodes(): readonly OkbNode[];
|
|
24
|
+
get edges(): readonly GraphEdge[];
|
|
25
|
+
static load(start: string): Ontology;
|
|
26
|
+
static fromData(nodes: readonly OkbNode[], edges: readonly GraphEdge[], manifest?: Partial<Manifest>): Ontology;
|
|
27
|
+
private indexEdge;
|
|
28
|
+
/** The Ontology node (scope, conventions). A stand-in if the file lacks one; struct-well-formed reports that. */
|
|
29
|
+
get meta(): OntologyNode;
|
|
30
|
+
get conventions(): Conventions | undefined;
|
|
31
|
+
get step(): number;
|
|
32
|
+
get(id: string): OkbNode | undefined;
|
|
33
|
+
/**
|
|
34
|
+
* The node with this id, which the caller knows exists (an edge end, a stored
|
|
35
|
+
* slot id). Throws a readable OkbError rather than crashing on a hand-edited
|
|
36
|
+
* file where it doesn't.
|
|
37
|
+
*/
|
|
38
|
+
require(id: string): OkbNode;
|
|
39
|
+
require<T extends NodeType>(id: string, type: T): NodeOf<T>;
|
|
40
|
+
ofType<T extends NodeType>(type: T): NodeOf<T>[];
|
|
41
|
+
outEdges(id: string, type: string): GraphEdge[];
|
|
42
|
+
inEdges(id: string, type: string): GraphEdge[];
|
|
43
|
+
targets(id: string, type: string): string[];
|
|
44
|
+
sources(id: string, type: string): string[];
|
|
45
|
+
edgesOf(type: string): GraphEdge[];
|
|
46
|
+
label(id: string): string;
|
|
47
|
+
/** Find a node by id, or by name/text (case- and delimiter-insensitive) among `types`. */
|
|
48
|
+
find<T extends NodeType>(ref: string, types: T | readonly T[]): NodeOf<T>;
|
|
49
|
+
find(ref: string, types?: NodeType | readonly NodeType[]): OkbNode;
|
|
50
|
+
find<T extends NodeType>(ref: string, types: T | readonly T[] | undefined, required: false): NodeOf<T> | undefined;
|
|
51
|
+
parents(id: string): string[];
|
|
52
|
+
children(id: string): string[];
|
|
53
|
+
/** All classes above id (not including id). Cycle-safe. */
|
|
54
|
+
ancestors(id: string): Set<string>;
|
|
55
|
+
descendants(id: string): Set<string>;
|
|
56
|
+
private walk;
|
|
57
|
+
/** id plus all its ancestors. */
|
|
58
|
+
up(id: string): Set<string>;
|
|
59
|
+
/** a is b, or a (transitively) IS_A b. */
|
|
60
|
+
isSub(a: string, b: string): boolean;
|
|
61
|
+
/** a and b can never share members: a declared DISJOINT_WITH pair covers them (directly or via ancestors). */
|
|
62
|
+
disjointImplied(a: string, b: string): boolean;
|
|
63
|
+
roots(): string[];
|
|
64
|
+
/** Every class an instance belongs to, including inherited ones. */
|
|
65
|
+
instanceClasses(id: string): Set<string>;
|
|
66
|
+
/** Classes a node belongs to for slot purposes: an instance's classes, or a class and its ancestors. */
|
|
67
|
+
classContext(id: string): string[];
|
|
68
|
+
/** Whether following `type` edges from `from` ever reaches `to`. */
|
|
69
|
+
reaches(from: string, to: string, type: string): boolean;
|
|
70
|
+
ownSlots(id: string): string[];
|
|
71
|
+
slotsOfClasses(classes: Iterable<string>): string[];
|
|
72
|
+
/** Own + inherited slots of a class, all slots of an instance, or the slots declared to apply to Rules. */
|
|
73
|
+
applicableSlots(id: string): string[];
|
|
74
|
+
domain(slotId: string): string[];
|
|
75
|
+
/** Whether a slot belongs to anything: a class, or every Rule. */
|
|
76
|
+
isAttached(slotId: string): boolean;
|
|
77
|
+
range(slotId: string): string[];
|
|
78
|
+
inverses(slotId: string): string[];
|
|
79
|
+
/** Slot facets with overrides from any of `classes` applied (most restrictive wins). */
|
|
80
|
+
effectiveFacets(slotId: string, classes: Iterable<string>): Facets;
|
|
81
|
+
/** Values a node states for a slot: literals (values / fixedValues) plus relationship targets. */
|
|
82
|
+
statedValues(id: string, slotId: string): unknown[];
|
|
83
|
+
/** The fixed (class-level) values for a slot inherited from any of `classes`, with the class that set them. */
|
|
84
|
+
inheritedFixed(slotId: string, classes: Iterable<string>, exclude?: string): {
|
|
85
|
+
cls: string;
|
|
86
|
+
values: unknown[];
|
|
87
|
+
} | null;
|
|
88
|
+
}
|
|
89
|
+
/** A node's own literal value for a slot: an instance's value, or a class's fixed value. */
|
|
90
|
+
export declare function literalValue(n: OkbNode, slotId: string): StoredValue | undefined;
|
|
91
|
+
/** Where a node keeps its own literal values: instances and rules in `values`, classes in `fixedValues`. */
|
|
92
|
+
export declare function literalValues(n: InstanceNode | ClassNode | RuleNode): Record<string, StoredValue>;
|
|
93
|
+
/** A node's name, or a question's/term's text (undefined for anything else). */
|
|
94
|
+
export declare function nameOrText(n: OkbNode): string | undefined;
|
|
95
|
+
export { edgeProps };
|
|
96
|
+
export declare function editDistance(a: string, b: string): number;
|