lutaml-model 0.8.98 → 0.8.99

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f7cb26a9f87fbfe0feb461b25dd3e8b50e32d64bbbd32b23f848e96355965b
-  data.tar.gz: 1961e58a64424ca1d69181f3e873d107e8f1d8762f1d1155c1de953c883ceaa1
+  metadata.gz: 41d8d37a85f86f8d8f30d632c36526fe311ba0156f01a096a15717627f29ec72
+  data.tar.gz: f15221cd4017756a1045502f77b588df6ae8f3e62ff39b38ac10c8d6f4a68115
 SHA512:
-  metadata.gz: 8624d39f5b4d556f6c72e7f76fa6ab262490a1583d5776756373dd4ea220bb1ba89e3f57f7774efa8f5f8c16f631f312ac149ed93ed651c15223068265bea629
-  data.tar.gz: 1249cac19b6f80880f5eb0c29cb0b2df17ff5813021573f6c2b63c923f6b2d63d2f579b9d14ebf18b8dae774df208787cef61cbfc507848fd99afffbc28b1404
+  metadata.gz: 509fc9f6462f37013113fdcb7a582ca70e9ce0ff021b51c780f9afdd66c03ec2c62213bd0c76a680dc993db138182b7260ed821757b37946b2b61941e2b9b066
+  data.tar.gz: e01bb47f5085c77f6ce840f31ac4f9f243271846267f1083c2c099cfae7f2ced2979f73a61a3a44ea0b0d609b9176a6e8d64e8841994c794382fd0a16c0880f2

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/index.adoc

@@ -28,8 +28,13 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * 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

data/docs/_guides/type-registers-contexts.adoc

@@ -0,0 +1,126 @@
+---
+title: Type Registers and Contexts
+nav_order: 20
+---
+
+= Type registers and contexts
+
+Lutaml::Model resolves every attribute type — Symbol or class —
+through a per-application *register*: a named table of types scoped
+so that different class trees can share mapping definitions without
+colliding. Registers are the mechanism behind multi-version model
+suites and model substitution.
+
+== Registers
+
+A register maps type ids to classes. Classes declare the register
+they belong to:
+
+[source,ruby]
+----
+module MyModels
+  class Mi < Lutaml::Model::Serializable
+    def self.lutaml_default_register
+      :my_models
+    end
+  end
+end
+----
+
+Symbol attribute types resolve in the declaring class's register,
+so the same symbol can mean different classes per tree — the
+multi-version pattern below builds on this.
+
+== Contexts: derived registers with substitutions
+
+A *context* is a derived type-resolution scope: it carries a
+registry, fallback registers, and — the part that powers model
+substitution — a list of type substitutions. Contexts are created
+through the global registry:
+
+[source,ruby]
+----
+Lutaml::Model::GlobalContext.create_context(
+  id: :custom_models,
+  fallback_to: [:my_models],
+  substitutions: [
+    { from_type: MyModels::Mover, to_type: Overset },
+  ],
+)
+
+instance = MyModels::Math.from_xml(xml, context: :custom_models)
+instance.mover_value.first # => #<Overset>
+----
+
+Every attribute whose type resolves to `MyModels::Mover` — at any
+depth of the tree — hydrates `Overset` in that context. Substitution
+is type-based, so "swap this class everywhere it is referenced" and
+"swap it only inside this one path" are the same operation scoped by
+context: create two contexts with different substitution lists.
+
+Contexts are cheap and disposable:
+
+[source,ruby]
+----
+Lutaml::Model::GlobalContext.unregister_context(:custom_models)
+----
+
+=== The custom-models convenience
+
+A whole-table convenience reads exactly like a class-swap hash and
+derives the context for you:
+
+[source,ruby]
+----
+models = { MyModels::Mover => Overset, MyModels::Mi => BoldMi }
+Lutaml::Model::GlobalContext.create_context(
+  id: :custom, fallback_to: [:my_models],
+  substitutions: models.map { |from, to| { from_type: from, to_type: to } },
+)
+MyModels::Math.from_xml(xml, context: :custom)
+----
+
+Substitute classes should inherit from the class they replace (or
+provide its full attribute surface) so mappings and serialization
+keep working.
+
+=== Substituting a symbol entry instead of a class
+
+Registers accept direct class registrations under a type id — useful
+when a tree declares `attribute :row, :row` and you want the symbol
+to resolve to your own class within a derived register:
+
+[source,ruby]
+----
+derived = Lutaml::Model::Register.new(:derived, fallback: [:my_models])
+derived.register_model(NewRow, id: :row)
+MyModels::Doc.from_xml(xml, register: derived)
+----
+
+(`register:` is the pre-context spelling; prefer `context:` with
+substitutions in new code.)
+
+== Multi-version class trees
+
+The flagship pattern combines registers with per-version classes
+and shared mapping modules:
+
+* a `Base::Mrow` module holds the mapping DSL once;
+* each version declares `class Mrow` mixing the module in and
+  pointing `lutaml_default_register` at its version's register;
+* attributes use symbol types, so `attribute :mrow, :mrow` means
+  the right class per tree;
+* a substitution context swaps individual classes for one call
+  without re-opening or redefining anything.
+
+Nothing re-opens generated classes, and each version's tree stays
+independent — no hidden delegation.
+
+== Rules of thumb
+
+* Prefer contexts over global configuration: substitutions scoped
+  to a context cannot leak into other resolutions.
+* Substitute classes should inherit the original; substitution then
+  preserves every mapping declared on the base.
+* Clean up exploratory contexts with `unregister_context` in test
+  teardowns — contexts are global state.

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.98"
+    VERSION = "0.8.99"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.98
+  version: 0.8.99
 platform: ruby
 authors:
 - Ribose Inc.
@@ -207,6 +207,7 @@ files:
 - docs/_guides/creating-xsd.adoc
 - docs/_guides/custom-methods.adoc
 - docs/_guides/document-validation.adoc
+- docs/_guides/gem-integration.adoc
 - docs/_guides/grammar-backed-formats.adoc
 - docs/_guides/index.adoc
 - docs/_guides/jsonld-serialization.adoc
@@ -220,6 +221,7 @@ files:
 - docs/_guides/schema-generation.adoc
 - docs/_guides/schema-import.adoc
 - docs/_guides/turtle-serialization.adoc
+- docs/_guides/type-registers-contexts.adoc
 - docs/_guides/value-transformations.adoc
 - docs/_guides/xml-mapping.adoc
 - docs/_guides/xml-mappings-guide.adoc