metanorma-plugin-lutaml 0.7.39 → 0.7.40

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad20f1059d6fb886f3b8f8e209a5eb2053bd84cf197b4df0a6f28c32ceb05b76
-  data.tar.gz: ea0e8cdfdc56ada195921fbefff8256f67e702dba4685a001ba22051031bfc74
+  metadata.gz: ab934a775aa2b0aa6abeb544d5dcaf3c4c8fcf37daa75119d5ba9d57a09196e8
+  data.tar.gz: ca930ec2f902c975ffaecc0b5bdd2fb15ad8e68f4dfb72cce3626cd54d9cc560
 SHA512:
-  metadata.gz: a72753313c88e6a7bc1388c764fe2f315faf4ff7447690dd5d6a8851f5fe15285d1b53629ff6c79db3ba53ec20e7cdb9d05242e1ef2b5e9fe7b6e69076cedad0
-  data.tar.gz: 98fbf0c36b867aae35acf710853ea74506bfc7835e8ed4368e9acedc84fe9f622f2cc44aae66fabc75bd49c9242487027d94239cec948972cf0e6117941e1ac2
+  metadata.gz: a6b32f1e6a256f7c548578fc324d25bfdf0c0a389233c02836178b95af7dca009723f72407fd8dab9f18761535915da9b665ab819bd6fdd8ee67ceae290d1139
+  data.tar.gz: dece27d9189a6b36ec3a0e80aa6c376eabcd8af181f52409f1d5ae559a85a7611eee30c4146a598a751dc26bbb7cf85482f540ca38dc767465a99013e914dee0

data/CLAUDE.md

@@ -39,10 +39,12 @@ All extensions follow the Asciidoctor extension API. The two main extension type
 
 ### Preprocessor Inheritance Hierarchy
 
-- `LutamlPreprocessor` — handles `[lutaml]`, `[lutaml_express]`, `[lutaml_express_liquid]` blocks. Parses EXPRESS files via the `lutaml`/`expressir` gems, builds Liquid contexts, and renders templates.
+- `BasePreprocessor` — abstract base for EXPRESS and XSD preprocessors. Uses Template Method pattern: subclasses implement `lutaml_liquid?`, `load_lutaml_file`, `index_type_name` and may override `update_repo`, `template`, `reorder_schemas`.
+- `LutamlPreprocessor` < `BasePreprocessor` — handles `[lutaml]`, `[lutaml_express]`, `[lutaml_express_liquid]` blocks. Adds EXPRESS-specific `update_repo` (cache unwrap, remark decoration), Liquid environment with custom tags/filters, schema reordering.
+- `LutamlXsdPreprocessor` < `BasePreprocessor` — handles `[lutaml_xsd]` blocks. Parses XSD files via `lutaml-model`, double-newline template joins for Asciidoctor paragraph breaks.
 - `LutamlUmlDatamodelDescriptionPreprocessor` and `LutamlEaXmiPreprocessor` — both include `LutamlEaXmiBase`, which handles XMI parsing via `lutaml` gem and renders using bundled Liquid templates.
 - `LutamlXmiUmlPreprocessor` — another XMI-based preprocessor with its own macro regex.
-- `BaseStructuredTextPreprocessor` — base for `[yaml2text]`, `[json2text]`, `[data2text]` blocks. Its subclasses (`Yaml2TextPreprocessor`, `Json2TextPreprocessor`, `Data2TextPreprocessor`) differ only in how they load content (YAML vs JSON vs auto-detect). The `Content` module provides the actual parsing logic.
+- `BaseStructuredTextPreprocessor` — base for `[yaml2text]`, `[json2text]`, `[data2text]` blocks. Its subclasses (`Yaml2TextPreprocessor`, `Json2TextPreprocessor`, `Data2TextPreprocessor`) differ only in how they load content (YAML vs JSON vs auto-detect).
 
 ### Key Shared Modules
 
@@ -71,8 +73,10 @@ Tests use `metanorma-standoc` as the backend. The spec helper registers all exte
 
 ## Key Dependencies
 
-- `lutaml` — core LutaML parser/model library (EXPRESS, UML, XMI formats)
+- `lutaml` — core LutaML parser/model library (EXPRESS, UML, XMI, XSD formats)
+- `lutaml-model` — LutaML serialization framework (provides XSD parsing, Liquid drops)
 - `expressir` — EXPRESS schema parser
 - `ogc-gml` — OGC GML dictionary parser
 - `liquid` — template rendering engine
 - `asciidoctor` — document processing framework
+- `canon` — semantic XML comparison for test assertions

data/Gemfile

@@ -12,7 +12,12 @@ rescue StandardError
   nil
 end
 
