metanorma-plugin-lutaml 0.7.38 → 0.7.40

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb242e5ff7bfcfa7b4baec472a6fc0ecf0be94558913c8bb39bcf19655640e12
-  data.tar.gz: 81455de9a154af7534d43830562613fbee00bd8ce2c252ce13be79fc790efaec
+  metadata.gz: ab934a775aa2b0aa6abeb544d5dcaf3c4c8fcf37daa75119d5ba9d57a09196e8
+  data.tar.gz: ca930ec2f902c975ffaecc0b5bdd2fb15ad8e68f4dfb72cce3626cd54d9cc560
 SHA512:
-  metadata.gz: c84b7143c72c6bbb6334bc9c27faea196a516edd34c67607579f61b0a371be648c9087e5b297159f98d60654f43ffc9a2c736a5e5c546196f7251917cc042d28
-  data.tar.gz: b68b53795e9576abc2e1beb3746219ae2ca0ab8e888ab15f0c79430f94eedb870a568fe425e9a3ae503ba34e03d603436cc2dcb0cd64068500d30db421e079e5
+  metadata.gz: a6b32f1e6a256f7c548578fc324d25bfdf0c0a389233c02836178b95af7dca009723f72407fd8dab9f18761535915da9b665ab819bd6fdd8ee67ceae290d1139
+  data.tar.gz: dece27d9189a6b36ec3a0e80aa6c376eabcd8af181f52409f1d5ae559a85a7611eee30c4146a598a751dc26bbb7cf85482f540ca38dc767465a99013e914dee0

data/.github/workflows/rake.yml

@@ -10,6 +10,10 @@ on:
 
 jobs:
   rake:
-    uses: metanorma/ci/.github/workflows/graphviz-rake.yml@main
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    with:
+      setup-tools: graphviz
+      submodules: true
+      choco-cache: true
     secrets:
       pat_token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}

data/.gitignore

@@ -5,4 +5,5 @@ test.err
 
 .rubocop-https--*
 .DS_Store
-.vscode
+.vscode
+*.log.txt

data/.rubocop.yml

@@ -1,10 +1,19 @@
 # Auto-generated by Cimas: Do not edit it manually!
 # See https://github.com/metanorma/cimas
 inherit_from:
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  - .rubocop_todo.yml
+
+inherit_mode:
+  merge:
+    - Exclude
 
 # local repo-specific modifications
 # ...
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 3.0

data/.rubocop_todo.yml

@@ -0,0 +1,238 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-05-12 14:53:16 UTC using RuboCop version 1.86.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Gemspec/RequireMFA:
+  Exclude:
+    - 'metanorma-plugin-lutaml.gemspec'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_klass_table_block_macro.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLines:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Exclude:
+    - 'Rakefile'
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+    - 'lib/metanorma/plugin/lutaml/lutaml_klass_table_block_macro.rb'
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor_spec.rb'
+    - 'spec/support/shared_examples/structured_data_2_text_preprocessor.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+    - 'lib/metanorma/plugin/lutaml/lutaml_klass_table_block_macro.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 19
+
+# Offense count: 2
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+
+# Offense count: 1
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+
+# Offense count: 2
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: infinite?, nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/asciidoctor/preprocessor.rb'
+    - 'lib/metanorma/plugin/lutaml/liquid/custom_filters/file_exist.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/AncestorsInclude:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/utils.rb'
+
+# Offense count: 86
+# Configuration parameters: Prefixes, AllowedPatterns.
+# Prefixes: when, with, without
+RSpec/ContextWording:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_enum_table_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_gml_dictionary_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_gml_dictionary_block_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_klass_table_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_text_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/macros_data2text_spec.rb'
+    - 'spec/support/shared_examples/structured_data_2_text_preprocessor.rb'
+
+# Offense count: 37
+# Configuration parameters: CountAsOne.
+RSpec/ExampleLength:
+  Max: 26
+
+# Offense count: 13
+# Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
+RSpec/IndexedLet:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_ea_diagram_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/macros_data2text_spec.rb'
+    - 'spec/support/shared_examples/structured_data_2_text_preprocessor.rb'
+
+# Offense count: 4
+# Configuration parameters: AssignmentOnly.
+RSpec/InstanceVariable:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_express_preprocessor_spec.rb'
+
+# Offense count: 44
+RSpec/LeakyLocalVariable:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_klass_table_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb'
+
+# Offense count: 14
+RSpec/MultipleExpectations:
+  Max: 6
+
+# Offense count: 9
+# Configuration parameters: AllowSubject.
+RSpec/MultipleMemoizedHelpers:
+  Max: 8
+
+# Offense count: 41
+# Configuration parameters: EnforcedStyle, IgnoreSharedExamples.
+# SupportedStyles: always, named_only
+RSpec/NamedSubject:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/config/root_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_gml_dictionary_block_macro_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_gml_dictionary_block_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/source_extractor_spec.rb'
+
+# Offense count: 117
+# Configuration parameters: AllowedGroups.
+RSpec/NestedGroups:
+  Max: 7
+
+# Offense count: 1
+RSpec/PendingWithoutReason:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_text_preprocessor_spec.rb'
+
+# Offense count: 2
+RSpec/RepeatedExampleGroupBody:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/macros_yaml2text_spec.rb'
+
+# Offense count: 6
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/lutaml_express_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_text_preprocessor_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/macros_data2text_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/macros_json2text_spec.rb'
+    - 'spec/metanorma/plugin/lutaml/macros_yaml2text_spec.rb'
+
+# Offense count: 1
+RSpec/SubjectDeclaration:
+  Exclude:
+    - 'spec/metanorma/plugin/lutaml/config/root_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantBegin:
+  Exclude:
+    - 'lib/metanorma/plugin/lutaml/lutaml_ea_xmi_base.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'metanorma-plugin-lutaml.gemspec'

