Add UnitsML XML Schema specification generated from XSD

.github/workflows/generate.yml

@@ -19,14 +19,26 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
-    container:
-      image: metanorma/metanorma:latest
+    env:
+      BUNDLE_GEMFILE: Gemfile
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           submodules: true
 
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
       - name: Validate register structure
         run: ruby scripts/validate-register.rb
 
@@ -40,11 +52,28 @@ jobs:
       #     github-packages-token: ${{ secrets.METANORMA_CI_PAT_TOKEN }}
       #     use-bundler: true
 
+      - name: Install bundled dependencies
+        run: bundle check || bundle install
+
+      - name: Record documentation runtime
+        run: |
+          bundle exec ruby -rjson -e '
+            names = %w[lutaml-model metanorma-standoc metanorma-plugin-lutaml metanorma-plugin-plantuml metanorma-utils metanorma-cli]
+            dependencies = Gem.loaded_specs.select { |name, _| names.include?(name) }
+            puts JSON.generate(runtime: RUBY_DESCRIPTION, dependencies: dependencies.transform_values { |spec| spec.version.to_s })
+          '
+
       - name: Metanorma generate site
         uses: actions-mn/build-and-publish@v2
         with:
           agree-to-terms: true
           destination: gh-pages
+          use-bundler: true
+
+      - name: Verify generated XML Schema documentation
+        run: >-
+          bundle exec ruby script/verify_xsd_documentation.rb
+          sources/unitsml-xml-schema/schemas/unitsml-v1.0.xsd _site
 
   deploy:
     if: ${{ github.ref == 'refs/heads/main' }}
@@ -56,4 +85,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

Gemfile

@@ -1,4 +1,20 @@
 source "https://rubygems.org"
 
+gem "lutaml", "~> 0.10", ">= 0.10.12"
+gem "lutaml-model", "~> 0.8.4"
+gem "metanorma"
 gem "metanorma-cli"
-# gem "metanorma-nist", source: "https://rubygems.pkg.github.com/metanorma"
+gem "metanorma-plugin-lutaml", "~> 0.7", ">= 0.7.55"
+gem "metanorma-standoc", "~> 3.5", ">= 3.5.1"
+gem "metanorma-utils", "~> 2.0", ">= 2.0.8"
+# 1.0.17 emits SVG lengthAdjust on <g>, rejected by the scoped Metanorma profile.
+gem "metanorma-plugin-plantuml", "= 1.0.15"
+
+# PlantUML attribute compatibility; pin until the fix is released.
+gem "svg_conform", github: "claricle/svg_conform", ref: "7e4c8cb1326b3850b50bb47ae63257076078ca88"
+
+# Parse generated HTML IDs and links without matching data attributes or code examples.
+gem "nokogiri"
+
+# Linked-SVG pixel sizing; pin until the fix is released.
+gem "metanorma-cc", github: "metanorma/metanorma-cc", ref: "42c77bf2514e37d714aed48d44c1b9b9a2011bc5"

metanorma.yml

@@ -4,6 +4,7 @@ metanorma:
     files:
       - sources/asciiunits/document.adoc
       - sources/unitsdb/document.adoc
+      - sources/unitsml-xml-schema/document.adoc
       - sources/unitsml-36812-general/document.adoc
       - sources/unitsml-36813-numeric/document.adoc
       - sources/unitsml-36814-unitsdb/document.adoc

