glossarist 0.3.8 → 0.4.1

package/package.json

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

package/src/concept-collection.js

@@ -86,22 +86,14 @@ export class ConceptCollection {
         for (const t of lc.terms) {
           if ((t.designation ?? '').toLowerCase().includes(q)) return true;
         }
-        if (this._searchDefs(lc.definitions, q)) return true;
-        if (this._searchDefs(lc.notes, q)) return true;
-        if (this._searchDefs(lc.examples, q)) return true;
-        if (this._searchDefs(lc.annotations, q)) return true;
+      }
+      for (const { text } of c.walkTexts()) {
+        if (text.toLowerCase().includes(q)) return true;
       }
       return false;
     }));
   }
 
-  _searchDefs(arr, q) {
-    for (const d of arr) {
-      if ((d.content ?? '').toLowerCase().includes(q)) return true;
-    }
-    return false;
-  }
-
   allLanguages() {
     const set = new Set();
     for (const c of this[_items]) {

package/src/concept-parser.js

@@ -3,7 +3,7 @@ import { Concept } from './models/concept.js';
 import { RelatedConcept } from './models/related-concept.js';
 import { InvalidInputError, YamlParseError } from './errors.js';
 
-const STRUCTURAL_KEYS = new Set(['termid', 'term']);
+const STRUCTURAL_KEYS = new Set(['termid', 'term', 'figures', 'tables', 'formulas']);
 
 export class ConceptParser {
   parse(raw, context) {
@@ -51,6 +51,9 @@ export class ConceptParser {
       id: String(doc.termid),
       term: doc.term || null,
       localizations,
+      figures: doc.figures,
+      tables: doc.tables,
+      formulas: doc.formulas,
       raw: doc,
     });
   }
@@ -76,6 +79,9 @@ export class ConceptParser {
       groups: mc.data.groups,
       dates: mc.dates ?? mc.data?.dates,
       sources: mc.sources ?? mc.data?.sources,
+      figures: mc.data?.figures,
+      tables: mc.data?.tables,
+      formulas: mc.data?.formulas,
       status: mc.status,
       schemaVersion: mc.schema_version,
       raw: mc,

package/src/dataset-asset.js

@@ -12,6 +12,9 @@
 const DATASET_ASSETS = Object.freeze([
   { path: 'bibliography.yaml', type: 'file' },
   { path: 'images', type: 'directory' },
+  { path: 'figures', type: 'directory' },
+  { path: 'tables', type: 'directory' },
+  { path: 'formulas', type: 'directory' },
 ]);
 
 const FILE_ASSETS = Object.freeze(

package/src/entity-directory.js

@@ -0,0 +1,43 @@
+const ENTITY_DIRECTORIES = Object.freeze(new Map([
+  ['figure', 'figures'],
+  ['table', 'tables'],
+  ['formula', 'formulas'],
+]));
+
+const ENTITY_TYPES = Object.freeze([...ENTITY_DIRECTORIES.keys()]);
+
+function entityDir(type) {
+  const dir = ENTITY_DIRECTORIES.get(type);
+  if (!dir) throw new RangeError(`Unknown entity type: ${type}`);
+  return dir;
+}
+
+function entityPath(type, id) {
+  return `${entityDir(type)}/${id}.yaml`;
+}
+
+function isKnownEntityType(type) {
+  return ENTITY_DIRECTORIES.has(type);
+}
+
+function parseEntityPath(zipPath) {
+  for (const [type, dir] of ENTITY_DIRECTORIES) {
+    const prefix = `${dir}/`;
+    if (!zipPath.startsWith(prefix)) continue;
+    const filename = zipPath.slice(prefix.length);
+    if (!filename.endsWith('.yaml')) continue;
+    const id = filename.slice(0, -'.yaml'.length);
+    if (!id) continue;
+    return { type, id };
+  }
+  return null;
+}
+
+export {
+  ENTITY_DIRECTORIES,
+  ENTITY_TYPES,
+  entityDir,
+  entityPath,
+  isKnownEntityType,
+  parseEntityPath,
+};

package/src/gcr-reader.js

@@ -6,6 +6,9 @@ import { COMPILED_FORMATS, parseCompiledPath, compiledPath } from './compiled-fo
 import { DATASET_ASSETS, findFileAsset, findDirectoryAssetPath } from './dataset-asset.js';
 import { GcrMetadata } from './models/gcr-metadata.js';
 import { naturalSort } from './sort.js';
+import { NonVerbalEntity } from './models/non-verbal-entity.js';
+import { BibliographyData } from './models/bibliography-data.js';
+import { entityDir, entityPath, ENTITY_TYPES, parseEntityPath } from './entity-directory.js';
 
 export { naturalSort } from './sort.js';
 
@@ -34,7 +37,7 @@ const BASE64_RE = /^[A-Za-z0-9+/]{100,}={0,2}$/;
  * @property {Term[]} terms - term designations
  * @property {Definition[]} [definition] - definition content
  * @property {{ content: string }[]} [notes] - editorial notes
- * @property {{ content: string }[]} [examples] - usage examples
+ * @property {Array<{ content: string, examples?: object[], sources?: object[] }>} [examples] - usage examples (may themselves nest examples)
  * @property {Source[]} [sources] - bibliographic sources
  * @property {string} [entry_status] - e.g. 'valid', 'draft'
  * @property {string} [normative_status] - e.g. 'preferred', 'admitted'
@@ -283,12 +286,13 @@ export class GcrPackage {
   }
 
   /**
-   * Read bibliography.yaml from the package as a string (raw YAML).
-   * @returns {Promise<string | null>}
+   * Read and parse bibliography.yaml from the package as a BibliographyData instance.
+   * @returns {Promise<BibliographyData | null>}
    */
   async bibliography() {
-    const fileAsset = DATASET_ASSETS.find((a) => a.type === 'file' && a.path === 'bibliography.yaml');
-    return fileAsset ? this._readText(fileAsset.path) : null;
+    const raw = await this._readText('bibliography.yaml');
+    if (raw === null) return null;
+    return BibliographyData.fromYAML(raw);
   }
 
   /**
@@ -403,6 +407,50 @@ export class GcrPackage {
   async _readText(filePath) {
     return this.readText(filePath);
   }
+
+  // --- Non-verbal entity directories (figures/, tables/, formulas/) ---
+
+  async entityIds(type) {
+    const prefix = `${entityDir(type)}/`;
+    const ids = [];
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir && relativePath.startsWith(prefix) && relativePath.endsWith('.yaml')) {
+        ids.push(relativePath.slice(prefix.length, -'.yaml'.length));
+      }
+    });
+    return ids.sort(naturalSort);
+  }
+
+  async entity(type, id) {
+    const raw = await this.readText(entityPath(type, id));
+    if (raw === null) return null;
+    const yamlData = yaml.load(raw);
+    return NonVerbalEntity.fromData({ ...yamlData, type });
+  }
+
+  async eachEntity(type, callback) {
+    for (const id of await this.entityIds(type)) {
+      const entity = await this.entity(type, id);
+      if (entity) await callback(entity, id);
+    }
+  }
+
+  async allEntities(type) {
+    const entities = [];
+    await this.eachEntity(type, (e) => { entities.push(e); });
+    return entities;
+  }
+
+  async entityTypes() {
+    const seen = new Set();
+    this._zip.forEach((relativePath, entry) => {
+      if (!entry.dir) {
+        const parsed = parseEntityPath(relativePath);
+        if (parsed) seen.add(parsed.type);
+      }
+    });
+    return ENTITY_TYPES.filter((t) => seen.has(t));
+  }
 }
 
 // --- Concept YAML parsing ---

package/src/gcr-writer.js

@@ -38,7 +38,9 @@ export class GcrWriter {
     }
 
     if (options.bibliography) {
-      zip.file('bibliography.yaml', options.bibliography);
+      const bib = options.bibliography;
+      const yamlStr = bib.toYAML ? bib.toYAML() : String(bib);
+      zip.file('bibliography.yaml', yamlStr);
     }
 
     if (options.images) {

package/src/index.d.ts

@@ -1,12 +1,18 @@
 // Models
 export {
   GlossaristModel,
+  RegistrableModel,
   Concept, LocalizedConcept,
-  Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
-  Citation, ConceptRef, ConceptSource, RelatedConcept, ConceptDate,
-  DetailedDefinition, NonVerbRep,
+  Designation, Expression, Abbreviation, Symbol, LetterSymbol, GraphicalSymbol,
+  Citation, ConceptRef, ConceptSource, RelatedConcept,
+  DesignationRelationship, ConceptReference, ConceptDate,
+  DetailedDefinition, NonVerbRep, NON_VERBAL_TYPES,
+  NonVerbalEntity, SharedNonVerbalEntity,
+  Figure, FigureImage, Table, Formula,
+  NonVerbalReference, FigureReference, TableReference, FormulaReference,
+  BibliographyEntry, BibliographyData,
   GcrMetadata, GcrStatistics,
-  RELATIONSHIP_TYPES, DATE_TYPES,
+  RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index';
 
 // GCR reader
@@ -26,16 +32,27 @@ export { ConceptCollection } from './concept-collection';
 export { ManagedConceptCollection } from './managed-concept-collection';
 
 // Validators
-export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index';
+export {
+  validateConcept, validateRegister, validateGcrPackage,
+  createConceptValidator,
+  ValidationError, ValidationRule, ValidationResult,
+  RegisterValidator, GcrValidator,
+  NonVerbalRefIntegrityRule, OrphanedImagesRule,
+} from './validators/index';
+export { AssetIndex } from './validators/asset-index';
 
 // UUID
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
 
 // Reference resolution
-export { ReferenceResolver, Reference, referenceResolver } from './reference-resolver';
+export {
+  ReferenceResolver, Reference, referenceResolver,
+  resolveBibliographyRecord, findNonVerbalEntity,
+} from './reference-resolver';
 
 export type MentionParseResult = {
-  kind: 'cite-ref' | 'urn-ref' | 'numeric' | 'designation' | 'unresolved';
+  kind: 'cite-ref' | 'urn-ref' | 'fig-ref' | 'table-ref' | 'formula-ref'
+      | 'numeric' | 'designation' | 'unresolved';
   key?: string;
   uri?: string;
   label?: string | null;
@@ -45,6 +62,14 @@ export type MentionParseResult = {
 
 export function parseMention(raw: string): MentionParseResult;
 
+export function fetchLocalizedString(
+  hash: Record<string, string> | null,
+  lang: string,
+  fallback?: string,
+): string | null;
+export function localizedStringIsEmpty(hash: Record<string, string> | null): boolean;
+export function localizedStringIsPresent(hash: Record<string, string> | null): boolean;
+
 // V1 support
 export { V1Reader, migrateV1ToV2 } from './v1-reader';
 
@@ -66,3 +91,11 @@ export const DIRECTORY_ASSETS: readonly { path: string; type: string }[];
 export function findFileAsset(path: string): { path: string; type: string } | undefined;
 export function findDirectoryAssetPath(zipPath: string): { path: string; type: string } | undefined;
 export function isDatasetAssetPath(zipPath: string): boolean;
+
+// Entity directory registry
+export const ENTITY_DIRECTORIES: ReadonlyMap<string, string>;
+export const ENTITY_TYPES: readonly string[];
+export function entityDir(type: string): string;
+export function entityPath(type: string, id: string): string;
+export function isKnownEntityType(type: string): boolean;
+export function parseEntityPath(zipPath: string): { type: string; id: string } | null;

package/src/index.js

@@ -7,7 +7,7 @@ export { ConceptCollection } from './concept-collection.js';
 export { ManagedConceptCollection } from './managed-concept-collection.js';
 export { validateConcept, validateRegister, validateGcrPackage, createConceptValidator, ValidationError, ValidationRule, ValidationResult, RegisterValidator, GcrValidator } from './validators/index.js';
 export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid.js';
-export { ReferenceResolver, Reference, referenceResolver, resolveBibliographyRecord } from './reference-resolver.js';
+export { ReferenceResolver, Reference, referenceResolver, resolveBibliographyRecord, findNonVerbalEntity } from './reference-resolver.js';
 export { parseMention } from './reference-mention.js';
 export { ReferenceClassifier } from './render-classification.js';
 export { V1Reader, migrateV1ToV2 } from './v1-reader.js';
@@ -30,12 +30,29 @@ export {
 
 export {
   GlossaristModel,
+  RegistrableModel,
   Register, Section,
   REGISTER_STATUSES, ORDERING_METHODS,
   Concept, LocalizedConcept,
   Designation, Expression, Abbreviation, Symbol, GraphicalSymbol,
   Citation, ConceptRef, ConceptSource, RelatedConcept, DesignationRelationship, ConceptReference, ConceptDate,
-  DetailedDefinition, NonVerbRep,
+  DetailedDefinition, NonVerbRep, NON_VERBAL_TYPES,
+  NonVerbalEntity, SharedNonVerbalEntity,
+  Figure, FigureImage, Table, Formula,
+  NonVerbalReference, FigureReference, TableReference, FormulaReference,
+  BibliographyEntry, BibliographyData,
+  fetchLocalizedString, localizedStringIsEmpty, localizedStringIsPresent,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
 } from './models/index.js';
+
+export { AssetIndex } from './validators/asset-index.js';
+
+export {
+  ENTITY_DIRECTORIES,
+  ENTITY_TYPES,
+  entityDir,
+  entityPath,
+  isKnownEntityType,
+  parseEntityPath,
+} from './entity-directory.js';

package/src/managed-concept-collection.js

@@ -3,6 +3,7 @@ import { readConcepts, readRegister } from './concept-reader.js';
 import { writeConcepts } from './concept-writer.js';
 import { loadGcr } from './gcr-reader.js';
 import { GcrWriter } from './gcr-writer.js';
+import { BibliographyData } from './models/bibliography-data.js';
 
 export class ManagedConceptCollection {
   constructor() {
@@ -73,8 +74,16 @@ export class ManagedConceptCollection {
     return this;
   }
 
-  setBibliography(yamlString) {
-    this._bibliography = yamlString;
+  setBibliography(bib) {
+    if (bib instanceof BibliographyData) {
+      this._bibliography = bib;
+    } else if (typeof bib === 'string') {
+      this._bibliography = BibliographyData.fromYAML(bib);
+    } else if (bib == null) {
+      this._bibliography = null;
+    } else {
+      this._bibliography = new BibliographyData(bib);
+    }
     return this;
   }
 

package/src/models/bibliography-data.js

@@ -0,0 +1,43 @@
+import yaml from 'js-yaml';
+import { GlossaristModel } from './base.js';
+import { BibliographyEntry } from './bibliography-entry.js';
+
+export class BibliographyData extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    const entriesData = data.bibliography ?? data.entries ?? [];
+    this._rawEntries = Array.isArray(entriesData) ? entriesData : [];
+    this._entries = null;
+  }
+
+  get entries() {
+    return this._lazy('_entries', '_rawEntries',
+      e => e instanceof BibliographyEntry ? e : new BibliographyEntry(e));
+  }
+
+  find(id) {
+    return this.entries.find(e => e.id === id) ?? null;
+  }
+
+  get keys() {
+    return this.entries.map(e => e.id);
+  }
+
+  toJSON() {
+    if (this.entries.length === 0) return { bibliography: [] };
+    return { bibliography: this.entries.map(e => e.toJSON()) };
+  }
+
+  toYAML() {
+    return yaml.dump(this.toJSON());
+  }
+
+  static fromYAML(yamlString) {
+    const parsed = yaml.load(yamlString);
+    return new BibliographyData(parsed ?? {});
+  }
+
+  static fromJSON(data) {
+    return new BibliographyData(data);
+  }
+}

package/src/models/bibliography-entry.js

@@ -0,0 +1,26 @@
+import { GlossaristModel } from './base.js';
+
+export class BibliographyEntry extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.id = data.id ?? null;
+    this.reference = data.reference ?? null;
+    this.title = data.title ?? null;
+    this.link = data.link ?? null;
+    this.type = data.type ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.id != null) obj.id = this.id;
+    if (this.reference != null) obj.reference = this.reference;
+    if (this.title != null) obj.title = this.title;
+    if (this.link != null) obj.link = this.link;
+    if (this.type != null) obj.type = this.type;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new BibliographyEntry(data);
+  }
+}

package/src/models/concept.js

@@ -4,6 +4,9 @@ import { RelatedConcept } from './related-concept.js';
 import { ConceptReference } from './concept-reference.js';
 import { ConceptDate } from './concept-date.js';
 import { ConceptSource } from './concept-source.js';
+import { FigureReference } from './non-verbal-references.js';
+import { TableReference } from './non-verbal-references.js';
+import { FormulaReference } from './non-verbal-references.js';
 
 export class Concept extends GlossaristModel {
   constructor(data = {}) {
@@ -19,6 +22,12 @@ export class Concept extends GlossaristModel {
     this.tags = Array.isArray(data.tags) ? [...data.tags] : [];
     this.dates = _mapInstances(data.dates ?? [], ConceptDate);
     this.sources = _mapInstances(data.sources ?? [], ConceptSource);
+    this._rawFigures = data.figures ?? [];
+    this._rawTables = data.tables ?? [];
+    this._rawFormulas = data.formulas ?? [];
+    this._figures = null;
+    this._tables = null;
+    this._formulas = null;
     this.status = data.status ?? null;
     this.schemaVersion = data.schemaVersion ?? data.schema_version ?? '3';
     this.raw = data.raw ?? null;
@@ -107,6 +116,38 @@ export class Concept extends GlossaristModel {
     return null;
   }
 
+  get figures() {
+    return this._lazy('_figures', '_rawFigures',
+      r => FigureReference.fromJSON(r));
+  }
+
+  get tables() {
+    return this._lazy('_tables', '_rawTables',
+      r => TableReference.fromJSON(r));
+  }
+
+  get formulas() {
+    return this._lazy('_formulas', '_rawFormulas',
+      r => FormulaReference.fromJSON(r));
+  }
+
+  /**
+   * Yield every content-text fragment in this concept across all
+   * localizations, recursing through nested examples. Each yielded
+   * `{ text, source }` carries a dotted path rooted at
+   * `localizations.<lang>.<slot>[i]...content`.
+   *
+   * Designations are not included; they live on `LocalizedConcept.terms`
+   * and have a different shape.
+   */
+  *walkTexts() {
+    for (const lang of this.languages) {
+      const lc = this.localization(lang);
+      if (!lc) continue;
+      yield* lc.walkTexts(`localizations.${lang}`);
+    }
+  }
+
   toJSON() {
     const obj = { id: this.id };
     if (this.term != null) obj.term = this.term;
@@ -141,6 +182,9 @@ export class Concept extends GlossaristModel {
     if (this.sources.length > 0) {
       obj.sources = this.sources.map(s => s.toJSON());
     }
+    this._serialize(obj, 'figures', '_figures', '_rawFigures');
+    this._serialize(obj, 'tables', '_tables', '_rawTables');
+    this._serialize(obj, 'formulas', '_formulas', '_rawFormulas');
     if (this.status != null) obj.status = this.status;
     obj.schema_version = this.schemaVersion;
     return obj;

package/src/models/designation.js

@@ -1,23 +1,11 @@
-import { GlossaristModel } from './base.js';
+import { RegistrableModel } from './registrable.js';
 import { ConceptSource } from './concept-source.js';
 import { Pronunciation } from './pronunciation.js';
 import { GrammarInfo } from './grammar-info.js';
 import { RelatedConcept } from './related-concept.js';
 import { DesignationRelationship, DESIGNATION_RELATIONSHIP_TYPES } from './designation-relationship.js';
 
-export class Designation extends GlossaristModel {
-  static _registry = new Map();
-
-  static register(type, cls) {
-    Designation._registry.set(type, cls);
-  }
-
-  static fromData(data) {
-    if (data instanceof Designation) return data;
-    const Cls = Designation._registry.get(data?.type) ?? Designation;
-    return new Cls(data);
-  }
-
+export class Designation extends RegistrableModel {
   constructor(data = {}) {
     super();
     this.designation = data.designation ?? '';

package/src/models/detailed-definition.js

@@ -5,19 +5,43 @@ export class DetailedDefinition extends GlossaristModel {
   constructor(data = {}) {
     super();
     this.content = data.content ?? '';
-    this.sources = (data.sources ?? []).map(
-      s => s instanceof Citation ? s : new Citation(s)
-    );
+    this._rawSources = data.sources ?? [];
+    this._rawExamples = data.examples ?? [];
+    this._sources = null;
+    this._examples = null;
+  }
+
+  get sources() {
+    return this._lazy('_sources', '_rawSources',
+      s => s instanceof Citation ? s : new Citation(s));
+  }
+
+  get examples() {
+    return this._lazy('_examples', '_rawExamples',
+      e => e instanceof DetailedDefinition ? e : new DetailedDefinition(e));
   }
 
   toJSON() {
     const obj = { content: this.content };
-    if (this.sources.length > 0) {
-      obj.sources = this.sources.map(s => s.toJSON());
-    }
+    this._serialize(obj, 'sources', '_sources', '_rawSources');
+    this._serialize(obj, 'examples', '_examples', '_rawExamples');
     return obj;
   }
 
+  /**
+   * Yield this definition's content and the content of every nested
+   * example (recursively). Each item carries `{ text, source }` where
+   * `source` is `<path>.content` rooted at the `path` argument.
+   */
+  *walkTexts(path) {
+    if (typeof this.content === 'string' && this.content.length > 0) {
+      yield { text: this.content, source: `${path}.content` };
+    }
+    for (let i = 0; i < this.examples.length; i++) {
+      yield* this.examples[i].walkTexts(`${path}.examples[${i}]`);
+    }
+  }
+
   static fromJSON(data) {
     return new DetailedDefinition(data);
   }

package/src/models/figure.js

@@ -0,0 +1,71 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class FigureImage {
+  constructor(data = {}) {
+    this.src = data.src ?? null;
+    this.format = data.format ?? null;
+    this.role = data.role ?? null;
+    this.width = data.width ?? null;
+    this.height = data.height ?? null;
+    this.scale = data.scale ?? null;
+  }
+
+  toJSON() {
+    const obj = {};
+    if (this.src != null) obj.src = this.src;
+    if (this.format != null) obj.format = this.format;
+    if (this.role != null) obj.role = this.role;
+    if (this.width != null) obj.width = this.width;
+    if (this.height != null) obj.height = this.height;
+    if (this.scale != null) obj.scale = this.scale;
+    return obj;
+  }
+
+  static fromJSON(data) { return new FigureImage(data); }
+}
+
+export class Figure extends SharedNonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this._rawImages = data.images ?? [];
+    this._rawSubfigures = data.subfigures ?? [];
+    this._images = null;
+    this._subfigures = null;
+  }
+
+  get images() {
+    return this._lazy('_images', '_rawImages',
+      i => i instanceof FigureImage ? i : new FigureImage(i));
+  }
+
+  get subfigures() {
+    return this._lazy('_subfigures', '_rawSubfigures',
+      s => s instanceof Figure ? s : new Figure(s));
+  }
+
+  findById(targetId) {
+    if (this.id === targetId) return this;
+    for (const sub of this.subfigures) {
+      const found = sub.findById(targetId);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  allIds() {
+    const ids = this.id != null ? [this.id] : [];
+    return [...ids, ...this.subfigures.flatMap(s => s.allIds())];
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    this._serialize(obj, 'images', '_images', '_rawImages');
+    this._serialize(obj, 'subfigures', '_subfigures', '_rawSubfigures');
+    return obj;
+  }
+
+  static fromJSON(data) { return new Figure(data); }
+}
+
+NonVerbalEntity.register('figure', Figure);

package/src/models/formula.js

@@ -0,0 +1,21 @@
+import { SharedNonVerbalEntity } from './shared-non-verbal-entity.js';
+import { NonVerbalEntity } from './non-verbal-entity.js';
+
+export class Formula extends SharedNonVerbalEntity {
+  constructor(data = {}) {
+    super(data);
+    this.expression = data.expression ?? null;
+    this.notation = data.notation ?? null;
+  }
+
+  toJSON() {
+    const obj = super.toJSON();
+    if (this.expression != null) obj.expression = this.expression;
+    if (this.notation != null) obj.notation = this.notation;
+    return obj;
+  }
+
+  static fromJSON(data) { return new Formula(data); }
+}
+
+NonVerbalEntity.register('formula', Formula);