lutaml-model 0.8.56 → 0.8.106

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eaff3e9ef7cbf71d8cd5adbf05161b81c43399c92a1c741023005722c190025
-  data.tar.gz: bd4383a644f8878226034c191215780c38b5f1beee2cdf196e26d31067908878
+  metadata.gz: cc1bb0f95876011fac44764d7ea55c334d24ea2a20911e46f4200448cf50cc1e
+  data.tar.gz: 23f02dbcf3dac25a19a50f4a8bf75b81d642b64514c0aeb9a820d727be63406f
 SHA512:
-  metadata.gz: 00453571fbb8c6b2540f3d545fe53d0c664fa18301797e5192699a6dded982ca9280a4ac39dcc2a7c60f03746ee0dc986e9571c05f9f387f503ba6ab2b522d5c
-  data.tar.gz: bdf133791492a00bb00babcc2b1037366918e6eba7bb05001d4b5748152249c7e45c47c0dbd099c72e0f99acf949febf8ae36f43bb99b43b35874112da3f6312
+  metadata.gz: 8d649b8eef84ef0cfa60ec5fec9e70b0fa45cdc44508325f12c7a17d66e3ca437535c3bf56bc725217f73d305046c9102d7dba067148f4efdec8996d2f2f8ec2
+  data.tar.gz: d81707bac3fb9bf9ebc3091c421253e3b9b8abd085891e03debcd19674af75ae5e6dc5f1b724fbb05e160847694dcc8752e9eb1fb17425a394c1babc67777273