data/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`metanorma-plugin-lutaml` is a Ruby gem that provides Asciidoctor extensions for the Metanorma document publishing system. It enables Metanorma documents to embed and render data models from multiple formats: EXPRESS (ISO 10303), LutaML DSL, Enterprise Architect XMI, GML Dictionaries, JSON, and YAML.
+
+## Build and Test Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake
+
+# Run a single test file
+bundle exec rspec spec/metanorma/plugin/lutaml/lutaml_preprocessor_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/metanorma/plugin/lutaml/lutaml_preprocessor_spec.rb:42
+
+# Lint
+bundle exec rubocop
+
+# Build the gem
+bundle exec rake build
+```
+
+## Architecture
+
+### Asciidoctor Extension Pattern
+
+All extensions follow the Asciidoctor extension API. The two main extension types are:
+
+- **Preprocessors** (`::Asciidoctor::Extensions::Preprocessor`): Process document text before rendering. They read input lines, detect custom block syntax (e.g., `[lutaml_express, ...]`), and replace them with rendered content via Liquid templates.
+- **Block/BlockMacro/InlineMacro extensions**: Handle `lutaml_diagram`, `lutaml_ea_diagram`, `lutaml_gml_dictionary`, `lutaml_klass_table`, `lutaml_enum_table`, `lutaml_table`, `lutaml_figure` — these are Asciidoctor block-level or inline macros.
+
+### Preprocessor Inheritance Hierarchy
+
+- `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).
+
+### Key Shared Modules
+
+- `Utils` (`lib/metanorma/plugin/lutaml/utils.rb`) — shared helpers: file path resolution relative to document, Liquid template rendering with custom environment/filters, EXPRESS repository loading with caching, parsing document-level `:lutaml-express-index:` attributes.
+- `LutamlEaXmiBase` — shared logic for XMI-based preprocessors: XMI document loading/caching, config YAML parsing, package filtering/sorting, Liquid context building, nested macro collection.
+- `LutamlDiagramBase` — shared logic for diagram block extensions: parses LutaML DSL, renders via Graphviz to PNG.
+- `LutamlGmlDictionaryBase` — parses GML XML via `ogc-gml` gem, renders via Liquid.
+- `SourceExtractor` — scans document lines for anchors (`[[id]]`, `[#id]`, `[id=...]`) and `include::`/`embed::` directives, extracting source blocks into `document.attributes["source_blocks"]` for later use by preprocessors.
+
+### Liquid Template System
+
+The plugin uses Liquid templates extensively. Key components:
+
+- **Custom Liquid environment** with registered `keyiterator` tag and custom filters (`html2adoc`, `values`, `replace_regex`, `loadfile`, `file_exist`).
+- **`Liquid::LocalFileSystem`** subclass (`multiply_local_file_system.rb`) resolves includes from multiple paths.
+- **Liquid Drops** (`liquid_drops/`) wrap domain objects (e.g., `GmlDictionaryDrop`) for template rendering.
+- **Bundled templates** live in `lib/metanorma/plugin/lutaml/liquid_templates/` for XMI/EA rendering.
+
+### Config System
+
+The `Config` module (`lib/metanorma/plugin/lutaml/config.rb`) uses `lutaml/model` (LutaML::Model) to define config schemas: `Root`, `Package`, `Guidance`, `GuidanceKlass`, `GuidanceAttribute`. Config YAML files control which packages/entities to render from XMI documents.
+
+### Testing Pattern
+
+Tests use `metanorma-standoc` as the backend. The spec helper registers all extensions with Asciidoctor, then tests call `metanorma_convert(input)` which converts AsciiDoc input through the pipeline and compares XML output. Test fixtures (`.exp`, `.lutaml`, `.xmi`, `.xml`, `.liquid` files) are in `spec/fixtures/lutaml/` and `spec/assets/lutaml/`.
+
+## Key Dependencies
+
+- `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,18 +12,20 @@ rescue StandardError
   nil
 end
 
-gem "byebug"
-gem "debug"
-gem "equivalent-xml"
-gem "metanorma"
-gem "metanorma-standoc", "~> 3.0.8"
-gem "rake", "~> 13"
-gem "rspec", "~> 3.6"
+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", "~> 1.58"
-gem "rubocop-performance", "~> 1.19"
-gem "simplecov", "~> 0.15"
-gem "timecop", "~> 0.9"
-gem "vcr", "~> 6.1.0"
+gem "rubocop"
+gem "rubocop-performance"
+gem "rubocop-rake"
+gem "rubocop-rspec"
+gem "simplecov"
+gem "timecop"
+gem "vcr"
 gem "webmock"
-gem "xml-c14n"
+

data/Gemfile.devel

@@ -0,0 +1,2 @@
+gem "metanorma-standoc", github: "metanorma/metanorma-standoc", branch: "main"
+gem "metanorma", github: "metanorma/metanorma", branch: "main"

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/Rakefile

@@ -1,6 +1,23 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+XMI_SPEC_FILES = %w[
+  spec/metanorma/plugin/lutaml/lutaml_ea_xmi_preprocessor_spec.rb
+  spec/metanorma/plugin/lutaml/lutaml_uml_datamodel_description_preprocessor_spec.rb
+  spec/metanorma/plugin/lutaml/lutaml_klass_table_block_macro_spec.rb
+  spec/metanorma/plugin/lutaml/lutaml_enum_table_block_macro_spec.rb
+  spec/metanorma/plugin/lutaml/lutaml_xmi_index_spec.rb
+  spec/metanorma/plugin/lutaml/lutaml_xmi_uml_preprocessor_spec.rb
+].freeze
+
 RSpec::Core::RakeTask.new(:spec)
 
+RSpec::Core::RakeTask.new(:fast) do |t|
+  t.pattern = FileList["spec/**/*_spec.rb"] - XMI_SPEC_FILES
+end
+
+RSpec::Core::RakeTask.new(:xmi) do |t|
+  t.pattern = FileList[XMI_SPEC_FILES]
+end
+
 task default: :spec

data/docs/usages/express.adoc

@@ -297,3 +297,58 @@ from the paths other than the location of the document.
 The resulting block adds the `include_path` to the Liquid renderer.  The path is
 resolved based on the location of the document.  You can add multiple paths by
 separating them with commas.
+
+=== Using `loadfile` filter in templates
+
+This functionality allows `[lutaml_express_liquid]` blocks to load data from
+a yaml or json file from the specified path.
+
+For example, you have the Metanorma document file (.adoc) with the following
+content:
+
+[source,adoc]
+-----
+:lutaml-express-index: all_schemas; ../schemas_all.yaml;
+
+[lutaml_express_liquid,all_schemas,context,config_yaml=schemas.yaml,include_path=../templates]
+---
+{% assign all_schemas = repo.schemas  %}
+{% render "templates/resources/schema" for ordered_schemas as schema %}
+...
+----
+-----
+
+You have the liquid template file
+`templates/resources/schema.liquid` with the following content:
+
+[source,liquid]
+-----
+{% assign data = "my_file.yaml" | loadfile: "." %}
+This is {{ data.shape }} with color {{ data.color }}.
+-----
+
+Where:
+
+* `loadfile:` is a liquid filter that loads the file content based on the path
+  `my_file.yaml` with argument `.`.
+  The argument is the path of the parent folder, which is the
+  current directory of the Metanorma document.
+
+And the content of the yaml file `my_file.yaml` looks like:
+
+[source,yaml]
+----
+---
+shape: square
+color: blue
+corners: 4
+----
+
+Will render as:
+[source,asciidoc]
+----
+...
+This is square with color blue.
+...
+----
+

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.