Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
1ae7de5
Added liquid templates utilizing 'lutaml_xsd' command
suleman-uzair Jul 25, 2025
751d4b1
Delete sources/unitsml_xsd_docs/document.html
suleman-uzair Aug 22, 2025
8da5c06
removed handcrafted xml
suleman-uzair Aug 29, 2025
3c8c458
used Lutaml::Xsd#to_xml method over handcrafted XML
suleman-uzair Sep 1, 2025
f7765fd
feat: update xsd document
ronaldtse Sep 22, 2025
bbd4099
Changed filter calls to drop method calls
suleman-uzair Sep 25, 2025
397d081
moved from filter use to lutaml-xsd liquid methods
suleman-uzair Oct 6, 2025
4b768a7
updated complex type and element documents
suleman-uzair Oct 7, 2025
559cde2
updated documents and removed unused liquid files
suleman-uzair Oct 7, 2025
d202d5b
updated file extensions and documents
suleman-uzair Oct 9, 2025
8e12973
Updated templates code and added a new partial
suleman-uzair Nov 10, 2025
2148ce4
Updated document files about child elements rendering in elements and…
suleman-uzair Nov 11, 2025
c83adb8
Updated example block for complex type and element
suleman-uzair Nov 13, 2025
b761d10
updated used lutaml-xsd methods names
suleman-uzair Nov 19, 2025
10b496c
Updated doc files and branch names in Gemfile
suleman-uzair Dec 10, 2025
38648ac
Add UnitsML XSD generated document templates
suleman-uzair May 15, 2026
4a321cd
Fix UnitsML XSD Metanorma compilation
suleman-uzair May 18, 2026
4a736d3
Require the XSD-capable documentation toolchain
suleman-uzair Oct 29, 2026
7897aa1
Use the repository Gemfile in the documentation container
suleman-uzair Oct 29, 2026
78e77d6
Allow the container to bootstrap repository gems
suleman-uzair Oct 29, 2026
b26d3c5
Build the documentation bundle on the hosted Ruby toolchain
suleman-uzair Oct 29, 2026
4554c9c
Generate linked schema diagrams and verify their output
suleman-uzair Oct 30, 2026
1109f28
Document final UnitsML 1.0 schema
suleman-uzair Nov 3, 2026
3a303c8
Pin SVG-compatible PlantUML generator
suleman-uzair Nov 3, 2026
9dc4fae
Complete the XML Schema normrefs entries
ronaldtse Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 32 additions & 3 deletions .github/workflows/generate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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' }}
Expand All @@ -56,4 +85,4 @@ jobs:
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
uses: actions/deploy-pages@v4
18 changes: 17 additions & 1 deletion Gemfile
Original file line number Diff line number Diff line change
@@ -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"
1 change: 1 addition & 0 deletions metanorma.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ metanorma:
- sources/unitsml-36817-asciiunits/document.adoc
- sources/unitsml-36818-xml-usage/document.adoc
- sources/unitsml-36819-conformance/document.adoc
- sources/unitsml-xml-schema/document.adoc
# - sources/unitsml-guide/document.adoc
# - sources/unitsml-incorporation/document.adoc
# - sources/unitsml-ubl-ndr-subset/document.adoc
Expand Down
71 changes: 71 additions & 0 deletions script/verify_xsd_documentation.rb
Original file line number Diff line number Diff line change
@@ -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"
45 changes: 45 additions & 0 deletions sources/unitsml-xml-schema/document.adoc
Original file line number Diff line number Diff line change
@@ -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[]
25 changes: 25 additions & 0 deletions sources/unitsml-xml-schema/schemas/README.adoc
Original file line number Diff line number Diff line change
@@ -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`
Loading
Loading