data/.github/scripts/test_installed_gem.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Smoke test for the INSTALLED lutaml-model gem (parsanol-ruby
+# pattern, lutaml-model#833): runs against the gem's own load paths —
+# never the repo — and exercises the boot surface a packaging
+# regression would break: every format round-trip and the Opal boot
+# manifest's autoload coverage.
+
+gem_root = Gem::Specification.find_by_name("lutaml-model").full_gem_path
+raise "installed lutaml-model not found" unless gem_root
+
+$LOAD_PATH.unshift(File.join(gem_root, "lib"))
+require "lutaml/model"
+
+# Boot manifest: every autoload in lib/compat/opal/lutaml_model_boot.rb
+# must resolve from the installed gem alone.
+boot = File.join(gem_root, "lib", "compat", "opal", "lutaml_model_boot.rb")
+if File.exist?(boot)
+  manifest = File.read(boot)
+  missing = manifest.scan(/autoload[^\n]*["']([^"']+)["']/).flatten.select do |path|
+    !File.exist?(File.join(gem_root, "lib", path))
+  end
+  raise "boot manifest references missing files: #{missing.inspect}" unless missing.empty?
+end
+
+class Smoke < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :count, :integer
+  attribute :tags, :string, collection: true
+
+  xml do
+    root "smoke"
+    map_attribute "name", to: :name
+    map_element "count", to: :count
+    map_element "tag", to: :tags
+  end
+end
+
+require "tempfile"
+model = Smoke.new(name: "smoke", count: 3, tags: %w[a b])
+
+round_trips = {
+  xml: -> { Smoke.from_xml(model.to_xml) },
+  json: -> { Smoke.from_json(model.to_json) },
+  yaml: -> { Smoke.from_yaml(model.to_yaml) },
+  toml: -> { Smoke.from_toml(model.to_toml) },
+  hash: -> { Smoke.from_hash(model.to_hash) },
+}
+round_trips.each do |format, parse|
+  round = parse.call
+  raise "#{format}: name lost" if round.name != "smoke"
+  raise "#{format}: count lost" if round.count != 3
+  raise "#{format}: tags lost" if Array(round.tags).sort != %w[a b]
+end
+
+puts "installed-gem smoke OK (#{gem_root}, " \
+     "lutaml-model #{Lutaml::Model::VERSION}, " \
+     "#{round_trips.keys.join("/")})"

data/.github/workflows/downstream-performance.yml

@@ -17,9 +17,16 @@ permissions:
 jobs:
   benchmark:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     strategy:
       fail-fast: false
+      # Serializes the corpus legs: concurrent legs on shared runners
+      # produce contention measurements that misfire the absolute gates
+      # (lutaml-model#834: niso 0.921s vs a 0.25s main-passing gate).
+      # max-parallel, NOT a job-level concurrency group: with a
+      # matrix, every leg lands in the same group and GitHub cancels
+      # four of the five at start.
+      max-parallel: 1
       matrix:
         include:
           - downstream: xmi
@@ -109,7 +116,16 @@ jobs:
             File.write("Gemfile", out.join)
           ' /tmp/main-checkout
           bundle install --jobs=4
-          bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb
+          # lutaml-model#834: min-of-N across attempts — contention
+          # inflates single-shot timings, so run three attempts and let
+          # the merge keep the least-interfered measurement per fixture.
+          for i in 1 2 3; do
+            bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
+              echo "::warning::baseline attempt $i errored (#834) — continuing with remaining attempts"
+            cp "$BENCH_JSON" "$BENCH_JSON.attempt$i" 2>/dev/null || true
+          done
+          ruby ${{ github.workspace }}/bench/bench_merge_attempts.rb \
+            "$BENCH_JSON" "$BENCH_JSON.attempt1" "$BENCH_JSON.attempt2" "$BENCH_JSON.attempt3"
 
       - name: Run current benchmark (PR branch)
         env:
@@ -117,6 +133,9 @@ jobs:
           ${{ matrix.env_key }}: ${{ github.workspace }}/downstream
           LUTAML_MODEL_DIR: ${{ github.workspace }}
           BENCH_JSON: /tmp/bench_current_${{ matrix.downstream }}.json
+          # TODO.perf 17: corpus opt-out histogram in the job log —
+          # which clauses (if any) keep this corpus interpretive.
+          PLAN_COMPILE_STATS: "1"
         run: |
           cd downstream
           ruby -e '
@@ -134,7 +153,13 @@ jobs:
             File.write("Gemfile", out.join)
           ' ${{ github.workspace }}
           bundle install --jobs=4
-          bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb
+          for i in 1 2 3; do
+            bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
+              echo "::warning::current attempt $i errored (#834) — continuing with remaining attempts"
+            cp "$BENCH_JSON" "$BENCH_JSON.attempt$i" 2>/dev/null || true
+          done
+          ruby ${{ github.workspace }}/bench/bench_merge_attempts.rb \
+            "$BENCH_JSON" "$BENCH_JSON.attempt1" "$BENCH_JSON.attempt2" "$BENCH_JSON.attempt3"
 
       - name: Compare baseline vs current
         run: |

data/.github/workflows/js-pr-check.yml

@@ -31,6 +31,10 @@ permissions:
   contents: read
   pull-requests: write
 
+concurrency:
+  group: js-pr-check-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   trigger:
     runs-on: ubuntu-latest

data/.github/workflows/js-sync.yml

@@ -20,6 +20,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: js-sync-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   trigger:
     runs-on: ubuntu-latest

data/.github/workflows/opal.yml

@@ -9,9 +9,18 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: opal-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
+    env:
+      # The Opal leg is the ONLY consumer of the vendored
+      # Opal-compatibility forks (#835 step 2): MRI legs run released
+      # oga/ruby-ll.
+      LUTAML_OPAL_FORKS: "1"
     steps:
       - uses: actions/checkout@v6
         with:

data/.github/workflows/rake.yml

@@ -23,10 +23,13 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         ruby: ["3.3", "3.4", "4.0"]
         experimental: [false]
-        include:
+        # ruby head runs on ubuntu/macos only: windows-head cannot build
+        # the released ruby-ll C extension (and the vendored forks exist
+        # for Opal), so that cell was permanently red with zero signal
+        # (#832 follow-up).
+        exclude:
           - os: windows-latest
             ruby: head
-            experimental: true
     steps:
       - uses: actions/checkout@v6
         with:
@@ -36,50 +39,12 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          # bundler-cache disabled: the path-source oga and ruby-ll forks
-          # need ragel + ruby-ll outputs generated (rake vendor:prepare)
-          # before their C extensions can compile.
+          # bundler-cache disabled: adapter pins resolve per run.
           bundler-cache: false
 
-      - name: Install ragel (Linux)
-        if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y ragel
-
-      - name: Install ragel (macOS)
-        if: runner.os == 'macOS'
-        run: brew install ragel
-
-      - name: Install ragel (Windows)
-        if: runner.os == 'Windows'
-        run: choco install -y ragel
-        continue-on-error: true
-
-      - name: Install ruby-ll (for rake vendor:prepare)
-        run: gem install ruby-ll --no-document
-
-      - name: Generate ragel / ruby-ll outputs in vendored forks
-        # Run before bundle install: the path-source oga/ruby-ll forks
-        # gitignore their generated .rb/.c files. bundle install compiles
-        # the C extensions via each fork's extconf.rb, which needs
-        # ext/c/lexer.c to exist.
-        run: rake vendor:prepare
-
-      - name: Configure bundler
-        # ruby-ll's C extension needs an older C standard on some compilers.
-        run: |
-          mkdir -p .bundle
-          echo '---' > .bundle/config
-          echo 'BUNDLE_BUILD__RUBY___LL: "--with-cflags=-std=gnu17"' >> .bundle/config
-
       - name: Install dependencies
         run: bundle install
 
-      - name: Compile liboga / libll native extensions
-        # Bundler does not reliably build path-source gems' native
-        # extensions; compile them explicitly so `require "oga"` (which
-        # requires libll) resolves under CRuby.
-        run: rake vendor:compile
-
       - name: Run tests
         run: bundle exec rake spec
 

data/.github/workflows/release.yml

@@ -20,6 +20,12 @@ permissions:
   contents: write
   id-token: write
 
+# One release at a time: concurrent bumps race the version commit
+# and half-published gems are worse than a queued release.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
   release:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
@@ -33,3 +39,38 @@ jobs:
       # pat_token is optional (private-gem checkout + GH Packages). Keep if
       # the org still uses private deps; drop once pure public.
       pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}
