asciichem-model 0.3.2

data/models/asciichem/Group.lutaml

@@ -0,0 +1,22 @@
+class Group {
+  definition {
+    A bracketed sub-formula whose optional multiplier applies to the
+    whole group, e.g. (OH)_2.
+  }
+  +nodes: Node[1..*] {
+    definition { Atoms, nested molecules, or nested groups. }
+  }
+  +multiplicity: String {
+    definition { Multiplier applied to the group ("2"). }
+  }
+  +bracket: BracketKind {
+    definition { The bracket style enclosing the group. }
+  }
+}
+
+enum BracketKind {
+  definition { Bracket kinds, one per AsciiChem spelling. }
+  paren { definition { Round brackets: (OH)_2 — the default. } }
+  square { definition { Square brackets: [OH]_2. } }
+  brace { definition { Braces: {OH}_2. } }
+}

data/models/asciichem/Identifier.lutaml

@@ -0,0 +1,56 @@
+class Identifier {
+  definition {
+    A substance identifier: a value plus the convention that
+    determines its format (CAS RN with check digit, InChI, InChIKey
+    14-10-1 blocks, SMILES, IUPAC name, PubChem CID, ChEBI).
+    Maps to CML `<identifier convention="...">`. Format constraints
+    are enforced offline by the implementations' identifier
+    validators; assignment checking is resolution, not modelling.
+  }
+  +value: String {
+    definition {
+      The identifier value (e.g. "50-78-2").
+    }
+  }
+  +convention: IdentifierConvention {
+    definition {
+      The identifier convention registry value.
+    }
+  }
+  +dictRef: String {
+    definition {
+      Optional dictionary reference for CML round-trip.
+    }
+  }
+}
+
+enum IdentifierConvention {
+  definition {
+    Registry of known identifier conventions. Adding a convention is
+    a MINOR model bump; format validators are per-implementation.
+  }
+  cas {
+    definition { CAS Registry Number, DDDDDDD-DD-D with check digit. }
+  }
+  inchi {
+    definition { IUPAC International Chemical Identifier. }
+  }
+  inchikey {
+    definition { Hashed InChI key, 14-10-1 uppercase blocks. }
+  }
+  smiles {
+    definition { SMILES structure string. }
+  }
+  canonical-smiles {
+    definition { Canonical SMILES from a specific toolchain. }
+  }
+  iupac-name {
+    definition { Systematic IUPAC name. }
+  }
+  pubchem-cid {
+    definition { PubChem Compound ID. }
+  }
+  chebi {
+    definition { ChEBI ontology identifier. }
+  }
+}

data/models/asciichem/Mechanism.lutaml

