@iriograph/semantic-access

Framework-independent label-first search and revision-safe authoring facade over Iriograph Turtle.

Install

npm install --save-exact @iriograph/core @iriograph/semantic-access

Read

import { SemanticAccessIndex } from "@iriograph/semantic-access";

const semantic = new SemanticAccessIndex(document, workspaceRevision, {
  locales: ["en", "ja-JP"],
});

const resources = semantic.searchResources("approval");
const predicates = semantic.searchPredicates("depends on");
const detail = semantic.describe(resources[0].alias);
const related = semantic.subgraph(resources[0].alias, { depth: 2 });

Labels and descriptions support discovery but never replace identity. Results use aliases bound to an exact document revision and index fingerprint. Ordinary DTOs do not expose overlays, asset bytes, authenticated URLs, or raw SPARQL Update.

Read APIs cover resources and predicates, descriptions, localized values, class/property hierarchy, incoming/outgoing neighborhoods, exact statement comments, related subgraphs, and normalized Bag/Seq/Alt membership. Limited RDFS inference is explicit and separate from asserted-edge counts.

The standard predicate presentation API adds picker metadata for selected RDF/RDFS, Dublin Core Terms, PROV-O, SKOS, and non-restriction OWL relationship predicates without minting custom predicates. English is the deterministic default; Japanese and regional BCP 47 tags are supported while exact predicate IRIs and structural flags remain locale-independent.

import {
  standardPredicateTerms,
  standardPredicateVocabulary,
  standardPredicateVocabularyForLocale,
} from "@iriograph/semantic-access";

const englishDefaults = standardPredicateVocabulary;
const japanese = standardPredicateVocabularyForLocale("ja-JP");
const dependencies = standardPredicateTerms({ locale: "en-US", categories: ["Dependency"] });

Unknown locales fall back to English. standardPredicateVocabularyJa and standardPredicateTermsJa(categories) remain available for compatibility.

Write

A host injects a SemanticWritePort; direct Core hosts can use createCoreSemanticWritePort.

const preview = await semantic.preview({
  kind: "add-relation",
  source: sourceAlias,
  predicate: predicateAlias,
  target: targetAlias,
});

const committed = await semantic.apply({
  previewId: preview.previewId,
  confirmationId: preview.confirmationId,
});

Apply requires the same revision and exact preview binding. Stale and unknown aliases fail closed. Core or the Cloud write port remains responsible for final policy, canonical Turtle, all-view reconciliation, and atomic save.

See Semantic Access.

License

MIT. See LICENSE.