script/verify_xsd_documentation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "rexml/xpath"
+require "set"
+require "svg_conform"
+require "nokogiri"
+
+schema_path = ARGV.fetch(0)
+output_path = ARGV.fetch(1)
+schema = REXML::Document.new(File.read(schema_path))
+ns = { "xsd" => "http://www.w3.org/2001/XMLSchema" }
+components = %w[element complexType attributeGroup].flat_map do |kind|
+  REXML::XPath.match(schema, "/xsd:schema/xsd:#{kind}", ns)
+end
+expected = components.map { |component| "xsd_#{component.attributes.fetch('name')}" }.to_set
+abort "No schema components found in #{schema_path}" if expected.empty?
+
+validator = SvgConform::Validator.new(mode: :sax)
+profile = SvgConform::Profiles.get(:metanorma)
+engine = SvgConform::RemediationEngine.new(profile)
+svg_directory = ARGV[2] || File.expand_path("../_plantuml_images", File.dirname(schema_path))
+
+files = File.directory?(output_path) ? Dir.glob(File.join(output_path, "**", "*.html")) : [output_path]
+files.each do |file|
+  html = File.read(file)
+  document = Nokogiri::HTML5(html)
+  identifiers = document.xpath("//*[@id]").map { |node| node["id"] }
+  anchors = identifiers.to_set
+  next unless expected.subset?(anchors)
+  abort "Duplicate HTML identifiers in #{file}" unless identifiers.size == anchors.size
+
+  if html.match?(/\{%\s*(?:for|render|endfor)\b|Liquid (?:syntax )?error:/)
+    abort "Unrendered or failed Liquid in #{file}"
+  end
+
+  diagrams = document.xpath("//*[local-name()='svg']")
+  abort "Expected #{expected.size} SVG structure diagrams, found #{diagrams.size} in #{file}" unless diagrams.size == expected.size
+
+  diagram_roots = diagrams.map do |diagram|
+    abort "PlantUML error diagram in #{file}" if diagram.text.match?(/Syntax Error|An error has occurred/i)
+    links = diagram.xpath(".//*[local-name()='a']").filter_map do |node|
+      href = node["href"] || node.attribute_with_ns("href", "http://www.w3.org/1999/xlink")&.value
+      href.delete_prefix("#") if href&.start_with?("#")
+    end
+    missing = links.reject { |target| anchors.include?(target) }
+    abort "Broken SVG component links: #{missing.uniq.join(', ')}" unless missing.empty?
+    links.grep(/\Axsd_/).first
+  end
+  missing_diagrams = expected - diagram_roots.to_set
+  abort "Missing linked SVG component roots: #{missing_diagrams.to_a.join(', ')}" unless missing_diagrams.empty?
+
+  # Validate native assets before HTML-specific IDs and attributes are injected.
+  # Apply the same configured remediations as Metanorma, without writing files.
+  expected.sort.each do |anchor|
+    svg_file = File.join(svg_directory, "#{anchor.sub('xsd_', 'xsd-')}.svg")
+    abort "Missing native SVG: #{svg_file}" unless File.file?(svg_file)
+    native = SvgConform::Document.from_file(svg_file)
+    result = validator.validate(native.root, profile: profile)
+    engine.apply_remediations(native, result)
+    result = validator.validate(native.root, profile: profile)
+    invalid = result.errors.reject { |error| error.violation_type == :reference_violation }
+    abort "SVG conformance errors in #{svg_file}: #{invalid.map(&:message).uniq.join('; ')}" unless invalid.empty?
+    unresolved = result.unresolved_internal_references.reject { |reference| anchors.include?(reference.target_id) }
+    abort "Broken SVG references in #{svg_file}: #{unresolved.map(&:value).uniq.join(', ')}" unless unresolved.empty?
+  end
+
+  puts "Verified #{expected.size} schema component anchors and #{diagrams.size} linked SVG diagrams in #{file}"
+  exit 0
+end
+abort "No generated HTML in #{output_path} contains all #{expected.size} schema component anchors"

sources/unitsml-xml-schema/document.adoc

@@ -0,0 +1,45 @@
+= CalConnect Standard: UnitsML XML schema specification
+:title: UnitsML XML schema specification
+:docnumber: 36811
+:copyright-year: 2025
+:doctype: standard
+:edition: 1
+:status: committee-draft
+:updated-date: 2025-08-22
+:published-date: 2025-08-22
+:technical-committee: TC UNITS
+:fullname: Ronald Tse
+:surname: Tse
+:givenname: Ronald
+:affiliation: Ribose Inc.
+:fullname_2: Suleman Uzair
+:surname_2: Uzair
+:givenname_2: Suleman
+:affiliation_2: Ribose Inc.
+:imagesdir: images
+:mn-document-class: cc
+:mn-output-extensions: xml,html,pdf,rxl
+:local-cache-only:
+:data-uri-image:
+
+include::sections/00-foreword.adoc[]
+
+include::sections/00-intro.adoc[]
+
+include::sections/01-scope.adoc[]
+
+include::sections/02-normrefs.adoc[]
+
+include::sections/03-terms.adoc[]
+
+include::sections/04-conventions.adoc[]
+
+include::sections/05-schema.adoc[]
+
+include::sections/06-elements.adoc[]
+
+include::sections/07-complex-types.adoc[]
+
+include::sections/08-attribute-groups.adoc[]
+
+include::sections/99-bibliography.adoc[]

sources/unitsml-xml-schema/schemas/README.adoc

@@ -0,0 +1,25 @@
+= UnitsML 1.0 schema source provenance
+
+The schema in `unitsml-v1.0.xsd` is generated from the UnitsML schema project
+inputs used for the published final 1.0 reference. The optional `schemaLocation`
+was omitted from the XML namespace import so schema documentation builds do not
+need network access; the import namespace and schema declarations are unchanged.
+The schema template and generator are from `unitsml/schemas` commit
+`de016581e4ab886550608ae26fd457f669b0938f`. The `unitsdb/units.yaml` and
+`unitsdb/prefixes.yaml` inputs are from commit
+`651384b0300b79489274c117a3ea4a860a806e84`, the UnitsDB main revision before
+the published reference was deployed.
+
+The original generator expands both YAML files into `items` XML, then runs
+`templates/xsdprocess.xsl` over `templates/unitsml-v1.0.template`. The resulting
+schema has namespace `https://schema.unitsml.org/unitsml/1.0`. Its 298
+enumeration values exactly match the values rendered in the published schema
+reference, and its non-annotation, non-enumeration structure matches the
+maintained final 1.0 XSD.
+
+Input SHA-256 values:
+
+* `units.yaml`: `05893cff15d593a9197a17dd8b70e941634d483e5847b97f8326960b2e06af1e`
+* `prefixes.yaml`: `25c804e6e7951eb0605608002e23f3439e58ce83e3ba410cae91370fff420625`
+* original generated XSD before the optional-import-hint omission: `7bf145052f69abcbd79b268993f60b5b25be323be0e325e1b1cbe444abb104d6`
+* repository XSD with the optional hint omitted: `efef28d7bde5a66fbf3c1c6e40c9b4897868b7e1b6171723b7f6364087b9fcd3`