@@ -0,0 +1,22 @@
+class Mechanism {
+  definition {
+    A reaction mechanism: labelled reaction steps plus spectator
+    species that are present but not transformed.
+  }
+  +steps: MechanismStep[0..*] {
+    definition { The mechanism steps in order. }
+  }
+  +spectators: Molecule[0..*] {
+    definition { Species present but not transformed. }
+  }
+
+  class MechanismStep {
+    definition { One labelled step of the mechanism. }
+    +label: String {
+      definition { Step label, e.g. "initiation". }
+    }
+    +reaction: Reaction {
+      definition { The step's reaction. }
+    }
+  }
+}

data/models/asciichem/Molecule.lutaml

@@ -0,0 +1,25 @@
+class Molecule {
+  definition {
+    An ordered sequence of atoms/groups with optional stoichiometric
+    coefficient, optional stereochemistry marker, and optional
+    names/identifiers/properties/metadata attached as CML-level
+    annotations. Substance identity lives here via Identifier
+    instances.
+  }
+  +nodes: Atom[0..*] {
+    definition {
+      Ordered child nodes (atoms, groups, nested molecules).
+    }
+  }
+  +coefficient: String {
+    definition {
+      Stoichiometric coefficient (e.g. "2" in `2H_2O`).
+    }
+  }
+  +identifiers: Identifier[0..*] {
+    definition {
+      Substance identifiers attached to this molecule (CAS RN, InChI,
+      SMILES, ...), each with a convention.
+    }
+  }
+}

data/models/asciichem/Name.lutaml

@@ -0,0 +1,15 @@
+class Name {
+  definition {
+    A molecule name. Maps to CML name; convention distinguishes
+    IUPAC, CAS, trivial, and trade names.
+  }
+  +content: String {
+    definition { The name text. }
+  }
+  +convention: String {
+    definition { Naming convention, e.g. "iupac" or "cas". }
+  }
+  +dictRef: String {
+    definition { Optional dictionary reference for CML round-trip. }
+  }
+}

data/models/asciichem/Provenance.lutaml

@@ -0,0 +1,20 @@
+class Provenance {
+  definition {
+    Where a piece of identity data came from: the asserting source,
+    retrieval timestamp, source version, and the attribution line
+    that licence terms (e.g. CAS Common Chemistry CC BY-NC 4.0)
+    require on every cached record.
+  }
+  +source: String {
+    definition { Source adapter name, e.g. "pubchem" or "commonchemistry". }
+  }
+  +retrievedAt: DateTime {
+    definition { When the value was retrieved from the source. }
+  }
+  +sourceVersion: String {
+    definition { Source release, or an accessed-date pin when versionless. }
+  }
+  +attribution: String {
+    definition { Attribution string emitted with NC-licensed data. }
+  }
+}

data/models/asciichem/Reaction.lutaml

@@ -0,0 +1,36 @@
+class Reaction {
+  definition {
+    A chemical reaction: reactants, an arrow with optional
+    conditions above/below it, and products.
+  }
+  +reactants: Molecule[0..*] {
+    definition { The left-hand side molecules. }
+  }
+  +products: Molecule[0..*] {
+    definition { The right-hand side molecules. }
+  }
+  +arrow: ArrowKind {
+    definition { The reaction arrow kind; forward by default. }
+  }
+  +conditions: ReactionConditions {
+    definition { Free text above/below the arrow. }
+  }
+}
+
+enum ArrowKind {
+  definition { forward (->), reverse (<-), equilibrium (<=>), resonance (<->). }
+  forward {}
+  reverse {}
+  equilibrium {}
+  resonance {}
+}
+
+class ReactionConditions {
+  definition { Text carried over/under the reaction arrow. }
+  +above: String {
+    definition { Text above the arrow, e.g. the catalyst [Fe]. }
+  }
+  +below: String {
+    definition { Text below the arrow, e.g. the temperature. }
+  }
+}

data/models/asciichem/ReactionCascade.lutaml

@@ -0,0 +1,6 @@
+class ReactionCascade {
+  definition { Two or more reactions chained together (A -> B -> C). }
+  +steps: Reaction[2..*] {
+    definition { The chained reactions, in order. }
+  }
+}

data/models/asciichem/Spectrum.lutaml

@@ -0,0 +1,31 @@
+class Spectrum {
+  definition {
+    A spectroscopy record: technique, acquisition parameters, and
+    peaks.
+  }
+  +technique: String {
+    definition { Technique type, e.g. "nmr", "ir", "mass". }
+  }
+  +params: String[0..*] {
+    definition { Acquisition parameters keyed by name (solvent, frequency, ...). }
+  }
+  +peaks: Peak[0..*] {
+    definition { The spectrum's peaks. }
+  }
+
+  class Peak {
+    definition { One spectroscopic peak. }
+    +position: String {
+      definition { Peak position (ppm, cm^-1, m/z, ...). }
+    }
+    +intensity: String {
+      definition { Relative intensity. }
+    }
+    +multiplicity: String {
+      definition { Splitting pattern (s, d, t, q, m). }
+    }
+    +assignment: String {
+      definition { Structural assignment of the peak. }
+    }
+  }
+}

data/models/asciichem/SubstanceRecord.lutaml

@@ -0,0 +1,52 @@
+class SubstanceRecord {
+  definition {
+    The resolved view of a substance produced by a resolver source,
+    shaped after the CAS Common Chemistry detail payload so resolver
+    output maps onto it 1:1. Every identifier and property carries
+    its own provenance.
+  }
+  +preferredName: String {
+    definition { The source's preferred chemical name. }
+  }
+  +synonyms: String[0..*] {
+    definition { Systematic, common, and trade names. }
+  }
+  +formula: String {
+    definition { Molecular formula as stated by the source. }
+  }
+  +molecularWeight: Real {
+    definition { Molecular weight in g/mol as stated by the source. }
+  }
+  +identifiers: ProvenancedIdentifier[1..*] {
+    definition { The substance's identifiers, each with provenance. }
+  }
+  +properties: ProvenancedProperty[0..*] {
+    definition { Physical properties, each with provenance. }
+  }
+}
+
+class ProvenancedIdentifier {
+  definition { An identifier together with where it came from. }
+  +identifier: Identifier {
+    definition { The identifier value and convention. }
+  }
+  +provenance: Provenance {
+    definition { The source that asserted this identifier. }
+  }
+}
+
+class ProvenancedProperty {
+  definition { A named physical property with units and provenance. }
+  +name: String {
+    definition { e.g. "boiling point", "melting point", "density". }
+  }
+  +value: String {
+    definition { The property value as stated by the source. }
+  }
+  +units: String {
+    definition { Units of the value, when stated. }
+  }
+  +provenance: Provenance {
+    definition { The source that asserted this property. }
+  }
+}

data/models/asciichem/Text.lutaml

@@ -0,0 +1,9 @@
+class Text {
+  definition {
+    Free-form text in double quotes. Unquoted prose is a parse error
+    by design.
+  }
+  +content: String {
+    definition { The text content without the quote delimiters. }
+  }
+}

data/models/asciichem/ZMatrix.lutaml

@@ -0,0 +1,34 @@
+class ZMatrix {
+  definition {
+    Internal coordinates: each row places an atom by distance, angle,
+    and dihedral relative to previously defined atoms.
+  }
+  +rows: ZRow[0..*] {
+    definition { The z-matrix rows in definition order. }
+  }
+
+  class ZRow {
+    definition { One atom placement by internal coordinates. }
+    +atom: String {
+      definition { This row's atom label, e.g. "H1". }
+    }
+    +ref1: String {
+      definition { Label of the bond-length reference atom. }
+    }
+    +distance: String {
+      definition { Bond length to ref1. }
+    }
+    +ref2: String {
+      definition { Label of the angle reference atom. }
+    }
+    +angle: String {
+      definition { Angle atom-ref1-ref2 in degrees. }
+    }
+    +ref3: String {
+      definition { Label of the dihedral reference atom. }
+    }
+    +dihedral: String {
+      definition { Dihedral ref2-ref1-atom in degrees. }
+    }
+  }
+}

data/schemas/v1/atom.yaml

@@ -0,0 +1,45 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/atom"
+title: AsciiChem Atom node
+description: |
+  A chemical atom in the canonical wire form. A prefix superscript
+  (isotope) binds to the atom — the defining semantic fix over
+  AsciiMath's phantom `{}` carrier.
+type: object
+required: [type, element]
+properties:
+  type:
+    const: atom
+  element:
+    type: string
+    pattern: "^[A-Z][a-z]?$"
+    description: Element symbol (e.g. "C", "Cl").
+    examples: ["C", "Cl", "Fe"]
+  isotope:
+    type: string
+    pattern: "^\\d+$"
+    description: Isotope mass number bound to this atom ("14" in ^14C).
+  charge:
+    type: string
+    description: Charge annotation (e.g. "2+", "-").
+  subscript:
+    type: string
+    pattern: "^\\d+$"
+    description: Subscript multiplicity ("2" in H_2O).
+  oxidationState:
+    type: string
+    description: Oxidation state annotation ("II" in Ca^(II)).
+  lonePairs:
+    type: integer
+    minimum: 0
+    description: Lewis lone-pair markers ("::O" carries 2).
+  radicalElectrons:
+    type: integer
+    minimum: 0
+    description: Radical-electron markers ("N." carries 1).
+  ringClosures:
+    type: string
+    pattern: "^\\d+$|^(\\d)+$"
+    description: SMILES-style ring closure digits ("1" in C1...C1).
+additionalProperties: false

data/schemas/v1/bond.yaml

@@ -0,0 +1,20 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/bond"
+title: AsciiChem Bond node
+description: |
+  A bond between adjacent atoms in a linear structure. Kind enum is
+  the single source of truth shared by every implementation; adding a
+  kind is a MINOR model bump.
+type: object
+required: [type]
+properties:
+  type:
+    const: bond
+  kind:
+    default: single
+    enum: [single, double, triple, quadruple, wedge, hash, dative, wavy]
+    description: |
+      single (-), double (=), triple (#), quadruple (##), wedge (>-),
+      hash (-<), dative (~>), wavy (~~).
+additionalProperties: false

data/schemas/v1/calculation.yaml

@@ -0,0 +1,37 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/calculation"
+title: AsciiChem Calculation node
+description: |
+  A computational-chemistry result: method, basis set, and computed
+  properties.
+type: object
+required: [type]
+properties:
+  type:
+    const: calculation
+  method:
+    type: string
+    description: e.g. "B3LYP".
+  basis:
+    type: string
+    description: e.g. "6-31G(d)".
+  properties:
+    type: array
+    items:
+      type: object
+      required: [title, value]
+      properties:
+        title:
+          type: string
+          description: Property name, e.g. "dipole".
+        value:
+          type: string
+        units:
+          type: string
+        dictRef:
+          type: string
+        convention:
+          type: string
+      additionalProperties: false
+additionalProperties: false

data/schemas/v1/crystal.yaml

@@ -0,0 +1,30 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/crystal"
+title: AsciiChem Crystal node
+description: |
+  A crystallographic cell: unit-cell constants, space group, and the
+  asymmetric-unit atoms with fractional coordinates.
+type: object
+required: [type]
+properties:
+  type:
+    const: crystal
+  name:
+    type: string
+    description: Mineral/compound name.
+  a: { type: number, description: Cell length a (Angstrom). }
+  b: { type: number, description: Cell length b. }
+  c: { type: number, description: Cell length c. }
+  alpha: { type: number, description: Cell angle alpha (degrees). }
+  beta: { type: number, description: Cell angle beta. }
+  gamma: { type: number, description: Cell angle gamma. }
+  spacegroup:
+    type: string
+    description: Hermann-Mauguin symbol, e.g. "Fm-3m".
+  atoms:
+    type: array
+    description: Asymmetric-unit atoms (fractional coordinates ride on the atom's coordinate annotations).
+    items:
+      $ref: "atom.yaml"
+additionalProperties: false

data/schemas/v1/electron-configuration.yaml

@@ -0,0 +1,43 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/electron-configuration"
+title: AsciiChem ElectronConfiguration node
+description: |
+  Orbital occupancy (`1s^2 2s^2 2p^6`) with an optional term symbol
+  (^{multiplicity}L_J).
+type: object
+required: [type, orbitals]
+properties:
+  type:
+    const: electron-configuration
+  orbitals:
+    type: array
+    description: Ordered orbital occupancies.
+    items:
+      type: object
+      required: [orbital, occupancy]
+      properties:
+        orbital:
+          type: string
+          description: Orbital label, e.g. "1s", "2p".
+        occupancy:
+          type: string
+          pattern: "^\\d+$"
+          description: Electron count in this orbital.
+      additionalProperties: false
+  termSymbol:
+    type: object
+    description: Optional atomic term symbol.
+    properties:
+      multiplicity:
+        type: string
+        pattern: "^\\d+$"
+        description: Spin multiplicity (2S+1).
+      letter:
+        type: string
+        description: Orbital angular momentum letter (S, P, D, ...).
+      jValue:
+        type: string
+        description: Total angular momentum J.
+    additionalProperties: false
+additionalProperties: false

data/schemas/v1/embedded-math.yaml

@@ -0,0 +1,18 @@
+%YAML 1.2
+---
+$id: "https://github.com/asciichem/asciichem-model/v1/embedded-math"
+title: AsciiChem EmbeddedMath node
+description: |
+  Math embedded in chemistry (backtick syntax, e.g. `K_c = 1`). The
+  wire form carries the AsciiMath source; the parsed
+  Plurimath::Math::Formula is a Ruby-implementation detail.
+type: object
+required: [type, source]
+properties:
+  type:
+    const: embedded-math
+  source:
+    type: string
+    minLength: 1
+    description: The backticked AsciiMath source text.
+additionalProperties: false

data/schemas/v1/examples/01-atom-isotope.yaml

@@ -0,0 +1,7 @@
+# 01 — Atom with prefix isotope (the defining semantic fix)
+
+# `^14C` parses as Atom(element: "C", isotope: "14") — the isotope
+# binds to the atom, never to a phantom AsciiMath `{}` carrier.
+type: atom
+element: C
+isotope: "14"

data/schemas/v1/examples/02-molecule-water.yaml

@@ -0,0 +1,18 @@
+# 02 — Molecule with coefficient, atoms, and substance identifiers
+
+# `2H_2O` annotated with validated identity: water's CAS RN and InChI.
+type: molecule
+coefficient: "2"
+nodes:
+  - type: atom
+    element: H
+    subscript: "2"
+  - type: atom
+    element: O
+identifiers:
+  - type: identifier
+    value: "7732-18-5"
+    convention: cas
+  - type: identifier
+    value: "InChI=1S/H2O/h1H2"
+    convention: inchi

data/schemas/v1/examples/03-group-multiplicity.yaml

@@ -0,0 +1,11 @@
+# 03 — Group with multiplicity and bracket kind
+
+# `(OH)_2`: a paren group with multiplier 2.
+type: group
+multiplicity: "2"
+bracket: paren
+nodes:
+  - type: atom
+    element: O
+  - type: atom
+    element: H

data/schemas/v1/examples/04-reaction-conditions.yaml

@@ -0,0 +1,30 @@
+# 04 — Reaction with equilibrium arrow and conditions
+
+# `N_2 + 3H_2 <=>[Fe][400°C] 2NH_3`: catalyst above the arrow,
+# temperature below.
+type: reaction
+arrow: equilibrium
+conditions:
+  above: "Fe"
+  below: "400°C"
+reactants:
+  - type: molecule
+    nodes:
+      - type: atom
+        element: N
+        subscript: "2"
+  - type: molecule
+    coefficient: "3"
+    nodes:
+      - type: atom
+        element: H
+        subscript: "2"
+products:
+  - type: molecule
+    coefficient: "2"
+    nodes:
+      - type: atom
+        element: N
+      - type: atom
+        element: H
+        subscript: "3"

data/schemas/v1/examples/05-substance-record-aspirin.yaml

@@ -0,0 +1,40 @@
+# 05 — SubstanceRecord: aspirin resolved from CAS Common Chemistry
+
+# The resolved view a resolver produces for CAS RN 50-78-2. Every
+# identifier and property carries provenance; the attribution line is
+# required because Common Chemistry content is CC BY-NC 4.0.
+type: substance-record
+preferredName: Aspirin
+synonyms:
+  - 2-Acetyloxybenzoic acid
+  - acetylsalicylic acid
+formula: C9H8O4
+molecularWeight: 180.16
+identifiers:
+  - identifier:
+      type: identifier
+      value: "50-78-2"
+      convention: cas
+    provenance:
+      type: provenance
+      source: commonchemistry
+      retrievedAt: "2026-09-09T00:00:00Z"
+      attribution: "CAS Common Chemistry, CC BY-NC 4.0"
+  - identifier:
+      type: identifier
+      value: "BSYNRYMUTXBXSQ-UHFFFAOYSA-N"
+      convention: inchikey
+    provenance:
+      type: provenance
+      source: commonchemistry
+      retrievedAt: "2026-09-09T00:00:00Z"
+      attribution: "CAS Common Chemistry, CC BY-NC 4.0"
+properties:
+  - name: melting point
+    value: "135"
+    units: "°C"
+    provenance:
+      type: provenance
+      source: commonchemistry
+      retrievedAt: "2026-09-09T00:00:00Z"
+      attribution: "CAS Common Chemistry, CC BY-NC 4.0"

data/schemas/v1/examples/06-electron-configuration.yaml

@@ -0,0 +1,16 @@
+# 06 — Electron configuration with term symbol
+
+# `1s^2 2s^2 2p^6 3d^10 4s^2` style occupancy plus an optional
+# atomic term symbol.
+type: electron-configuration
+orbitals:
+  - orbital: 1s
+    occupancy: "2"
+  - orbital: 2s
+    occupancy: "2"
+  - orbital: 2p
+    occupancy: "6"
+termSymbol:
+  multiplicity: "3"
+  letter: P
+  jValue: "2"