+
+  # lutaml-model#833: the reusable release pushes the gem without ever
+  # installing it — packaging regressions (gemspec globs, autoload
+  # drift, fresh-bundler resolution) pass in-repo and break consumers.
+  # Install the just-published version from rubygems.org and exercise
+  # the boot surface from the gem's own load paths.
+  smoke:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        # The release job commits the version bump to main while this job
+        # runs; a checkout of the dispatch-time HEAD reads the previous
+        # version and smoke-tests the wrong gem (0.8.60 was smoke-checked
+        # for the 0.8.61 release). Pull post-bump main before resolving.
+        with:
+          fetch-depth: 5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - name: Resolve the released version
+        id: version
+        # From the version file, not git describe: the default checkout
+        # is shallow with no tags, so git describe failed and the empty
+        # version produced `gem install "lutaml-model:"`.
+        run: |
+          git pull --ff-only origin main
+          echo "version=$(ruby -e 'print File.read(%q{lib/lutaml/model/version.rb})[/VERSION\s*=\s*"([^"]+)"/, 1]')" >> "$GITHUB_OUTPUT"
+      - name: Install and smoke the released gem
+        run: |
+          gem install "lutaml-model:${{ steps.version.outputs.version }}" --no-document
+          # The round-trip script exercises all five formats; the TOML
+          # legs require an adapter gem to be present.
+          gem install tomlib toml-rb --no-document
+          ruby .github/scripts/test_installed_gem.rb

data/Gemfile

@@ -10,8 +10,17 @@ gemspec
 # in lib/oga.rb / lib/ll/setup.rb that selects the pure-Ruby implementation
 # when RUBY_PLATFORM == 'opal'. Under CRuby/JRuby the forks behave
 # identically to upstream (the conditional falls through to liboga/libll).
-gem "oga", path: "vendor/opal-oga"
-gem "ruby-ll", path: "vendor/opal-ruby-ll"
+# The vendored forks are Opal-compatibility shims (pure-Ruby lexer)
+# used by the Opal CI leg ONLY (LUTAML_OPAL_FORKS=1 in opal.yml) —
+# #835 step 2. Every MRI leg runs against released oga/ruby-ll; the
+# forks' C extension is upstream's and adds nothing under MRI.
+if ENV["LUTAML_OPAL_FORKS"]
+  gem "oga", path: "vendor/opal-oga"
+  gem "ruby-ll", path: "vendor/opal-ruby-ll"
+else
+  gem "oga"
+  gem "ruby-ll"
+end
 
 # needed for liquid with ruby 3.4
 gem "base64"
@@ -35,7 +44,12 @@ gem "rexml"
 # Native engines stay development-only: every adapter detects and
 # degrades gracefully at runtime (safe requires + prefer-if-available).
 # yeptris ships no Windows prebuilt platform gem.
-gem "leptris"
+# leptris floor: the single capability line for the plan fast path
+# (see Lutaml::Xml::Leptris::MIN_LEPTRIS_VERSION) — child snapshots,
+# exact-URI attribute rows, nested-attribute capture, wildcard rows,
+# walk-side ns retention and leniency, :unqualified rows, and the
+# address-based text attach all ride it.
+gem "leptris", ">= 1.9.336.0"
 gem "teptris"
 gem "yeptris" unless Gem.win_platform?
 # TODO: revert rng branch to main when lutaml/rng#32 is merged

data/bench/bench_alloc_audit.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module AllocAudit
+  class Row < Lutaml::Model::Serializable
+    attribute :id, :integer
+    attribute :name, :string
+
+    xml do
+      root "row"
+      map_element "id", to: :id
+      map_element "name", to: :name
+    end
+
+    json do
+      map "id", to: :id
+      map "name", to: :name
+    end
+  end
+
+  class Doc < Lutaml::Model::Serializable
+    attribute :rows, AllocAudit::Row, collection: true
+
+    xml do
+      root "doc"
+      map_element "row", to: :rows
+    end
+
+    json do
+      map "rows", to: :rows
+    end
+  end
+
+  DOC = Doc.new(rows: Array.new(500) { |i| Row.new(id: i, name: "n#{i}") })
+
+  def self.alloc
+    GC.start
+    before = GC.stat(:total_allocated_objects)
+    yield
+    GC.stat(:total_allocated_objects) - before
+  end
+
+  3.times do
+    DOC.to_xml
+    DOC.to_json
+    DOC.to_hash
+  end
+
+  puts "rows=500"
+  puts "to_xml_alloc=#{alloc { DOC.to_xml }}"
+  puts "to_json_alloc=#{alloc { DOC.to_json }}"
+  puts "to_hash_alloc=#{alloc { DOC.to_hash }}"
+  puts "from_xml_alloc=#{alloc { Doc.from_xml(DOC.to_xml) }}"
+  puts "from_json_alloc=#{alloc { Doc.from_json(DOC.to_json) }}"
+end

data/bench/bench_common.rb

@@ -12,6 +12,17 @@
 #   bundle exec ruby bench/bench_uniword.rb
 
 require "bundler/setup"
+
+# TODO.perf/15: run any benchmark with PLAN_COMPILE_STATS=1 to append
+# the plan-compiler opt-out histogram (which clauses keep a corpus on
+# the interpretive path) after the benchmark output.
+if ENV["PLAN_COMPILE_STATS"]
+  at_exit do
+    require "pp"
+    puts "\nPlanCompiler opt-out histogram:"
+    pp(Lutaml::Xml::Leptris::PlanCompiler.plan_stats)
+  end
+end
 require "benchmark"
 require "fileutils"
 

data/bench/bench_merge_attempts.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# lutaml-model#834: merge N benchmark-attempt JSONs into one result set,
+# taking the per-fixture minimum of every metric. Contention inflates
+# timings; the minimum across attempts is the least-interfered
+# measurement, so gates evaluated on merged output misfire only when
+# EVERY attempt was slow.
+#
+# Usage: ruby bench_merge_attempts.rb <merged.json> <attempt1.json> [attempt2.json ...]
+#
+# Attempt files may be missing (crashed attempt): missing files are
+# skipped; if none exist, nothing is written and the caller's compare
+# step fails on the missing merged file.
+if ARGV.length < 3
+  warn "Usage: #{$PROGRAM_NAME} <merged.json> <attempt1.json> [attempt2.json ...]"
+  exit 1
+end
+
+merged_path = ARGV[0]
+attempt_paths = ARGV[1..]
+
+require "json"
+
+best = {}
+attempt_paths.each do |path|
+  next unless File.exist?(path)
+
+  results = JSON.parse(File.read(path))
+  results.each do |label, metrics|
+    cur = best[label]
+    if cur
+      cur["avg_time"] = [cur["avg_time"], metrics["avg_time"]].min
+      cur["min_time"] = [cur["min_time"], metrics["min_time"]].min
+      cur["max_time"] = [cur["max_time"], metrics["max_time"]].min
+      cur["allocations"] = [cur["allocations"], metrics["allocations"]].min
+      cur["ips"] = [cur["ips"], metrics["ips"]].max
+    else
+      best[label] = metrics.dup
+    end
+  end
+end
+
+if best.nil? || best.empty?
+  warn "No attempt JSONs found among: #{attempt_paths.join(', ')}"
+  exit 1
+end
+
+File.write(merged_path, JSON.pretty_generate(best))
+puts "Merged #{attempt_paths.size} attempt file(s) into #{merged_path} (#{best.size} fixtures)"

data/docs/_guides/gem-integration.adoc

@@ -0,0 +1,85 @@
+---
+title: Integrating lutaml-model in a Gem
+nav_order: 21
+---
+
+= Integrating lutaml-model in a gem
+
+For gem authors, the integration contract is simple: **depend on
+`lutaml-model` and nothing else format-specific.** Every XML, YAML,
+JSON, and TOML engine is resolved at runtime, and the standard
+adapters (Nokogiri through moxml, Psych, the `json` gem, toml-rb
+compatible engines) cover a working default everywhere.
+
+== Declaring the dependency
+
+[source,ruby]
+----
+spec.add_dependency "lutaml-model", "~> 0.8"
+----
+
+Do not add Nokogiri, Ox, Oga, leptris, yeptris, or teptris to your
+gemspec. All engines are optional at runtime:
+
+* when an engine gem is in the end user's bundle, the matching
+  adapters prefer it (see the
+  link:../native-engines[native engines guide]);
+* when it is not, adapters fall back to the standard engine for
+  that format — parsing and generation semantics are identical,
+  error classes are re-raised as their standard-library equivalents.
+
+There is no code path to write, no require order to respect, and no
+capability probe to perform in your gem.
+
+== Testing across adapters
+
+Your test suite should exercise the adapters your users may run.
+Lutaml::Model's own suite parameterizes the XML adapter through an
+environment variable; the same shape works downstream:
+
+[source,ruby]
+----
+ADAPTER = ENV.fetch("XML_ADAPTER", "nokogiri").to_sym
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    Lutaml::Model::Config.xml_adapter_type = ADAPTER
+  end
+end
+----
+
+Run the matrix in CI — one leg per adapter the standard runners can
+install:
+
+[source,sh]
+----
+XML_ADAPTER=nokogiri bundle exec rspec
+XML_ADAPTER=ox bundle exec rspec
+XML_ADAPTER=leptris bundle exec rspec   # requires the leptris gem in that leg's bundle
+----
+
+Engine gems belong in the CI *Gemfile* (a `group :test` entry or a
+separate CI gemfile), never in the gemspec. Start with the primary
+adapter (Nokogiri) and enable further legs incrementally as they
+pass — the same "adapter-first" strategy this library's own suite
+uses.
+
+== Semantics your users can rely on
+
+* Adapter choice never changes results: the plan fast path and the
+  interpretive pipeline produce identical output; on engines below
+  a capability floor the affected models parse interpretively
+  rather than degrade (see the version-floor note in the
+  link:../native-engines[native engines guide]).
+* Parse failures raise the standard error classes wrapped as
+  `Lutaml::Model::InvalidFormatError` on every engine — code that
+  rescues those classes works regardless of the bundle.
+
+== Rules of thumb
+
+* Gemspec: `lutaml-model` only. CI gemfiles: the engines you test.
+* Expose format options you want to forward (pretty printing,
+  encoding) — never the adapter itself.
+* If you ship models for multiple schema versions, see
+  link:../type-registers-contexts[type registers and contexts] for
+  per-version trees and substitution.

data/docs/_guides/grammar-backed-formats.adoc

@@ -0,0 +1,69 @@
+= Grammar-backed string formats
+
+A serialization format whose input is a *grammar*, not a data structure:
+identifier strings, query languages, DSLs — text that is parsed, not
+decoded. lutaml-model supports registering these as first-class formats
+through the same `FormatRegistry` extension point as xml/json/yaml; the
+parse side is implemented by a grammar engine (the reference
+implementation is https://github.com/parsanol/parsanol-ruby[Parsanol]'s
+`Parsanol::PARG::Lutaml.register`, which consumes a compiled PARG
+artifact plus its bindings).
+
+== The contract
+
+A grammar-backed format needs three things:
+
+* a *parse* — text → attribute hash (the grammar engine's job)
+* *bindings* — capture names → model attributes (the artifact's
+  bindings section)
+* a *model class* — a regular `Serializable` with attributes; no
+  hand-written `from_h`/`to_h` anywhere
+
+== Reference implementation (Parsanol)
+
+[source,ruby]
+----
+require "parsanol/parg/lutaml"
+
+Parsanol::PARG::Lutaml.register(
+  IsoIdentifier,
+  format_name: :pubid_iso,
+  artifact: "artifacts/iso.json", # compiled grammar + bindings + tests
+  entry: "identifier",
+)
+
+IsoIdentifier.from_pubid_iso("ISO/IEC 12345-1:2020")
+# => #<IsoIdentifier number: "12345-1", year: 2020, ...>
+----
+
+What `register` does:
+
+. loads the checksummed artifact (parse failures raise the engine's
+  error type — register it via `error_types:` so users can rescue it);
+. registers the format through `FormatRegistry.register` with an
+  adapter whose `parse` is artifact-parse-then-bind;
+. defines `from_<format>` on the model class.
+
+The artifact is the parser of record: it carries the grammar, the
+bindings, and the conformance tests (the grammar's own test block is
+baked in and can be re-run by consumers), and its checksum pins the
+pinned version of the language.
+
+== Writing the grammar side
+
+Grammars are authored in PARG (`.parg` — ABNF-flavoured surface, PEG
+semantics, one rule per line) and compiled with the `parsanol` CLI:
+
+----
+parsanol compile grammars/iso.parg --tables tables
+----
+
+The compile-time lint rejects left recursion and shadowed
+alternatives; the embedded test block runs at compile time, so a
+grammar that stops accepting its documented inputs fails the build
+rather than the consumer.
+
+== See also
+
+* parsanol-ruby `docs/pg-language-guide.md` — the PARG language
+* `Parsanol::PARG::Lutaml.register` — the bridge (reference implementation)

data/docs/_guides/index.adoc

@@ -26,9 +26,15 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 == Advanced mapping
 
 * link:../advanced-mapping[Advanced Attribute Mapping] - Same-name dispatch on attribute values (`when_attribute`), grouped declarations, custom methods, delegation
+* link:../grammar-backed-formats[Grammar-Backed String Formats] - Register a grammar engine as a serialization format (identifier strings, DSLs)
 
-== Performance
+== Model architecture and integration
+
+* link:../type-registers-contexts[Type Registers and Contexts] - Multi-version class trees, derived contexts, and model substitution
+* link:../gem-integration[Integrating lutaml-model in a Gem] - Dependency contract, adapter deferral, cross-adapter testing
 
+== Performance
+/
 * link:../native-engines[Native engines (leptris / yeptris / teptris)] - Drop-in XML/YAML/JSON/TOML engine upgrades via bundle opt-in
 
 == Linked Data serialization
@@ -47,6 +53,7 @@ See link:../references/rdf-namespaces[RDF Namespaces] for namespace classes,
 * link:../value-transformations[Value Transformations] - Transform values during serialization
 * link:../missing-values-handling[Missing Values Handling] - Handle nil/empty/omitted
 * link:../advanced-mapping[Advanced Mapping] - Custom methods and delegation
+* link:../grammar-backed-formats[Grammar-Backed String Formats] - Grammar engines as serialization formats
 * link:../schema-generation[Schema Generation] - Generate schemas from models
 * link:../creating-xsd[Creating XSD Schemas] - Complete reference for XSD generation from LutaML models
 * link:../schema-import[Schema Import] - Import schemas to create models