lutaml-model 0.8.98 → 0.8.100

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9f7cb26a9f87fbfe0feb461b25dd3e8b50e32d64bbbd32b23f848e96355965b
-  data.tar.gz: 1961e58a64424ca1d69181f3e873d107e8f1d8762f1d1155c1de953c883ceaa1
+  metadata.gz: 2bd54a574eb02eec487d980543835abb2bec61c12104d6eea6b898a516fb301f
+  data.tar.gz: ffc5d3ed5b0c6df7140839064baec52624a034b2d1c5cfdc764dc4ee78c199ce
 SHA512:
-  metadata.gz: 8624d39f5b4d556f6c72e7f76fa6ab262490a1583d5776756373dd4ea220bb1ba89e3f57f7774efa8f5f8c16f631f312ac149ed93ed651c15223068265bea629
-  data.tar.gz: 1249cac19b6f80880f5eb0c29cb0b2df17ff5813021573f6c2b63c923f6b2d63d2f579b9d14ebf18b8dae774df208787cef61cbfc507848fd99afffbc28b1404
+  metadata.gz: 191c5ee654cc6863a6f8d865448f0fbb29c31f7d602e3ab2a356148fdca7117b254aa497bb1ebdd80da1c80f495cf46c5f1029897cf87e7423a7409747e4e97c
+  data.tar.gz: 4b55a05f437df7e0c85c7545d2042990572c70a4d64b42d9ae3ee44950ca6875cd640c2089cd9620951264180556e2e3776e7b32028b1b1d9962cbdaad739ecb

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/schema-generation.adoc

@@ -901,3 +901,28 @@ The generated schema will include validation constraints:
   </define>
 </grammar>
 ----
+
+== Documentation metadata (desc)
+
+Models and attributes carry documentation strings through `desc` —
+set on the model class or on any `attribute` declaration, read back
+by documentation and schema tooling. Serialization is never affected
+by it.
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  desc "This is a title."
+
+  attribute :type, :string, desc: "This attribute is used for..."
+end
+
+Title.desc # => "This is a title."
+Title.attributes[:type].desc # => "This attribute is used for..."
+----
+
+Subclasses inherit the nearest ancestor's class description; an
+explicit `desc` overrides it. A consumer override-free `desc` value
+does not change any generated schema today — wiring `desc` into the
+generated `description` fields is deliberate product scope, not a
+free rider on this option.

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/attribute.rb

@@ -46,6 +46,7 @@ module Lutaml
         signed
         min_length
         max_length
+        desc
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -641,6 +642,12 @@ instance_object = nil)
         options[:pattern]
       end
 
+      # Documentation metadata (#356): the `:desc` attribute option,
+      # consumed by documentation and schema tooling.
+      def desc
+        options[:desc]
+      end
+
       # Performance: Frozen empty array to reduce allocations
       EMPTY_VALUES_ARRAY = [].freeze
 

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -505,6 +505,22 @@ module Lutaml
           end
         end
 
+        # Class-level documentation metadata (#356): `desc "text"` on
+        # the model class; a zero-argument call reads it back.
+        # Subclasses inherit the nearest ancestor's description — an
+        # explicit `desc` overrides. Consumed by documentation and
+        # schema tooling; the serialization paths never read it.
+        def desc(text = nil)
+          return @lutaml_desc = text if text
+
+          return @lutaml_desc if defined?(@lutaml_desc)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            superclass.desc
+          end
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name

data/lib/lutaml/model/version.rb

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

data/spec/lutaml/model/desc_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+RSpec.describe "Documentation metadata (desc)" do
+  let(:widget_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      desc "A widget."
+
+      attribute :name, :string, desc: "The widget name."
+      attribute :size, :integer
+    end
+  end
+
+  it "stores and reads the class-level description" do
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "returns nil when no description is set" do
+    plain = Class.new(Lutaml::Model::Serializable)
+    expect(plain.desc).to be_nil
+  end
+
+  it "inherits the description on subclasses" do
+    child = Class.new(widget_class)
+    expect(child.desc).to eq("A widget.")
+  end
+
+  it "lets a subclass override the description" do
+    child = Class.new(widget_class) do
+      desc "A special widget."
+    end
+    expect(child.desc).to eq("A special widget.")
+  end
+
+  it "does not leak an override back to the superclass" do
+    Class.new(widget_class) { desc "Child only." }
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "stores the attribute-level description" do
+    expect(widget_class.attributes[:name].desc).to eq("The widget name.")
+    expect(widget_class.attributes[:size].desc).to be_nil
+  end
+
+  it "keeps serialization untouched" do
+    widget = widget_class.new(name: "w", size: 3)
+    expect(widget.to_hash).to eq("name" => "w", "size" => 3)
+  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.100
 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
@@ -1740,6 +1742,7 @@ files:
 - spec/lutaml/model/deferred_type_no_materialize_spec.rb
 - spec/lutaml/model/delegation_spec.rb
 - spec/lutaml/model/derived_attribute_serialization_spec.rb
+- spec/lutaml/model/desc_spec.rb
 - spec/lutaml/model/dynamic_attribute_spec.rb
 - spec/lutaml/model/encoding_spec.rb
 - spec/lutaml/model/enum_spec.rb