glossarist 0.2.2 → 0.3.0

package/README.md

@@ -308,8 +308,10 @@ import 'glossarist/validators'; // validation framework
 
 ```
 Public API (index.js)
-├── Domain models     → Concept, LocalizedConcept, Designation (Expression, Symbol, ...),
-│                       Citation, ConceptSource, RelatedConcept, DetailedDefinition, NonVerbRep
+├── Domain models     → Concept, LocalizedConcept, Designation (Expression, Abbreviation, Symbol,
+│                       LetterSymbol, GraphicalSymbol), GrammarInfo, Pronunciation, Locality,
+│                       Citation, ConceptSource, RelatedConcept, ConceptReference, ConceptDate,
+│                       DetailedDefinition, NonVerbRep
 ├── Parsing           → ConceptParser (canonical + managed format detection)
 ├── Serialization     → ConceptSerializer (canonical + managed YAML output)
 ├── I/O               → loadGcr, readConcepts, createGcr, writeConcepts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/concept-parser.js

@@ -1,5 +1,7 @@
 import yaml from 'js-yaml';
 import { Concept } from './models/concept.js';
+import { ConceptRef } from './models/concept-ref.js';
+import { RelatedConcept } from './models/related-concept.js';
 import { InvalidInputError, YamlParseError } from './errors.js';
 
 const STRUCTURAL_KEYS = new Set(['termid', 'term']);
@@ -70,11 +72,34 @@ export class ConceptParser {
       id: String(mc.data.identifier),
       term: null,
       localizations,
+      related: _normalizeRelated(mc.related ?? mc.data?.related),
       domains: mc.data.domains,
       groups: mc.data.groups,
+      dates: mc.dates ?? mc.data?.dates,
+      sources: mc.sources ?? mc.data?.sources,
+      status: mc.status,
+      schemaVersion: mc.schema_version,
       raw: mc,
     });
   }
 }
 
+function _normalizeRelated(arr) {
+  if (!arr || !Array.isArray(arr)) return [];
+  return arr.map(r => {
+    if (r instanceof RelatedConcept) return r;
+    const data = { ...r };
+    if (data.ref) {
+      if (typeof data.ref !== 'object' || data.ref === null) {
+        throw new InvalidInputError(
+          `RelatedConcept.ref must be an object { source, id }, got: ${typeof data.ref}`,
+          'object',
+        );
+      }
+      data.ref = new ConceptRef(data.ref);
+    }
+    return new RelatedConcept(data);
+  });
+}
+
 export const conceptParser = new ConceptParser();

package/src/concept-serializer.js

@@ -43,6 +43,18 @@ export class ConceptSerializer {
       mainDoc.data.domains = concept.domains.map(d => d.toJSON());
     }
 
+    if (concept.relatedConcepts.length > 0) {
+      mainDoc.related = concept.relatedConcepts.map(rc => rc.toJSON());
+    }
+    if (concept.sources.length > 0) {
+      mainDoc.sources = concept.sources.map(s => s.toJSON());
+    }
+    if (concept.dates.length > 0) {
+      mainDoc.dates = concept.dates.map(d => d.toJSON());
+    }
+    if (concept.status) mainDoc.status = concept.status;
+    if (concept.schemaVersion) mainDoc.schema_version = concept.schemaVersion;
+
     const parts = [
       '---\n' + yaml.dump(mainDoc, DUMP_OPTS),
       ...langDocs.map(d => '---\n' + yaml.dump(d, DUMP_OPTS)),

package/src/gcr-reader.js

@@ -26,7 +26,7 @@ const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 /**
  * @typedef {Object} Source
  * @property {string} type - e.g. 'authoritative', 'adapted'
- * @property {{ ref: string }} [origin] - reference to the source standard
+ * @property {{ ref: { source: string, id?: string, version?: string } }} [origin] - reference to the source standard
  */
 
 /**

package/src/index.d.ts

@@ -3,7 +3,7 @@ export {
   GlossaristModel,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
-  Citation, ConceptSource, RelatedConcept, ConceptDate,
+  Citation, ConceptRef, ConceptSource, RelatedConcept, ConceptDate,
   DetailedDefinition, NonVerbRep,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,

package/src/index.js

@@ -30,7 +30,7 @@ export {
   GlossaristModel,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
-  Citation, ConceptSource, RelatedConcept, ConceptReference, ConceptDate,
+  Citation, ConceptRef, ConceptSource, RelatedConcept, ConceptReference, ConceptDate,
   DetailedDefinition, NonVerbRep,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DATE_TYPES,

package/src/models/citation.js

@@ -1,45 +1,35 @@
 import { GlossaristModel } from './base.js';
+import { Locality } from './locality.js';
 
 export class Citation extends GlossaristModel {
-  constructor(data) {
+  constructor(data = {}) {
     super();
-    if (typeof data === 'string') {
-      this.source = data;
-      this.ref = null;
-      this.id = null;
-      this.version = null;
-      this.clause = null;
-      this.link = null;
-    } else {
-      const d = data ?? {};
-      this.source = d.source ?? null;
-      this.ref = d.ref ?? null;
-      this.id = d.id ?? null;
-      this.version = d.version ?? null;
-      this.clause = d.clause ?? null;
-      this.link = d.link ?? null;
-    }
-  }
-
-  get isStructured() {
-    return typeof this.source === 'object' && this.source !== null;
+    const d = data ?? {};
+
+    this.ref = d.ref
+      ? (d.ref instanceof Citation.Ref ? d.ref : new Citation.Ref(d.ref))
+      : null;
+
+    this.locality = d.locality
+      ? (d.locality instanceof Locality ? d.locality : new Locality(d.locality))
+      : null;
+    this.link = d.link ?? null;
+    this.original = d.original ?? null;
+    this.customLocality = d.custom_locality ?? d.customLocality ?? null;
   }
 
   toString() {
-    if (this.ref) return this.ref;
-    if (typeof this.source === 'string') return this.source;
-    if (typeof this.source === 'object' && this.source !== null) return this.source.ref ?? '';
+    if (this.ref) return this.ref.toString();
     return '';
   }
 
   toJSON() {
     const obj = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.ref != null) obj.ref = this.ref;
-    if (this.id != null) obj.id = this.id;
-    if (this.version != null) obj.version = this.version;
-    if (this.clause != null) obj.clause = this.clause;
+    if (this.ref != null) obj.ref = this.ref.toJSON();
+    if (this.locality != null) obj.locality = this.locality.toJSON();
     if (this.link != null) obj.link = this.link;
+    if (this.original != null) obj.original = this.original;
+    if (this.customLocality != null) obj.custom_locality = this.customLocality;
     return obj;
   }
 
@@ -47,3 +37,32 @@ export class Citation extends GlossaristModel {
     return new Citation(data);
   }
 }
+
+Citation.Ref = class Ref extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    const d = data ?? {};
+    this.source = d.source ?? null;
+    this.id = d.id ?? null;
+    this.version = d.version ?? null;
+  }
+
+  toString() {
+    const parts = [];
+    if (this.source) parts.push(this.source);
+    if (this.id) parts.push(this.id);
+    return parts.join(' ');
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.source != null) obj.source = this.source;
+    if (this.id != null) obj.id = this.id;
+    if (this.version != null) obj.version = this.version;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new Citation.Ref(data);
+  }
+};

package/src/models/concept-date.js

@@ -1,7 +1,7 @@
 import { GlossaristModel } from './base.js';
 
 export const DATE_TYPES = Object.freeze([
-  'accepted', 'amended', 'published', 'withdrawn', 'created',
+  'accepted', 'amended', 'retired',
 ]);
 
 export class ConceptDate extends GlossaristModel {

package/src/models/concept-ref.js

@@ -0,0 +1,25 @@
+import { GlossaristModel } from './base.js';
+
+export class ConceptRef extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.source = data.source ?? null;
+    this.id = data.id ?? null;
+  }
+
+  toString() {
+    if (this.source && this.id) return `${this.source} ${this.id}`;
+    return this.source ?? this.id ?? '';
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.source != null) obj.source = this.source;
+    if (this.id != null) obj.id = this.id;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new ConceptRef(data);
+  }
+}

package/src/models/concept.js

@@ -10,14 +10,16 @@ export class Concept extends GlossaristModel {
     super();
     this.id = String(data.id ?? data.termid ?? '');
     this.term = data.term ?? null;
+    this.uri = data.uri ?? null;
     this._rawLocalizations = data.localizations ?? {};
     this._cache = {};
 
-    this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related_concepts ?? [], RelatedConcept);
+    this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related ?? data.related_concepts ?? [], RelatedConcept);
     this.domains = _normalizeDomains(data.domains, data.groups);
     this.dates = _mapInstances(data.dates ?? [], ConceptDate);
     this.sources = _mapInstances(data.sources ?? [], ConceptSource);
     this.status = data.status ?? null;
+    this.schemaVersion = data.schemaVersion ?? data.schema_version ?? '3';
     this.raw = data.raw ?? null;
   }
 
@@ -68,6 +70,7 @@ export class Concept extends GlossaristModel {
   toJSON() {
     const obj = { id: this.id };
     if (this.term != null) obj.term = this.term;
+    if (this.uri != null) obj.uri = this.uri;
 
     if (Object.keys(this._rawLocalizations).length > 0) {
       obj.localizations = {};
@@ -84,7 +87,7 @@ export class Concept extends GlossaristModel {
     }
 
     if (this.relatedConcepts.length > 0) {
-      obj.relatedConcepts = this.relatedConcepts.map(rc => rc.toJSON());
+      obj.related = this.relatedConcepts.map(rc => rc.toJSON());
     }
     if (this.domains.length > 0) {
       obj.domains = this.domains.map(d => d.toJSON());
@@ -96,6 +99,7 @@ export class Concept extends GlossaristModel {
       obj.sources = this.sources.map(s => s.toJSON());
     }
     if (this.status != null) obj.status = this.status;
+    obj.schema_version = this.schemaVersion;
     return obj;
   }
 

package/src/models/designation.js

@@ -1,4 +1,8 @@
 import { GlossaristModel } from './base.js';
+import { ConceptSource } from './concept-source.js';
+import { Pronunciation } from './pronunciation.js';
+import { GrammarInfo } from './grammar-info.js';
+import { RelatedConcept } from './related-concept.js';
 
 export class Designation extends GlossaristModel {
   static _registry = new Map();
@@ -18,11 +22,41 @@ export class Designation extends GlossaristModel {
     this.designation = data.designation ?? '';
     this.type = data.type ?? 'expression';
     this.normativeStatus = data.normative_status ?? null;
+    this.absent = data.absent ?? null;
+    this.fieldOfApplication = data.field_of_application ?? null;
+    this.usageInfo = data.usage_info ?? null;
+    this.geographicalArea = data.geographical_area ?? null;
+    this.language = data.language ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.international = data.international ?? null;
+    this.termType = data.term_type ?? null;
+    this.pronunciations = (data.pronunciation ?? []).map(
+      p => p instanceof Pronunciation ? p : new Pronunciation(p)
+    );
+    this.sources = (data.sources ?? []).map(
+      s => s instanceof ConceptSource ? s : new ConceptSource(s)
+    );
+    this.related = (data.related ?? []).map(
+      r => r instanceof RelatedConcept ? r : new RelatedConcept(r)
+    );
   }
 
   toJSON() {
     const obj = { type: this.type, designation: this.designation };
     if (this.normativeStatus != null) obj.normative_status = this.normativeStatus;
+    if (this.absent != null) obj.absent = this.absent;
+    if (this.fieldOfApplication != null) obj.field_of_application = this.fieldOfApplication;
+    if (this.usageInfo != null) obj.usage_info = this.usageInfo;
+    if (this.geographicalArea != null) obj.geographical_area = this.geographicalArea;
+    if (this.language != null) obj.language = this.language;
+    if (this.script != null) obj.script = this.script;
+    if (this.system != null) obj.system = this.system;
+    if (this.international != null) obj.international = this.international;
+    if (this.termType != null) obj.term_type = this.termType;
+    if (this.pronunciations.length > 0) obj.pronunciation = this.pronunciations.map(p => p.toJSON());
+    if (this.sources.length > 0) obj.sources = this.sources.map(s => s.toJSON());
+    if (this.related.length > 0) obj.related = this.related.map(r => r.toJSON());
     return obj;
   }
 
@@ -34,18 +68,16 @@ export class Designation extends GlossaristModel {
 export class Expression extends Designation {
   constructor(data = {}) {
     super(data);
-    this.gender = data.gender ?? null;
-    this.plurality = data.plurality ?? null;
-    this.partOfSpeech = data.part_of_speech ?? null;
-    this.geographicalArea = data.geographical_area ?? null;
+    this.prefix = data.prefix ?? null;
+    this.grammarInfo = (data.grammar_info ?? []).map(
+      g => g instanceof GrammarInfo ? g : new GrammarInfo(g)
+    );
   }
 
   toJSON() {
     const obj = super.toJSON();
-    if (this.gender != null) obj.gender = this.gender;
-    if (this.plurality != null) obj.plurality = this.plurality;
-    if (this.partOfSpeech != null) obj.part_of_speech = this.partOfSpeech;
-    if (this.geographicalArea != null) obj.geographical_area = this.geographicalArea;
+    if (this.prefix != null) obj.prefix = this.prefix;
+    if (this.grammarInfo.length > 0) obj.grammar_info = this.grammarInfo.map(g => g.toJSON());
     return obj;
   }
 
@@ -54,37 +86,60 @@ export class Expression extends Designation {
 
 Designation.register('expression', Expression);
 
-export class Abbreviation extends Designation {
+export class Abbreviation extends Expression {
+  constructor(data = {}) {
+    super(data);
+    this.acronym = data.acronym ?? false;
+    this.initialism = data.initialism ?? false;
+    this.truncation = data.truncation ?? false;
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    if (this.acronym) obj.acronym = true;
+    if (this.initialism) obj.initialism = true;
+    if (this.truncation) obj.truncation = true;
+    return obj;
+  }
+
   static fromJSON(data) { return new Abbreviation(data); }
 }
 
 Designation.register('abbreviation', Abbreviation);
 
 export class Symbol extends Designation {
+  static fromJSON(data) { return new Symbol(data); }
+}
+
+Designation.register('symbol', Symbol);
+
+export class LetterSymbol extends Symbol {
   constructor(data = {}) {
     super(data);
-    this.international = data.international ?? null;
+    this.text = data.text ?? null;
   }
 
   toJSON() {
     const obj = super.toJSON();
-    if (this.international != null) obj.international = this.international;
+    if (this.text != null) obj.text = this.text;
     return obj;
   }
 
-  static fromJSON(data) { return new Symbol(data); }
+  static fromJSON(data) { return new LetterSymbol(data); }
 }
 
-Designation.register('symbol', Symbol);
+Designation.register('letter_symbol', LetterSymbol);
 
-export class GraphicalSymbol extends Designation {
+export class GraphicalSymbol extends Symbol {
   constructor(data = {}) {
     super(data);
+    this.text = data.text ?? null;
     this.image = data.image ?? null;
   }
 
   toJSON() {
     const obj = super.toJSON();
+    if (this.text != null) obj.text = this.text;
     if (this.image != null) obj.image = this.image;
     return obj;
   }

package/src/models/grammar-info.js

@@ -0,0 +1,40 @@
+import { GlossaristModel } from './base.js';
+
+export const GRAMMAR_GENDERS = Object.freeze(['m', 'f', 'n', 'c']);
+export const GRAMMAR_NUMBERS = Object.freeze(['singular', 'dual', 'plural']);
+export const GRAMMAR_PARTS_OF_SPEECH = Object.freeze([
+  'noun', 'verb', 'adj', 'adverb', 'preposition', 'participle',
+]);
+
+export class GrammarInfo extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.gender = data.gender ?? null;
+    this.number = data.number ?? null;
+    this.partOfSpeech = data.part_of_speech ?? data.partOfSpeech ?? null;
+    this.noun = data.noun ?? false;
+    this.verb = data.verb ?? false;
+    this.adj = data.adj ?? false;
+    this.adverb = data.adverb ?? false;
+    this.preposition = data.preposition ?? false;
+    this.participle = data.participle ?? false;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.gender != null) obj.gender = this.gender;
+    if (this.number != null) obj.number = this.number;
+    if (this.partOfSpeech != null) obj.part_of_speech = this.partOfSpeech;
+    if (this.noun) obj.noun = true;
+    if (this.verb) obj.verb = true;
+    if (this.adj) obj.adj = true;
+    if (this.adverb) obj.adverb = true;
+    if (this.preposition) obj.preposition = true;
+    if (this.participle) obj.participle = true;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new GrammarInfo(data);
+  }
+}

package/src/models/index.d.ts

@@ -8,6 +8,7 @@ export class GlossaristModel {
 export class Concept extends GlossaristModel {
   readonly id: string;
   readonly term: string | null;
+  readonly uri: string | null;
   readonly termid: string;
   readonly languages: string[];
   readonly localizations: Record<string, any>;
@@ -17,6 +18,7 @@ export class Concept extends GlossaristModel {
   readonly dates: ConceptDate[];
   readonly sources: ConceptSource[];
   readonly status: string | null;
+  readonly schemaVersion: string | null;
 
   localization(lang: string): LocalizedConcept | undefined;
   primaryDesignation(lang: string): string | null;
@@ -28,14 +30,29 @@ export class Concept extends GlossaristModel {
 
 export class LocalizedConcept extends GlossaristModel {
   readonly languageCode: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly entryStatus: string | null;
+  readonly classification: string | null;
+  readonly reviewType: string | null;
+  readonly domain: string | null;
+  readonly release: string | null;
+  readonly lineageSourceSimilarity: number | null;
+  readonly reviewDate: string | null;
+  readonly reviewDecisionDate: string | null;
+  readonly reviewDecisionEvent: string | null;
+  readonly reviewStatus: string | null;
+  readonly reviewDecision: string | null;
+  readonly reviewDecisionNotes: string | null;
   readonly terms: Designation[];
   readonly definitions: DetailedDefinition[];
   readonly definition: DetailedDefinition[];
-  readonly notes: { content: string }[];
-  readonly examples: { content: string }[];
+  readonly notes: DetailedDefinition[];
+  readonly examples: DetailedDefinition[];
   readonly sources: ConceptSource[];
-  readonly entryStatus: string | null;
-  readonly domain: string | null;
+  readonly dates: ConceptDate[];
+  readonly nonVerbalRep: NonVerbRep[];
+  readonly related: RelatedConcept[];
   readonly primaryDesignation: string | null;
   readonly primaryDefinition: string | null;
   static fromJSON(data: Record<string, unknown>): LocalizedConcept;
@@ -45,35 +62,100 @@ export class Designation extends GlossaristModel {
   readonly designation: string;
   readonly type: string;
   readonly normativeStatus: string | null;
+  readonly absent: boolean | null;
+  readonly fieldOfApplication: string | null;
+  readonly usageInfo: string | null;
+  readonly geographicalArea: string | null;
+  readonly language: string | null;
+  readonly script: string | null;
+  readonly system: string | null;
+  readonly international: boolean | null;
+  readonly termType: string | null;
+  readonly pronunciations: Pronunciation[];
+  readonly sources: ConceptSource[];
+  readonly related: RelatedConcept[];
   static register(type: string, cls: typeof Designation): void;
   static fromData(data: Record<string, unknown>): Designation;
   static fromJSON(data: Record<string, unknown>): Designation;
 }
 
 export class Expression extends Designation {
+  readonly prefix: string | null;
+  readonly grammarInfo: GrammarInfo[];
+}
+
+export class Abbreviation extends Expression {
+  readonly acronym: boolean;
+  readonly initialism: boolean;
+  readonly truncation: boolean;
+}
+
+export class Symbol extends Designation {}
+
+export class LetterSymbol extends Symbol {
+  readonly text: string | null;
+}
+
+export class GraphicalSymbol extends Symbol {
+  readonly text: string | null;
+  readonly image: string | null;
+}
+
+export const GRAMMAR_GENDERS: readonly string[];
+export const GRAMMAR_NUMBERS: readonly string[];
+export const GRAMMAR_PARTS_OF_SPEECH: readonly string[];
+
+export class GrammarInfo extends GlossaristModel {
   readonly gender: string | null;
-  readonly plurality: string | null;
+  readonly number: string | null;
   readonly partOfSpeech: string | null;
-  readonly geographicalArea: string | null;
+  readonly noun: boolean;
+  readonly verb: boolean;
+  readonly adj: boolean;
+  readonly adverb: boolean;
+  readonly preposition: boolean;
+  readonly participle: boolean;
 }
 
-export class Abbreviation extends Designation {}
-export class Symbol extends Designation {
-  readonly international: string | null;
+export class Pronunciation extends GlossaristModel {
+  readonly content: string | null;
+  readonly language: string | null;
+  readonly script: string | null;
+  readonly country: string | null;
+  readonly system: string | null;
 }
-export class GraphicalSymbol extends Designation {
-  readonly image: string | null;
+
+export class Locality extends GlossaristModel {
+  readonly type: string | null;
+  readonly referenceFrom: string | null;
+  readonly referenceTo: string | null;
 }
 
 export class Citation extends GlossaristModel {
-  readonly source: string | Record<string, unknown> | null;
-  readonly ref: string | null;
-  readonly id: string | null;
-  readonly version: string | null;
-  readonly clause: string | null;
+  readonly ref: Citation.Ref | null;
+  readonly locality: Locality | null;
   readonly link: string | null;
-  readonly isStructured: boolean;
+  readonly original: string | null;
+  readonly customLocality: unknown;
   toString(): string;
+  static fromJSON(data: Record<string, unknown>): Citation;
+}
+
+export namespace Citation {
+  class Ref extends GlossaristModel {
+    readonly source: string | null;
+    readonly id: string | null;
+    readonly version: string | null;
+    toString(): string;
+    static fromJSON(data: Record<string, unknown>): Ref;
+  }
+}
+
+export class ConceptRef extends GlossaristModel {
+  readonly source: string | null;
+  readonly id: string | null;
+  toString(): string;
+  static fromJSON(data: Record<string, unknown>): ConceptRef;
 }
 
 export class ConceptSource extends GlossaristModel {
@@ -87,7 +169,7 @@ export const RELATIONSHIP_TYPES: readonly string[];
 export class RelatedConcept extends GlossaristModel {
   readonly type: string;
   readonly content: string | null;
-  readonly ref: Citation | null;
+  readonly ref: ConceptRef | null;
 }
 
 export class ConceptReference extends GlossaristModel {
@@ -110,14 +192,14 @@ export class ConceptDate extends GlossaristModel {
 
 export class DetailedDefinition extends GlossaristModel {
   readonly content: string;
-  readonly sources: Citation[];
+  readonly sources: ConceptSource[];
 }
 
 export class NonVerbRep extends GlossaristModel {
-  readonly image: string | null;
-  readonly table: string | null;
-  readonly formula: string | null;
-  readonly sources: Citation[];
+  readonly type: string | null;
+  readonly ref: string | null;
+  readonly text: string | null;
+  readonly sources: ConceptSource[];
 }
 
 export class GcrStatistics extends GlossaristModel {

package/src/models/index.js

@@ -1,13 +1,17 @@
 export { GlossaristModel } from './base.js';
 export { Concept } from './concept.js';
 export { LocalizedConcept } from './localized-concept.js';
-export { Designation, Expression, Abbreviation, Symbol, GraphicalSymbol } from './designation.js';
+export { Designation, Expression, Abbreviation, Symbol, LetterSymbol, GraphicalSymbol } from './designation.js';
 export { Citation } from './citation.js';
+export { ConceptRef } from './concept-ref.js';
 export { ConceptSource } from './concept-source.js';
 export { RelatedConcept, RELATIONSHIP_TYPES } from './related-concept.js';
 export { ConceptReference } from './concept-reference.js';
 export { ConceptDate, DATE_TYPES } from './concept-date.js';
 export { DetailedDefinition } from './detailed-definition.js';
 export { NonVerbRep } from './non-verb-rep.js';
+export { Pronunciation } from './pronunciation.js';
+export { GrammarInfo, GRAMMAR_GENDERS, GRAMMAR_NUMBERS, GRAMMAR_PARTS_OF_SPEECH } from './grammar-info.js';
+export { Locality } from './locality.js';
 export { GcrMetadata } from './gcr-metadata.js';
-export { GcrStatistics } from './gcr-statistics.js';;
+export { GcrStatistics } from './gcr-statistics.js';

package/src/models/locality.js

@@ -0,0 +1,22 @@
+import { GlossaristModel } from './base.js';
+
+export class Locality extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.type = data.type ?? null;
+    this.referenceFrom = data.reference_from ?? data.referenceFrom ?? null;
+    this.referenceTo = data.reference_to ?? data.referenceTo ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.type != null) obj.type = this.type;
+    if (this.referenceFrom != null) obj.reference_from = this.referenceFrom;
+    if (this.referenceTo != null) obj.reference_to = this.referenceTo;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new Locality(data);
+  }
+}

package/src/models/localized-concept.js

@@ -2,24 +2,47 @@ import { GlossaristModel } from './base.js';
 import { Designation } from './designation.js';
 import { DetailedDefinition } from './detailed-definition.js';
 import { ConceptSource } from './concept-source.js';
+import { ConceptDate } from './concept-date.js';
+import { NonVerbRep } from './non-verb-rep.js';
+import { RelatedConcept } from './related-concept.js';
 
 export class LocalizedConcept extends GlossaristModel {
   constructor(data = {}) {
     super();
     this.languageCode = data.language_code ?? data.languageCode ?? null;
-    this._rawTerms = data.terms ?? [];
-    this._rawDefinition = data.definition ?? [];
-    this._rawSources = data.sources ?? [];
-    this.notes = data.notes ?? [];
-    this.examples = data.examples ?? [];
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
     this.entryStatus = data.entry_status ?? data.entryStatus ?? null;
-    this.reviewType = data.review_type ?? data.reviewType ?? null;
     this.classification = data.classification ?? null;
+    this.reviewType = data.review_type ?? data.reviewType ?? null;
     this.domain = data.domain ?? null;
+    this.release = data.release ?? null;
+    this.lineageSourceSimilarity = data.lineage_source_similarity ?? data.lineageSourceSimilarity ?? null;
+
+    this.reviewDate = data.review_date ?? data.reviewDate ?? null;
+    this.reviewDecisionDate = data.review_decision_date ?? data.reviewDecisionDate ?? null;
+    this.reviewDecisionEvent = data.review_decision_event ?? data.reviewDecisionEvent ?? null;
+    this.reviewStatus = data.review_status ?? data.reviewStatus ?? null;
+    this.reviewDecision = data.review_decision ?? data.reviewDecision ?? null;
+    this.reviewDecisionNotes = data.review_decision_notes ?? data.reviewDecisionNotes ?? null;
+
+    this._rawTerms = data.terms ?? [];
+    this._rawDefinition = data.definition ?? [];
+    this._rawSources = data.sources ?? [];
+    this._rawNotes = data.notes ?? [];
+    this._rawExamples = data.examples ?? [];
+    this._rawDates = data.dates ?? [];
+    this._rawNonVerbal = data.non_verbal_rep ?? data.non_verb ?? [];
+    this._rawRelated = data.related ?? [];
 
     this._terms = null;
     this._definitions = null;
     this._sources = null;
+    this._notes = null;
+    this._examples = null;
+    this._dates = null;
+    this._nonVerbal = null;
+    this._related = null;
   }
 
   get terms() {
@@ -51,6 +74,51 @@ export class LocalizedConcept extends GlossaristModel {
     return this._sources;
   }
 
+  get notes() {
+    if (this._notes === null) {
+      this._notes = this._rawNotes.map(
+        n => n instanceof DetailedDefinition ? n : new DetailedDefinition(n)
+      );
+    }
+    return this._notes;
+  }
+
+  get examples() {
+    if (this._examples === null) {
+      this._examples = this._rawExamples.map(
+        e => e instanceof DetailedDefinition ? e : new DetailedDefinition(e)
+      );
+    }
+    return this._examples;
+  }
+
+  get dates() {
+    if (this._dates === null) {
+      this._dates = this._rawDates.map(
+        d => d instanceof ConceptDate ? d : new ConceptDate(d)
+      );
+    }
+    return this._dates;
+  }
+
+  get nonVerbalRep() {
+    if (this._nonVerbal === null) {
+      this._nonVerbal = this._rawNonVerbal.map(
+        n => n instanceof NonVerbRep ? n : new NonVerbRep(n)
+      );
+    }
+    return this._nonVerbal;
+  }
+
+  get related() {
+    if (this._related === null) {
+      this._related = this._rawRelated.map(
+        r => r instanceof RelatedConcept ? r : new RelatedConcept(r)
+      );
+    }
+    return this._related;
+  }
+
   get primaryDesignation() {
     return this.terms[0]?.designation ?? null;
   }
@@ -62,6 +130,21 @@ export class LocalizedConcept extends GlossaristModel {
   toJSON() {
     const obj = {};
     if (this.languageCode) obj.language_code = this.languageCode;
+    if (this.script) obj.script = this.script;
+    if (this.system) obj.system = this.system;
+    if (this.entryStatus) obj.entry_status = this.entryStatus;
+    if (this.classification) obj.classification = this.classification;
+    if (this.reviewType) obj.review_type = this.reviewType;
+    if (this.domain) obj.domain = this.domain;
+    if (this.release) obj.release = this.release;
+    if (this.lineageSourceSimilarity != null) obj.lineage_source_similarity = this.lineageSourceSimilarity;
+
+    if (this.reviewDate) obj.review_date = this.reviewDate;
+    if (this.reviewDecisionDate) obj.review_decision_date = this.reviewDecisionDate;
+    if (this.reviewDecisionEvent) obj.review_decision_event = this.reviewDecisionEvent;
+    if (this.reviewStatus) obj.review_status = this.reviewStatus;
+    if (this.reviewDecision) obj.review_decision = this.reviewDecision;
+    if (this.reviewDecisionNotes) obj.review_decision_notes = this.reviewDecisionNotes;
 
     const terms = this._terms ?? this._rawTerms;
     if (terms.length > 0) {
@@ -73,18 +156,36 @@ export class LocalizedConcept extends GlossaristModel {
       obj.definition = defs.map(d => (typeof d.toJSON === 'function') ? d.toJSON() : d);
     }
 
-    if (this.notes.length > 0) obj.notes = this.notes;
-    if (this.examples.length > 0) obj.examples = this.examples;
+    const notes = this._notes ?? (this._rawNotes.length > 0 ? this._rawNotes : []);
+    if (notes.length > 0) {
+      obj.notes = notes.map(n => (typeof n.toJSON === 'function') ? n.toJSON() : n);
+    }
+
+    const examples = this._examples ?? (this._rawExamples.length > 0 ? this._rawExamples : []);
+    if (examples.length > 0) {
+      obj.examples = examples.map(e => (typeof e.toJSON === 'function') ? e.toJSON() : e);
+    }
 
     const sources = this._sources ?? (this._rawSources.length > 0 ? this._rawSources : []);
     if (sources.length > 0) {
       obj.sources = sources.map(s => (typeof s.toJSON === 'function') ? s.toJSON() : s);
     }
 
-    if (this.entryStatus != null) obj.entry_status = this.entryStatus;
-    if (this.reviewType != null) obj.review_type = this.reviewType;
-    if (this.classification != null) obj.classification = this.classification;
-    if (this.domain != null) obj.domain = this.domain;
+    const dates = this._dates ?? (this._rawDates.length > 0 ? this._rawDates : []);
+    if (dates.length > 0) {
+      obj.dates = dates.map(d => (typeof d.toJSON === 'function') ? d.toJSON() : d);
+    }
+
+    const nonVerbal = this._nonVerbal ?? (this._rawNonVerbal.length > 0 ? this._rawNonVerbal : []);
+    if (nonVerbal.length > 0) {
+      obj.non_verbal_rep = nonVerbal.map(n => (typeof n.toJSON === 'function') ? n.toJSON() : n);
+    }
+
+    const related = this._related ?? (this._rawRelated.length > 0 ? this._rawRelated : []);
+    if (related.length > 0) {
+      obj.related = related.map(r => (typeof r.toJSON === 'function') ? r.toJSON() : r);
+    }
+
     return obj;
   }
 

package/src/models/non-verb-rep.js

@@ -1,22 +1,22 @@
 import { GlossaristModel } from './base.js';
-import { Citation } from './citation.js';
+import { ConceptSource } from './concept-source.js';
 
 export class NonVerbRep extends GlossaristModel {
   constructor(data = {}) {
     super();
-    this.image = data.image ?? null;
-    this.table = data.table ?? null;
-    this.formula = data.formula ?? null;
+    this.type = data.type ?? null;
+    this.ref = data.ref ?? null;
+    this.text = data.text ?? null;
     this.sources = (data.sources ?? []).map(
-      s => s instanceof Citation ? s : new Citation(s)
+      s => s instanceof ConceptSource ? s : new ConceptSource(s)
     );
   }
 
   toJSON() {
     const obj = {};
-    if (this.image != null) obj.image = this.image;
-    if (this.table != null) obj.table = this.table;
-    if (this.formula != null) obj.formula = this.formula;
+    if (this.type != null) obj.type = this.type;
+    if (this.ref != null) obj.ref = this.ref;
+    if (this.text != null) obj.text = this.text;
     if (this.sources.length > 0) obj.sources = this.sources.map(s => s.toJSON());
     return obj;
   }

package/src/models/pronunciation.js

@@ -0,0 +1,26 @@
+import { GlossaristModel } from './base.js';
+
+export class Pronunciation extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.content = data.content ?? null;
+    this.language = data.language ?? null;
+    this.script = data.script ?? null;
+    this.system = data.system ?? null;
+    this.country = data.country ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.content != null) obj.content = this.content;
+    if (this.language != null) obj.language = this.language;
+    if (this.script != null) obj.script = this.script;
+    if (this.system != null) obj.system = this.system;
+    if (this.country != null) obj.country = this.country;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new Pronunciation(data);
+  }
+}

package/src/models/related-concept.js

@@ -1,19 +1,38 @@
 import { GlossaristModel } from './base.js';
-import { Citation } from './citation.js';
+import { ConceptRef } from './concept-ref.js';
 
 export const RELATIONSHIP_TYPES = Object.freeze([
-  'supersedes', 'superseded_by', 'extends', 'extended_by',
-  'narrower', 'broader', 'equivalent', 'compare', 'contrast',
-  'derived', 'deprecated', 'related',
+  // Lifecycle (ISO 10241-1)
+  'deprecates', 'supersedes', 'superseded_by',
+  // Hierarchical (SKOS)
+  'broader', 'narrower',
+  // ISO 25964 generic
+  'broader_generic', 'narrower_generic',
+  // ISO 25964 partitive
+  'broader_partitive', 'narrower_partitive',
+  // ISO 25964 instantial
+  'broader_instantial', 'narrower_instantial',
+  // SKOS mapping
+  'equivalent', 'close_match', 'broad_match', 'narrow_match', 'related_match',
+  // Associative (ISO 10241-1 / ISO 25964)
+  'see', 'related_concept', 'related_concept_broader', 'related_concept_narrower',
+  // Comparative (ISO 10241-1)
+  'compare', 'contrast',
+  // Spatiotemporal (ISO 25964 / TBX)
+  'sequentially_related_concept', 'spatially_related_concept', 'temporally_related_concept',
+  // Lexical (ISO 12620 / TBX)
+  'homograph', 'false_friend',
+  // Designation-level
+  'abbreviated_form_for', 'short_form_for',
 ]);
 
 export class RelatedConcept extends GlossaristModel {
   constructor(data = {}) {
     super();
-    this.type = data.type ?? 'related';
+    this.type = data.type ?? 'see';
     this.content = data.content ?? null;
     this.ref = data.ref
-      ? (data.ref instanceof Citation ? data.ref : new Citation(data.ref))
+      ? (data.ref instanceof ConceptRef ? data.ref : new ConceptRef(data.ref))
       : null;
   }
 

package/src/reference-resolver.js

@@ -1,3 +1,5 @@
+import { ConceptRef } from './models/concept-ref.js';
+
 export class Reference {
   constructor(type, target, relationship, source) {
     this.type = type;
@@ -7,12 +9,20 @@ export class Reference {
   }
 }
 
+function refTarget(rc) {
+  if (rc.content) return rc.content;
+  if (rc.ref instanceof ConceptRef) {
+    return rc.ref.id ?? rc.ref.source ?? '';
+  }
+  return '';
+}
+
 export class ReferenceResolver {
   extractReferences(concept) {
     const refs = [];
 
     for (const rc of concept.relatedConcepts) {
-      const target = rc.content ?? rc.ref?.toString() ?? '';
+      const target = refTarget(rc);
       if (target) {
         refs.push(new Reference('concept', target, rc.type, 'relatedConcepts'));
       }

package/src/validators/index.js

@@ -4,15 +4,40 @@ export { ValidationResult } from './validation-result.js';
 export { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
 export { RegisterValidator } from './register-validator.js';
 export { GcrValidator } from './gcr-validator.js';
+export {
+  RefShapeRule,
+  LocalityCompletenessRule,
+  LocalizationConsistencyRule,
+  SchemaVersionRule,
+  DomainRefRule,
+  UuidFormatRule,
+  SourceUrnFormatRule,
+} from './v3-rules.js';
 
 import { ConceptValidator, LanguageCodeRule, DesignationTypeRule, EntryStatusRule } from './concept-validator.js';
 import { RegisterValidator } from './register-validator.js';
 import { GcrValidator } from './gcr-validator.js';
+import {
+  RefShapeRule,
+  LocalityCompletenessRule,
+  LocalizationConsistencyRule,
+  SchemaVersionRule,
+  DomainRefRule,
+  UuidFormatRule,
+  SourceUrnFormatRule,
+} from './v3-rules.js';
 
 const _default = new ConceptValidator()
   .addRule(new LanguageCodeRule())
   .addRule(new DesignationTypeRule())
-  .addRule(new EntryStatusRule());
+  .addRule(new EntryStatusRule())
+  .addRule(new RefShapeRule())
+  .addRule(new LocalityCompletenessRule())
+  .addRule(new LocalizationConsistencyRule())
+  .addRule(new SchemaVersionRule())
+  .addRule(new DomainRefRule())
+  .addRule(new UuidFormatRule())
+  .addRule(new SourceUrnFormatRule());
 
 export function validateConcept(concept) {
   return _default.validate(concept);

package/src/validators/v3-rules.js

@@ -0,0 +1,216 @@
+import { ValidationRule } from './validation-rule.js';
+
+/**
+ * GLS-305: Enforces Citation#ref is a proper Citation.Ref object
+ * and RelatedConcept#ref has at least source or id.
+ */
+export class RefShapeRule extends ValidationRule {
+  constructor() { super('ref-shape'); }
+
+  validate(value, path) {
+    const errors = [];
+
+    // Check sources in localizations
+    const localizations = value.localizations || {};
+    let sourceIdx = 0;
+    for (const [lang, lc] of Object.entries(localizations)) {
+      const sources = lc.sources || [];
+      for (let i = 0; i < sources.length; i++) {
+        sourceIdx++;
+        const origin = sources[i].origin;
+        if (!origin) continue;
+
+        const ref = origin.ref;
+        if (!ref) {
+          errors.push(...this.error(
+            `${path}localizations.${lang}.sources[${i}].origin.ref`,
+            `source ${sourceIdx} origin has nil ref (expected Citation.Ref hash)`,
+          ));
+        } else if (!ref.source && !ref.id) {
+          errors.push(...this.error(
+            `${path}localizations.${lang}.sources[${i}].origin.ref`,
+            `source ${sourceIdx} origin.ref has neither source nor id`,
+          ));
+        }
+      }
+    }
+
+    // Check related concepts
+    const related = value.related || [];
+    for (let i = 0; i < related.length; i++) {
+      const ref = related[i].ref;
+      if (!ref) continue;
+      if (!ref.source && !ref.id) {
+        errors.push(...this.error(
+          `${path}related[${i}].ref`,
+          `related concept ${i + 1} has empty ref (no source or id)`,
+        ));
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-308: Locality must have type and reference_from when present.
+ */
+export class LocalityCompletenessRule extends ValidationRule {
+  constructor() { super('locality-completeness', 'warning'); }
+
+  validate(value, path) {
+    const errors = [];
+    const localizations = value.localizations || {};
+
+    for (const [lang, lc] of Object.entries(localizations)) {
+      const sources = lc.sources || [];
+      for (let i = 0; i < sources.length; i++) {
+        const origin = sources[i].origin;
+        if (!origin || !origin.locality) continue;
+
+        const loc = origin.locality;
+        if (!loc.type) {
+          errors.push(...this.error(
+            `${path}localizations.${lang}.sources[${i}].origin.locality.type`,
+            `source locality has no type`,
+          ));
+        }
+        if (!loc.reference_from) {
+          errors.push(...this.error(
+            `${path}localizations.${lang}.sources[${i}].origin.locality.reference_from`,
+            `source locality has no reference_from`,
+          ));
+        }
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-017: Localization map consistency.
+ */
+export class LocalizationConsistencyRule extends ValidationRule {
+  constructor() { super('localization-consistency'); }
+
+  validate(value, path) {
+    const errors = [];
+    const localizations = value.localizations || {};
+    const data = value.raw?.data || value;
+
+    const declaredLangs = data.localized_concepts
+      ? Object.keys(data.localized_concepts)
+      : Object.keys(localizations);
+
+    for (const lang of declaredLangs) {
+      if (!localizations[lang]) {
+        errors.push(...this.error(
+          `${path}localizations.${lang}`,
+          `localized_concepts map has '${lang}' but no localization loaded`,
+        ));
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-010: Schema version should be 3.
+ */
+export class SchemaVersionRule extends ValidationRule {
+  constructor() { super('schema-version', 'warning'); }
+
+  validate(value, path) {
+    const errors = [];
+    const version = value.schemaVersion || value.schema_version;
+
+    if (version && String(version) !== '3') {
+      errors.push(...this.error(
+        `${path}schema_version`,
+        `schema_version is '${version}', expected '3'`,
+      ));
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-309: Domain references need concept_id or urn.
+ */
+export class DomainRefRule extends ValidationRule {
+  constructor() { super('domain-ref', 'warning'); }
+
+  validate(value, path) {
+    const errors = [];
+    const domains = value.domains || [];
+
+    for (let i = 0; i < domains.length; i++) {
+      const domain = domains[i];
+      if (!domain.concept_id && !domain.urn) {
+        errors.push(...this.error(
+          `${path}domains[${i}]`,
+          `domain ${i + 1} has neither concept_id nor urn`,
+        ));
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-016: UUID format validation.
+ */
+export class UuidFormatRule extends ValidationRule {
+  constructor() { super('uuid-format'); }
+
+  validate(value, path) {
+    const errors = [];
+    const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    const id = value.id || value.uuid;
+
+    if (id && !UUID_RE.test(String(id))) {
+      // Only flag if it looks like it's supposed to be a UUID
+      if (String(id).includes('-') && String(id).length > 20) {
+        errors.push(...this.error(
+          `${path}id`,
+          `concept ID '${id}' is not valid UUID format`,
+        ));
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * GLS-310: URN format validation for sources.
+ */
+export class SourceUrnFormatRule extends ValidationRule {
+  constructor() { super('source-urn-format', 'warning'); }
+
+  validate(value, path) {
+    const errors = [];
+    const URN_RE = /^urn:[a-z0-9][a-z0-9-]{0,31}:[a-z0-9()+,\-.:=@;$_!*'%/?#]+$/i;
+
+    const localizations = value.localizations || {};
+    for (const [lang, lc] of Object.entries(localizations)) {
+      const sources = lc.sources || [];
+      for (let i = 0; i < sources.length; i++) {
+        const source = sources[i].origin?.ref?.source;
+        if (!source || !source.startsWith('urn:')) continue;
+        if (!URN_RE.test(source)) {
+          errors.push(...this.error(
+            `${path}localizations.${lang}.sources[${i}].origin.ref.source`,
+            `malformed URN '${source}'`,
+          ));
+        }
+      }
+    }
+
+    return errors;
+  }
+}