-gem "rake", "~> 13"
+gem "canon"
+gem "html2doc", github: "metanorma/html2doc", branch: "main"
+gem "lutaml"
+gem "metanorma", github: "metanorma/metanorma", branch: "main"
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+gem "rake"
 gem "rspec"
 gem "rspec-html-matchers"
 gem "rubocop"
@@ -23,3 +28,4 @@ gem "simplecov"
 gem "timecop"
 gem "vcr"
 gem "webmock"
+

data/README.adoc

@@ -14,6 +14,7 @@ within a Metanorma document:
 * Enterprise Architect exported UML files in XMI format (`*.xmi`)
 * LutaML GML Dictionary files (`*.xml`)
 * JSON or YAML files (`*.json|*.yml|*.yaml`)
+* XML Schema files (`*.xsd`)
 
 == Installation
 
@@ -34,6 +35,8 @@ link:docs/usages/lutaml-gml.adoc[Usage with LutaML GML Dictionary by lutaml_gml_
 
 link:docs/usages/json_yaml.adoc[Usage with JSON or YAML files by data2text, yaml2text or json2text]
 
+link:docs/usages/lutaml-xsd.adoc[Usage with XML Schema files by lutaml_xsd]
+
 == Documentation
 
 Please refer to https://www.metanorma.org.

data/docs/usages/lutaml-xsd.adoc

@@ -0,0 +1,94 @@
+== Usage with LutaML XSD
+
+=== Overview
+
+The `lutaml_xsd` macro parses *XML Schema (XSD)* files through `lutaml-model`
+and exposes the parsed schema object to *Liquid* templates.
+
+=== Syntax
+
+[source,adoc]
+-----
+[lutaml_xsd,<path_to_xsd>,<context_name>[, option1=value1, option2=value2, ...]]
+----
+<your Liquid template here>
+----
+-----
+
+* `<path_to_xsd>`: Path to the XSD file to be processed.
+* `<context_name>`: The name of the context variable to use in the template.
+* `option1=value1, ...`: Optional parameters (<<options,supported options>>).
+
+[[options]]
+=== Options
+
+* `location`: Base URL or path for resolving `<xs:import>` and `<xs:include>`
+  statements in the XSD. When omitted, the directory of `<path_to_xsd>` is used.
+
+=== Liquid Template Context
+
+The context variable (e.g., `unitsml`) exposes the parsed
+`Lutaml::Xml::Schema::Xsd::Schema` object through its Liquid drop.
+
+Commonly used schema collections:
+
+* `element`: List of elements defined in the XSD.
+* `complex_type`: List of complex types defined in the XSD.
+* `simple_type`, `attribute`, `attribute_group`, `group`, `import`, and
+  `include`: Other schema components exposed by `lutaml-model`.
+
+Commonly used helpers:
+
+* `elements_sorted_by_name`, `complex_types_sorted_by_name`,
+  `attribute_groups_sorted_by_name`: Sorted schema collections.
+* `used_by`, `child_elements`, `attribute_elements`, and `referenced_type`:
+  Component helpers exposed by parsed XSD objects.
+
+=== Example: Listing Elements and Complex Types
+
+[source,adoc]
+-----
+= Elements
+[lutaml_xsd,path/to/unitsml.xsd,unitsml]
+----
+{% for element in unitsml.elements_sorted_by_name %}
+Name: *{{ element.name }}*
+Type: *{{ element.type }}*
+Used by: {{ element.used_by | map: "name" | join: ", " }}
+{% endfor %}
+----
+
+= ComplexTypes
+[lutaml_xsd,path/to/unitsml.xsd,unitsml]
+----
+{% for complex_type in unitsml.complex_types_sorted_by_name %}
+Name: *{{ complex_type.name }}*
+Children: {{ complex_type.child_elements | map: "name" | join: ", " }}
+Attributes: {{ complex_type.attribute_elements | map: "name" | join: ", " }}
+{% endfor %}
+----
+-----
+
+=== Example: Using with Remote XSD and Options
+
+[source,adoc]
+-----
+[lutaml_xsd,path/to/omml.xsd,omml, location=https://raw.githubusercontent.com/t-yuki/ooxml-xsd/refs/heads/master]
+----
+{% for element in omml.element %}
+Name: *{{ element.name }}*
+Type: *{{ element.type }}*
+{% endfor %}
+----
+-----
+
+=== Use Cases
+
+* Generate documentation for XML schemas.
+* Extract and list schema elements and types or other details.
+* Customize output using Liquid templates.
+
+=== Notes
+
+* The macro supports local files at `<path_to_xsd>`.
+* You can use all standard *Liquid* template features for formatting and logic.

data/lib/metanorma/plugin/lutaml/base_preprocessor.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "asciidoctor"
+require "asciidoctor/reader"
+require "metanorma/plugin/lutaml/utils"
+require "metanorma/plugin/lutaml/asciidoctor/preprocessor"
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      # Base preprocessor for LutaML format-specific preprocessors.
+      #
+      # Subclasses must implement:
+      #   - #lutaml_liquid?(line) — match the macro header line
+      #   - #load_lutaml_file(document, file_path, options)
+      #     parse format-specific input
+      #
+      # Subclasses may override:
+      #   - #index_type_name — human-readable format name for error messages
+      #   - #update_repo(options, repo) — transform parsed repo before rendering
+      #   - #template(lines) — parse Liquid template lines
+      #   - #reorder_schemas(repo_liquid, options) — reorder/filter schemas
+      class BasePreprocessor < ::Asciidoctor::Extensions::Preprocessor
+        include Utils
+
+        def process(document, reader)
+          input_lines = Asciidoctor::PreprocessorNoIfdefsReader
+            .new(document, reader.lines).readlines.to_enum
+
+          express_indexes = Utils.parse_document_express_indexes(
+            document, input_lines
+          )
+
+          result_content = process_input_lines(
+            document: document,
+            input_lines: input_lines,
+            express_indexes: express_indexes,
+          )
+
+          Asciidoctor::PreprocessorNoIfdefsReader.new(document, result_content)
+        end
+
+        protected
+
+        def load_lutaml_file(_document, _file_path, _options)
+          raise NotImplementedError,
+                "#{self.class}#load_lutaml_file must be implemented"
+        end
+
+        def lutaml_liquid?(_line)
+          raise NotImplementedError,
+                "#{self.class}#lutaml_liquid? must be implemented"
+        end
+
+        def index_type_name
+          raise NotImplementedError,
+                "#{self.class}#index_type_name must be implemented"
+        end
+
+        def update_repo(_options, repo)
+          repo
+        end
+
+        def template(lines)
+          ::Liquid::Template.parse(lines.join("\n"))
+        end
+
+        def reorder_schemas(repo_liquid, _options)
+          repo_liquid
+        end
+
+        def index_missing_message(path)
+          "Unable to load #{index_type_name} file for `#{path}`, " \
+            "please specify the full path."
+        end
+
+        private
+
+        def process_input_lines(document:, input_lines:, express_indexes:)
+          result = []
+          loop do
+            result.push(
+              *process_text_blocks(document, input_lines, express_indexes),
+            )
+          end
+          result
+        end
+
+        def process_text_blocks(document, input_lines, express_indexes) # rubocop:disable Metrics/AbcSize
+          line = input_lines.next
+          block_header_match = lutaml_liquid?(line)
+
+          return [line] unless block_header_match
+
+          index_names = block_header_match[:index_names].split(";").map(&:strip)
+          context_name = block_header_match[:context_name].strip
+          options = (block_header_match[:options] &&
+            parse_options(block_header_match[:options].to_s.strip)) || {}
+
+          end_mark = input_lines.next
+
+          render_liquid_template(
+            document: document,
+            lines: extract_block_lines(input_lines, end_mark),
+            index_names: index_names,
+            context_name: context_name,
+            options: options,
+            indexes: express_indexes,
+          )
+        end
+
+        def extract_block_lines(input_lines, end_mark)
+          block = []
+          while (block_line = input_lines.next) != end_mark
+            block.push(block_line)
+          end
+          block
+        end
+
+        # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/ParameterLists
+        def gather_context_liquid_items(index_names:, document:,
+                                        indexes:, options: {})
+          index_names.map do |path|
+            if indexes[path] && indexes[path][:model]
+              repo = indexes[path][:model]
+              repo = update_repo(options, repo)
+              indexes[path][:liquid_drop] ||= repo.to_liquid
+            else
+              full_path = Utils.relative_file_path(document, path)
+              unless File.file?(full_path)
+                raise StandardError, index_missing_message(path)
+              end
+
+              repo = load_lutaml_file(document, path, options)
+              repo = update_repo(options, repo)
+              indexes[path] = { liquid_drop: repo.to_liquid }
+            end
+
+            indexes[path]
+          end
+        end
+        # rubocop:enable Metrics/AbcSize,Metrics/MethodLength,Metrics/ParameterLists
+
+        def render_liquid_template(document:, lines:, context_name:, # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/ParameterLists
+                                   index_names:, options:, indexes:)
+          options = process_options(document, options)
+
+          all_items = gather_context_liquid_items(
+            index_names: index_names, document: document, indexes: indexes,
+            options: options.merge("document" => document)
+          )
+
+          include_paths = [Utils.relative_file_path(document, "")]
+          options["include_path"]&.split(",")&.each do |path|
+            include_paths.push(Utils.relative_file_path(document, path))
+          end
+
+          file_system = ::Metanorma::Plugin::Lutaml::Liquid::LocalFileSystem
+            .new(include_paths, ["%s.liquid", "_%s.liquid", "_%s.adoc"])
+
+          parsed_template = template(lines)
+          parsed_template.registers[:file_system] = file_system
+
+          all_items.map do |item|
+            parsed_template.assigns[context_name] = item[:liquid_drop]
+            parsed_template.assigns["ordered_schemas"] = reorder_schemas(
+              item[:liquid_drop], options
+            )
+            parsed_template.assigns["schemas_order"] =
+              options["selected_schemas"]
+            parsed_template.render
+          end.flatten
+        rescue StandardError => e
+          ::Metanorma::Util.log(
+            "[#{self.class.name}] Failed to parse LutaML block: #{e.message}",
+            :error,
+          )
+          raise e
+        end
+
+        def process_options(document, options)
+          if (config_yaml_path = options.delete("config_yaml"))
+            config = read_config_yaml_file(document, config_yaml_path)
+            if config["selected_schemas"]
+              options["selected_schemas"] =
+                config["selected_schemas"]
+            end
+          end
+          options
+        end
+
+        def read_config_yaml_file(document, file_path) # rubocop:disable Metrics/MethodLength
+          return {} unless file_path
+
+          relative_file_path = Utils.relative_file_path(document, file_path)
+          config_yaml = YAML.safe_load(
+            File.read(relative_file_path, encoding: "UTF-8"),
+          )
+
+          return {} unless config_yaml["schemas"]
+
+          unless config_yaml["schemas"].is_a?(Hash)
+            raise StandardError,
+                  "[lutaml_express_liquid] attribute `config_yaml` must " \
+                  "point to a YAML file with the `schemas` key as a hash."
+          end
+
+          { "selected_schemas" => config_yaml["schemas"].keys }
+        end
+
+        def parse_options(options_string)
+          options_string
+            .to_s
+            .scan(/,\s*([^=]+?)=(\s*[^,]+)/)
+            .to_h { |elem| elem.map(&:strip) }
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb

@@ -490,7 +490,9 @@ module Metanorma
         def serialize_klass_drop_by_name(xmi_path, name, document = nil,
 guidance = nil)
           parser, uml_doc = build_uml_document(xmi_path, document)
-          raw_klass = find_packaged_klass(parser.xmi_index, name)
+          root_model_name = parser.xmi_root_model.model.name
+          raw_klass = find_packaged_klass(parser.xmi_index, name,
+                                          root_model_name: root_model_name)
           warn "Class not found for name: #{name}" if raw_klass.nil?
           klass = raw_klass && find_uml_node_by_xmi_id(
             uml_doc, raw_klass.id, :classes
@@ -550,11 +552,14 @@ guidance = nil)
           nil
         end
 
-        def find_packaged_klass(index, path)
-          segments = path.split("::")
+        def find_packaged_klass(index, path, root_model_name: nil)
+          segments = path.split("::").reject(&:empty?)
+          if root_model_name && segments.first == root_model_name
+            segments.shift
+          end
           if segments.one?
             index.find_packaged_by_name_and_types(
-              path, ["uml:Class", "uml:AssociationClass"]
+              segments.first, ["uml:Class", "uml:AssociationClass"]
             )
           else
             find_packaged_klass_by_path(index, segments)
@@ -563,20 +568,25 @@ guidance = nil)
 
         def find_packaged_klass_by_path(index, segments)
           klass_name = segments.pop
-          klass = index.find_packaged_by_name_and_types(
-            klass_name, ["uml:Class", "uml:AssociationClass"]
-          )
-          return unless klass
 
-          # Verify the path by walking up the parent chain
-          current = klass
-          segments.reverse_each do |pkg_name|
+          candidates = ["uml:Class", "uml:AssociationClass"]
+            .flat_map { |t| index.packaged_elements_of_type(t) }
+            .select { |e| e.name == klass_name }
+
+          candidates.find do |klass|
+            match_parent_chain?(index, klass, segments)
+          end
+        end
+
+        def match_parent_chain?(index, element, parent_segments)
+          current = element
+          parent_segments.reverse_each do |pkg_name|
             parent = index.find_parent(current.id)
-            return unless parent && parent.name == pkg_name
+            return false unless parent && parent.name == pkg_name
 
             current = parent
           end
-          klass
+          true
         end
 
         def find_packaged_enum(index, name)

data/lib/metanorma/plugin/lutaml/lutaml_preprocessor.rb

@@ -1,21 +1,15 @@
 # frozen_string_literal: true
 
-require "liquid"
-require "asciidoctor"
-require "asciidoctor/reader"
-require "lutaml"
-require "metanorma/plugin/lutaml/utils"
-require "metanorma/plugin/lutaml/asciidoctor/preprocessor"
 require "metanorma/plugin/lutaml/express_remarks_decorator"
 
 module Metanorma
   module Plugin
     module Lutaml
-      # Class for processing Lutaml files
-      class LutamlPreprocessor < ::Asciidoctor::Extensions::Preprocessor
-        include Utils
-
-        REMARKS_ATTRIBUTE = "remarks"
+      # Preprocessor for EXPRESS schema formats (lutaml, lutaml_express,
+      # lutaml_express_liquid). Parses EXPRESS files via the lutaml/expressir
+      # gems, decorates remarks with relative path resolution, and renders
+      # Liquid templates with the EXPRESS-specific Liquid environment.
+      class LutamlPreprocessor < BasePreprocessor
         EXPRESS_PREPROCESSOR_REGEX = %r{
           ^                            # Start of line
           \[                           # Opening bracket
@@ -30,117 +24,38 @@ module Metanorma
           \]                           # Closing bracket
         }x
 
-        def process(document, reader) # rubocop:disable Metrics/MethodLength
-          r = Asciidoctor::PreprocessorNoIfdefsReader.new(document,
-                                                          reader.lines)
-          input_lines = r.readlines.to_enum
-
-          express_indexes = Utils.parse_document_express_indexes(
-            document,
-            input_lines,
-          )
-
-          result_content = process_input_lines(
-            document: document,
-            input_lines: input_lines,
-            express_indexes: express_indexes,
-          )
-
-          Asciidoctor::PreprocessorNoIfdefsReader.new(document, result_content)
-        end
-
         protected
 
         def lutaml_liquid?(line)
           line.match(EXPRESS_PREPROCESSOR_REGEX)
         end
 
-        def load_express_lutaml_file(document, file_path)
-          ::Lutaml::Parser.parse(
-            File.new(
-              Utils.relative_file_path(document, file_path),
-              encoding: "UTF-8",
-            ),
-          )
-        end
-
-        private
+        def load_lutaml_file(document, file_path, _options)
+          full_path = Utils.relative_file_path(document, file_path)
 
-        def process_input_lines(document:, input_lines:, express_indexes:)
-          result = []
-          loop do
-            result.push(
-              *process_text_blocks(document, input_lines, express_indexes),
-            )
+          file = File.new(full_path, encoding: "UTF-8")
+          if full_path.end_with?(".exp")
+            ::Lutaml::Express::Parsers::Exp.parse(file)
+          else
+            ::Lutaml::Uml::Parsers::Dsl.parse(file)
           end
-          result
-        end
-
-        def process_text_blocks(document, input_lines, express_indexes) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
-          line = input_lines.next
-          block_header_match = lutaml_liquid?(line)
-
-          return [line] if block_header_match.nil?
-
-          index_names = block_header_match[:index_names].split(";").map(&:strip)
-          context_name = block_header_match[:context_name].strip
-
-          options = (block_header_match[:options] &&
-            parse_options(block_header_match[:options].to_s.strip)) || {}
-
-          end_mark = input_lines.next
-
-          render_liquid_template(
-            document: document,
-            lines: extract_block_lines(input_lines, end_mark),
-            index_names: index_names,
-            context_name: context_name,
-            options: options,
-            indexes: express_indexes,
-          )
         end
 
-        def extract_block_lines(input_lines, end_mark)
-          block = []
-          while (block_line = input_lines.next) != end_mark
-            block.push(block_line)
-          end
-          block
+        def index_type_name
+          "EXPRESS"
         end
 
-        def gather_context_liquid_items( # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/ParameterLists
-          index_names:, document:, indexes:, options: {}
-        )
-          index_names.map do |path| # rubocop:disable Metrics/BlockLength
-            if indexes[path] && indexes[path][:model]
-              repo = indexes[path][:model]
-              repo = update_repo(options, repo)
-              indexes[path][:liquid_drop] ||= repo.to_liquid
-            else
-              full_path = Utils.relative_file_path(document, path)
-              unless File.file?(full_path)
-                raise StandardError.new(
-                  "Unable to load EXPRESS index for `#{path}`, " \
-                  "please define it at `:lutaml-express-index:` or specify " \
-                  "the full path.",
-                )
-              end
-              repo = load_express_lutaml_file(document, path)
-              repo = update_repo(options, repo)
-              indexes[path] = {
-                liquid_drop: repo.to_liquid,
-              }
-            end
-
-            indexes[path]
-          end
+        def index_missing_message(path)
+          "Unable to load EXPRESS index for `#{path}`, " \
+            "please define it at `:lutaml-express-index:` or specify " \
+            "the full path."
         end
 
         def update_repo(options, repo)
-          # Unwrap repo if it's a cache
-          repo = repo.content if repo.is_a? Expressir::Model::Cache
+          repo = repo.content if repo.is_a?(Expressir::Model::Cache)
+          return repo unless repo.is_a?(Expressir::Model::Repository) ||
+            repo.is_a?(Expressir::Model::ExpFile)
 
-          # Process each schema
           repo.schemas.each do |schema|
             options["relative_path_prefix"] =
               relative_path_prefix(options, schema)
@@ -150,6 +65,25 @@ module Metanorma
           repo
         end
 
+        def template(lines)
+          ::Liquid::Template.parse(
+            lines.join("\n"),
+            environment: create_liquid_environment,
+          )
+        end
+
+        def reorder_schemas(repo_liquid, options)
+          return repo_liquid.schemas unless options["selected_schemas"]
+
+          options["selected_schemas"].filter_map do |schema_name|
+            repo_liquid.schemas.find do |schema|
+              schema.id == schema_name || schema.file_basename == schema_name
+            end
+          end
+        end
+
+        private
+
         def update_remarks(model, options)
           model.remarks = decorate_remarks(options, model.remarks)
           model.remark_items&.each do |ri|
@@ -157,127 +91,29 @@ module Metanorma
           end
 
           model.children.each do |child|
-            if child.respond_to?(:remarks) && child.respond_to?(:remark_items)
-              update_remarks(child, options)
-            end
+            next unless child.is_a?(Expressir::Model::ModelElement)
+
+            update_remarks(child, options)
           end
         end
 
         def relative_path_prefix(options, model)
-          return nil if options.nil? || options["document"].nil?
+          return if options.nil? || options["document"].nil?
 
           document = options["document"]
           file_path = File.dirname(model.file)
           docfile_directory = File.dirname(
             document.attributes["docfile"] || ".",
           )
-          document
-            .path_resolver
-            .system_path(file_path, docfile_directory)
+          document.path_resolver.system_path(file_path, docfile_directory)
         end
 
         def decorate_remarks(options, remarks)
           return [] unless remarks
 
           remarks.map do |remark|
-            ::Metanorma::Plugin::Lutaml::ExpressRemarksDecorator
-              .call(remark, options)
-          end
-        end
-
-        def read_config_yaml_file(document, file_path) # rubocop:disable Metrics/MethodLength
-          return {} if file_path.nil?
-
-          relative_file_path = Utils.relative_file_path(document, file_path)
-          config_yaml = YAML.safe_load(
-            File.read(relative_file_path, encoding: "UTF-8"),
-          )
-
-          return {} unless config_yaml["schemas"]
-
-          unless config_yaml["schemas"].is_a?(Hash)
-            raise StandardError.new(
-              "[lutaml_express_liquid] attribute `config_yaml` must point " \
-              "to a YAML file that has the `schemas` key containing a hash.",
-            )
+            ExpressRemarksDecorator.call(remark, options)
           end
-
-          { "selected_schemas" => config_yaml["schemas"].keys }
-        end
-
-        def render_liquid_template(document:, lines:, context_name:, # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/ParameterLists
-                      index_names:, options:, indexes:)
-          # Process options and configuration
-          options = process_options(document, options)
-
-          # Get all context items in one go
-          all_items = gather_context_liquid_items(
-            index_names: index_names, document: document, indexes: indexes,
-            options: options.merge("document" => document)
-          )
-
-          # Setup include paths for liquid templates
-          include_paths = [Utils.relative_file_path(document, "")]
-          options["include_path"]&.split(",")&.each do |path|
-            # resolve include_path relative to the document
-            include_paths.push(Utils.relative_file_path(document, path))
-          end
-
-          file_system = ::Metanorma::Plugin::Lutaml::Liquid::LocalFileSystem
-            .new(include_paths, ["%s.liquid", "_%s.liquid", "_%s.adoc"])
-
-          # Parse template once outside the loop
-          template = ::Liquid::Template
-            .parse(lines.join("\n"), environment: create_liquid_environment)
-          template.registers[:file_system] = file_system
-
-          # Render for each item
-          all_items.map do |item|
-            template.assigns[context_name] = item[:liquid_drop]
-            template.assigns["ordered_schemas"] = reorder_schemas(
-              item[:liquid_drop], options
-            )
-            template.assigns["schemas_order"] = options["selected_schemas"]
-            template.render
-          end.flatten
-        rescue StandardError => e
-          ::Metanorma::Util
-            .log("[LutamlPreprocessor] Failed to parse LutaML block: " \
-                 "#{e.message}", :error)
-          raise e
-        end
-
-        def reorder_schemas(repo_liquid, options)
-          return repo_liquid.schemas unless options["selected_schemas"]
-
-          ordered_schemas = []
-          options["selected_schemas"].each do |schema_name|
-            ordered_schema = repo_liquid.schemas.find do |schema|
-              schema.id == schema_name || schema.file_basename == schema_name
-            end
-            ordered_schemas.push(ordered_schema)
-          end
-
-          ordered_schemas
-        end
-
-        def process_options(document, options)
-          # Process config file if specified
-          if (config_yaml_path = options.delete("config_yaml"))
-            config = read_config_yaml_file(document, config_yaml_path)
-            if config["selected_schemas"]
-              options["selected_schemas"] =
-                config["selected_schemas"]
-            end
-          end
-          options
-        end
-
-        def parse_options(options_string)
-          options_string
-            .to_s
-            .scan(/,\s*([^=]+?)=(\s*[^,]+)/)
-            .to_h { |elem| elem.map(&:strip) }
         end
       end
     end

data/lib/metanorma/plugin/lutaml/lutaml_xsd_preprocessor.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "lutaml/xml/parsers/xsd"
+
+module Metanorma
+  module Plugin
+    module Lutaml
+      # Preprocessor for XSD (XML Schema Definition) files. Parses XSD via
+      # lutaml-model's XSD parser and exposes the schema object to Liquid
+      # templates.
+      #
+      # Caching: parsed XSD results are cached at two levels:
+      # - Class-level (@@xsd_cache) persists across document invocations
+      # - Document-level (document.attributes["lutaml_xsd_cache"]) within a
+      #   single document's processing
+      class LutamlXsdPreprocessor < BasePreprocessor
+        XSD_PREPROCESSOR_REGEX = %r{
+          ^                            # Start of line
+          \[                           # Opening bracket
+          (?:\blutaml_xsd\b)           # lutaml_xsd
+          ,                            # Comma separator
+          (?<index_names>[^,]+)?       # Optional index names
+          ,?                           # Optional comma
+          (?<context_name>[^,]+)?      # Optional context name
+          (?<options>,.*)?             # Optional options
+          \]                           # Closing bracket
+        }x
+
+        def initialize(_config = {})
+          super
+          @@xsd_cache ||= {}
+        end
+
+        protected
+
+        def lutaml_liquid?(line)
+          line.match(XSD_PREPROCESSOR_REGEX)
+        end
+
+        def load_lutaml_file(document, file_path, options)
+          full_path = Utils.relative_file_path(document, file_path)
+          location = xsd_location(full_path, options)
+          cache_key = [full_path, location]
+
+          cached = document_cache_entry(document, cache_key)
+          return cached if cached
+
+          result = @@xsd_cache[cache_key] ||=
+            parse_xsd_file(full_path, location)
+
+          set_document_cache_entry(document, cache_key, result)
+          result
+        end
+
+        def index_type_name
+          "XSD"
+        end
+
+        def index_missing_message(path)
+          "Unable to load XSD file for `#{path}`, please specify the full path."
+        end
+
+        def template(lines)
+          # XSD templates use double-newline joins to produce Asciidoctor
+          # paragraph breaks (single newlines are treated as continuation).
+          ::Liquid::Template.parse(
+            lines.join("\n\n"),
+            environment: create_liquid_environment,
+          )
+        end
+
+        private
+
+        def parse_xsd_file(full_path, location)
+          File.open(full_path, "r:UTF-8") do |file|
+            ::Lutaml::Xml::Parsers::Xsd.parse(file, location: location)
+          end
+        end
+
+        def xsd_location(full_path, options)
+          options["location"] || File.dirname(full_path)
+        end
+
+        def document_cache_entry(document, cache_key)
+          document.attributes["lutaml_xsd_cache"]&.[](cache_key)
+        end
+
+        def set_document_cache_entry(document, cache_key, result)
+          document.attributes["lutaml_xsd_cache"] ||= {}
+          document.attributes["lutaml_xsd_cache"][cache_key] = result
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/plugin/lutaml/utils.rb

@@ -183,8 +183,7 @@ module Metanorma
         end
 
         def load_express_repo_from_cache(path)
-          ::Lutaml::Parser
-            .parse(File.new(path), ::Lutaml::Parser::EXPRESS_CACHE_PARSE_TYPE)
+          ::Lutaml::Express::Parsers::Exp.parse_cache(path)
         end
 
         def save_express_repo_to_cache(path, repository, document)
@@ -202,10 +201,8 @@ module Metanorma
         end
 
         def load_express_from_folder(folder)
-          files = Dir["#{folder}/*.exp"].map do |nested_path|
-            File.new(nested_path, encoding: "UTF-8")
-          end
-          ::Lutaml::Parser.parse(files)
+          file_paths = Dir["#{folder}/*.exp"]
+          ::Expressir::Express::Parser.from_files(file_paths)
         end
 
         # TODO: Refactor this using Suma::SchemaConfig
@@ -220,16 +217,12 @@ module Metanorma
             schema_yaml_base_path = schema_yaml_base_path + root_schema_path
           end
 
-          files_to_load = yaml_content["schemas"].map do |key, value|
-            # If there is no path: set for a schema, we assume it uses the
-            # schema name as the #{filename}.exp.
+          file_paths = yaml_content["schemas"].map do |key, value|
             schema_path = Pathname.new(value["path"] || "#{key}.exp")
-
-            real_schema_path = schema_yaml_base_path + schema_path
-            File.new(real_schema_path.cleanpath.to_s, encoding: "UTF-8")
+            (schema_yaml_base_path + schema_path).cleanpath.to_s
           end
 
-          ::Lutaml::Parser.parse(files_to_load)
+          ::Expressir::Express::Parser.from_files(file_paths)
         end
 
         def parse_document_express_indexes(document, input_lines) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity

data/lib/metanorma/plugin/lutaml/version.rb

@@ -1,7 +1,7 @@
 module Metanorma
   module Plugin
     module Lutaml
-      VERSION = "0.7.39".freeze
+      VERSION = "0.7.40".freeze
     end
   end
 end

data/lib/metanorma-plugin-lutaml.rb

@@ -3,7 +3,9 @@ require "metanorma/plugin/lutaml/config"
 require "metanorma/plugin/lutaml/json2_text_preprocessor"
 require "metanorma/plugin/lutaml/yaml2_text_preprocessor"
 require "metanorma/plugin/lutaml/data2_text_preprocessor"
+require "metanorma/plugin/lutaml/base_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_preprocessor"
+require "metanorma/plugin/lutaml/lutaml_xsd_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor"
 require "metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor"

data/metanorma-plugin-lutaml.gemspec

@@ -26,14 +26,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.7.0" # rubocop:disable Gemspec/RequiredRubyVersion
+  spec.required_ruby_version = ">= 3.0.0" # rubocop:disable Gemspec/RequiredRubyVersion
 
   spec.add_dependency "asciidoctor"
   spec.add_dependency "coradoc", "~> 1.1.8"
-  spec.add_dependency "expressir", "~> 2.3", ">= 2.3.4"
+  spec.add_dependency "expressir", "~> 2.3", ">= 2.3.5"
   spec.add_dependency "isodoc"
   spec.add_dependency "liquid"
   spec.add_dependency "lutaml", "~> 0.10", ">= 0.10.12"
+  spec.add_dependency "lutaml-model", "~> 0.8.4"
   spec.add_dependency "ogc-gml", "~> 1.1"
   spec.add_dependency "relaton-cli"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-plugin-lutaml
 version: !ruby/object:Gem::Version
-  version: 0.7.39
+  version: 0.7.40
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-12 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -47,7 +47,7 @@ dependencies:
         version: '2.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.4
+        version: 2.3.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -57,7 +57,7 @@ dependencies:
         version: '2.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.4
+        version: 2.3.5
 - !ruby/object:Gem::Dependency
   name: isodoc
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +106,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.10.12
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.4
 - !ruby/object:Gem::Dependency
   name: ogc-gml
   requirement: !ruby/object:Gem::Requirement
@@ -160,9 +174,11 @@ files:
 - docs/usages/json_yaml.adoc
 - docs/usages/lutaml-gml.adoc
 - docs/usages/lutaml-uml.adoc
+- docs/usages/lutaml-xsd.adoc
 - docs/usages/xmi_to_uml.adoc
 - lib/metanorma-plugin-lutaml.rb
 - lib/metanorma/plugin/lutaml/asciidoctor/preprocessor.rb
+- lib/metanorma/plugin/lutaml/base_preprocessor.rb
 - lib/metanorma/plugin/lutaml/base_structured_text_preprocessor.rb
 - lib/metanorma/plugin/lutaml/config.rb
 - lib/metanorma/plugin/lutaml/config/guidance.rb
@@ -213,6 +229,7 @@ files:
 - lib/metanorma/plugin/lutaml/lutaml_table_inline_macro.rb
 - lib/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor.rb
 - lib/metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor.rb
+- lib/metanorma/plugin/lutaml/lutaml_xsd_preprocessor.rb
 - lib/metanorma/plugin/lutaml/parse_error.rb
 - lib/metanorma/plugin/lutaml/source_extractor.rb
 - lib/metanorma/plugin/lutaml/utils.rb
@@ -232,7 +249,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="