diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml index bff4275..146b4d0 100644 --- a/.github/workflows/generate.yml +++ b/.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 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/Gemfile b/Gemfile index d47c6f5..9579c6c 100644 --- a/Gemfile +++ b/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 , 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" diff --git a/metanorma.yml b/metanorma.yml index a5fdeac..3c3f02d 100644 --- a/metanorma.yml +++ b/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 diff --git a/script/verify_xsd_documentation.rb b/script/verify_xsd_documentation.rb new file mode 100644 index 0000000..205ca4f --- /dev/null +++ b/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" diff --git a/sources/unitsml-xml-schema/document.adoc b/sources/unitsml-xml-schema/document.adoc new file mode 100644 index 0000000..e3865e1 --- /dev/null +++ b/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[] diff --git a/sources/unitsml-xml-schema/schemas/README.adoc b/sources/unitsml-xml-schema/schemas/README.adoc new file mode 100644 index 0000000..617e599 --- /dev/null +++ b/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` diff --git a/sources/unitsml-xml-schema/schemas/unitsml-v1.0-csd04.xsd b/sources/unitsml-xml-schema/schemas/unitsml-v1.0-csd04.xsd new file mode 100644 index 0000000..0d34975 --- /dev/null +++ b/sources/unitsml-xml-schema/schemas/unitsml-v1.0-csd04.xsd @@ -0,0 +1,1368 @@ + + + + + + + + Container for UnitsML units, quantities, and prefixes. + + + + + ComplexType for the root element of an UnitsML document. + + + + + + + + + + + + + + Container for units. Use in UnitsML container or directly incorporate into a host schema. + + + + + Element for describing units. Use in containers UnitSet or directly incorporate into a host schema. + + + + + Container for describing the system of units. + + + + + Element containing the unit name. + + + + + Element containing various unit symbols. Examples include Aring (ASCII), Å (HTML). + + + + + Element for descriptive information, including version changes to the unit. + + + + + Element for listing the unit code value from a specific code list. + + + + + Container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered root units. + + + + + Element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + + Element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + + Container for providing conversion information to other units. + + + + + Element for providing factors for a conversion equation from another unit; stem:[y = d + ((b / c) (x + a))] + + + + + Element for descriptive information. + + + + + Element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Element for providing conversion based on SOAP/WSDL calls to a remote server. + + + + + Element to describe the WSDL service. + + + + + Element for a description of the SpecialConversionFrom. + + + + + Element for all quantities that can be expressed using this unit. + + + + + Element to describe the definition of the unit. + + + + + Element to describe the historical development of the unit. + + + + + Element as a placeholder for additional information. + + + + + + Container for items that are counted and are (in practice) combined with scientific units of measure. + + + + + Container for a single counted item. + + + + + Element containing the item name(s). + + + + + Element containing symbols for the item. + + + + + Element for descriptive information, including version changes to the item. + + + + + Element to describe the definition of the item. + + + + + Element to describe the historical development of the item. + + + + + Element as a placeholder for additional information. + + + + + + Container for quantities. + + + + + Element for describing quantities and referencing corresponding units. Use in container or directly incorporate into a host schema. + + + + + Element containing the quantity name. + + + + + Element containing various quantity symbols. + + + + + Element for referencing a unit of measure from within the Quantity element. + + + + + Element for descriptive information, including version changes to the unit. + + + + + Element to describe the definition of the quantity. + + + + + Element to describe the historical development of the quantity. + + + + + Element as a placeholder for additional information. + + + + + + Container for dimensions. + + + + + Element to express the dimension of a unit or quantity in terms of the SI base quantities length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. + + + + + Element containing the dimension of the quantity length. + + + + + Element containing the dimension of the quantity mass. + + + + + Element containing the dimension of the quantity time. + + + + + Element containing the dimension of the quantity electric current. + + + + + Element containing the dimension of the quantity thermodynamic temerature. + + + + + Element containing the dimension of the quantity amount of substance. + + + + + Element containing the dimension of the quantity luminous intensity. + + + + + Element containing the dimension of the quantity plane angle. + + + + + Element containing the dimension of any item. Note: this element is meant to be used to allow counted items to be included in the dimensioning of a derived quantity, e.g., electrons per time; usage of this element does not conform to the SI description of the dimension of a quantity in terms of seven base quantities. + + + + + + Container for prefixes. + + + + + Element containing information about a prefix. + + + + + Element containing the prefix name. + + + + + Element containing prefix symbols. + + + + + + URI indicating the unitID of the starting unit for the conversion. For units which are defined in the same document, the URI should consist of a pound sign (#) followed by the ID value. + + + + URI indicating the unitID of the starting unit for the conversion. For units which are defined in the same document, the URI should consist of a pound sign (#) followed by the ID value. + + + + + + Name of relevant publication. + + + + Name of relevant publication. + + + + + + Relevant URL for available information. + + + + Relevant URL for available information. + + + + + + An exponent of the unit, specified as powerNumerator and powerDenominator. + + + + An integer exponent of the unit. + + + + + An integer value divided into the powerNumerator to create a non integer exponent of a unit. For example 1/2. + + + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + URL to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + URL to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + + + + + Type for the unit container. + + + + + Element for describing units. Use in containers UnitSet or directly incorporate into a host schema. + + + + + + + Type for the unit. + + + + + Container for describing the system(s) of units. + + + + + + + + Container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered root units. + + + + + + + Element for descriptive information, including version changes to the unit. + + + + + + + + + + Used to indicate the version of the unit output from the Units Database. Changes in the time-stamp are made if a substantive change has been made to the unit, such as a change in the unit definition or changes in conversion factors. + + + + + Reference to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + + + Type for the element for listing the unit code value from a specific code list. + + + + The code associated for this unit in a specific code list. + + + + + The name of the code list. + + + + + The version of the code list containing the unit code. + + + + + Suggested retrieval location for this version of the code list. + + + + + Organization responsible for publication and/or maintenance of the code list. + + + + + URI for organization responsible for the code list. + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + + + Type for the container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered base units. + + + + + Element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + + Element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + + + + Type for the element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + Unit identifier; the enumerated list is basically English unit names in lowercase, with a few upper case exceptions, e.g., 32F, mmHg, pH. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + + + + Type for the element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + URI to identify the unit. + + + + + URI identifying the source and possibly the definition of the unit. + + + + + Optional unit annotation; e.g., a unit name if the unit identifier above is an uncommon code. + + + + + + + + + Type for the container for providing conversion information to other units. + + + + + Element for providing factors for a conversion equation from another unit; stem:[y = d + ((b / c) (x + a))]. Note: The related "conversion to" equation is a simple inversion of the above equation; i.e., stem:[x = ((c / b) (y - d)) - a]. + + + + + Element for describing a conversion that cannot be described by the linear expression in the element Float64ConversionFrom. + + + + + Element for providing conversion based on SOAP/WSDL calls to a remote server. + + + + + + + Type for the element for providing factors for a conversion equation from another unit; stem:[y = d + ((b / c) (x + a))] + + + + + + + + + Number to be added at the start of the conversion (prior to multiplication or division) [factor 'a' in equation]. + + + + + Indicates the position of the least +significant digit (in decimal) of +the initialAddend; the position of +this digit is given by ten to +additive inverse of this number. + + + + + Number by which to multiply sum of initial addend and initial value [factor 'b' in equation]. + + + + + Number of significant digits in the multiplicand value. + + + + + Divisor to be applied to the value at the same time as the multiplicand [factor 'c' in equation]. + + + + + Number of significant digits in the divisor value. + + + + + Number to be added at the end of the conversion [factor 'd' in equation]. + + + + + Indicates the position of the least +significant digit (in decimal) of +the finalAddend; the position of +this digit is given by ten to +additive inverse of this number. + + + + + Indicates if the conversion is exact. + + + + + + Type for the element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Description of the conversion. + + + + + + + URL for external description of the conversion or for an online convertor. + + + + + + + Type for the element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Description of the service. + + + + + + + + URL for external WSDL definition file. + + + + + + + Type for a set of counted items. + + + + + + + + Type for a single counted item. + + + + + + + + + + + + + + + Type for quantity container. + + + + + + + + Type for the quantity. + + + + + + Element containing various quantity symbols. + + + + + Element for specifying particular units associated with the quantity. + + + + + Element for descriptive information, including version changes to the quantity. + + + + + + + + + + Type of the quantity. For example base or derived. + + + + + + + + + + + + + + + Type for the dimension container. + + + + + Element to express a unit or quantity in terms of the SI base quantities length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. + + + + + + + Type for dimension. + + + + This unbounded sequence allows any order of any number of elements; e.g., L^1 · L^-1. + + + + + + + + + + + + Element containing the dimension of any item. Note: this element is meant to be used to allow counted items to be included in the dimensioning of a derived quantity, e.g., electrons per time; usage of this element does not conform to the SI description of the dimension of a quantity in terms of seven base quantities. + + + + + + + Boolean to designate that a quantity or unit is dimensionless. + + + + + + Type of the quantity length. + + + + Symbol of the quantity length. + + + + + + + Type of the quantity mass. + + + + Symbol of the quantity mass. + + + + + + + Type of the quantity time. + + + + Symbol of the quantity time. + + + + + + + Type of the quantity electric current. + + + + Symbol of the quantity electric current. + + + + + + + Type of the quantity thermodynamic temperature. + + + + Symbol of the quantity thermodynamic temperature. + + + + + + + Type of the quantity amount of substance. + + + + Symbol of the quantity amount of substance. + + + + + + + Type of the quantity luminous intensity. + + + + Symbol of the quantity luminous intensity. + + + + + + + Type of the quantity plane angle. + + + + Symbol of the quantity plane angle. + + + + + + + Type of the quantity represented by a counted item, e.g., electron + + + + Unique URL for identifying or describing the item. + + + + + Symbol for the item. + + + + + + + + Type for container for prefixes. + + + + + + + + Type for element for describing prefixes. Use in container PrefixSet. + + + + + + + + + The base of the prefix system, i.e., 10 (SI) or 2 (binary). + + + + + + + + + + + The exponential power of the prefix with relation to the base. + + + + + + + Type for name. Used for names in units, quantities, and prefixes. + + + + + + + + + + Type for unit system. + + + + Name of the unit system. For example, SI, inch-pound, CGS, and MKS. + + + + + Description of the unit relative to the unit system. Examples are SI_base and non-SI_not_acceptable. + + + + + + + Type for symbols. Used in units, quantities, and prefixes. + + + + + + + + Type of symbol representation. Examples include ASCII, unicode, HTML, and MathML. + + + + + + + + + + + + + + + + + + + + Type for notes. Used in units and conversion factors. + + + + + + + + + + Type for definition. + + + + + + + + + + + + Type for history. + + + + + + + + + + + + Type for remark. + + + + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + + + + + Type for reference to a unit or quantity. + + + + URL to the reference item. + + + + + Name of the referenced item. + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + diff --git a/sources/unitsml-xml-schema/schemas/unitsml-v1.0.xsd b/sources/unitsml-xml-schema/schemas/unitsml-v1.0.xsd new file mode 100644 index 0000000..c6c0a7e --- /dev/null +++ b/sources/unitsml-xml-schema/schemas/unitsml-v1.0.xsd @@ -0,0 +1,1345 @@ + + + + + + + + Container for UnitsML units, quantities, and prefixes. + + + + + ComplexType for the root element of an UnitsML document. + + + + + + + + + + + + + + Container for units. Use in UnitsML container or directly incorporate into a host schema. + + + + + Element for describing units. Use in containers UnitSet or directly incorporate into a host schema. + + + + + Container for describing the system of units. + + + + + Element containing the unit name. + + + + + Element containing various unit symbols. Examples include Aring (ASCII), Š(HTML). + + + + + Element for descriptive information, including version changes to the unit. + + + + + Element for listing the unit code value from a specific code list. + + + + + Container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered root units. + + + + + Element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + + Element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + + Container for providing conversion information to other units. + + + + + Element for providing factors for a conversion equation from another unit; y = d + ((b / c) (x + a)) + + + + + Element for descriptive information. + + + + + Element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Element for providing conversion based on SOAP/WSDL calls to a remote server. + + + + + Element to describe the WSDL service. + + + + + Element for a description of the SpecialConversionFrom. + + + + + Element for all quantities that can be expressed using this unit. + + + + + Element to describe the definition of the unit. + + + + + Element to describe the historical development of the unit. + + + + + Element as a placeholder for additional information. + + + + + + Container for items that are counted and are (in practice) combined with scientific units of measure. + + + + + Container for a single counted item. + + + + + Element containing the item name(s). + + + + + Element containing symbols for the item. + + + + + Element for descriptive information, including version changes to the item. + + + + + Element to describe the definition of the item. + + + + + Element to describe the historical development of the item. + + + + + Element as a placeholder for additional information. + + + + + + Container for quantities. + + + + + Element for describing quantities and referencing corresponding units. Use in container or directly incorporate into a host schema. + + + + + Element containing the quantity name. + + + + + Element containing various quantity symbols. + + + + + Element for referencing a unit of measure from within the Quantity element. + + + + + Element for descriptive information, including version changes to the unit. + + + + + Element to describe the definition of the quantity. + + + + + Element to describe the historical development of the quantity. + + + + + Element as a placeholder for additional information. + + + + + + Container for dimensions. + + + + + Element to express the dimension of a unit or quantity in terms of the SI base quantities length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. + + + + + Element containing the dimension of the quantity length. + + + + + Element containing the dimension of the quantity mass. + + + + + Element containing the dimension of the quantity time. + + + + + Element containing the dimension of the quantity electric current. + + + + + Element containing the dimension of the quantity thermodynamic temerature. + + + + + Element containing the dimension of the quantity amount of substance. + + + + + Element containing the dimension of the quantity luminous intensity. + + + + + Element containing the dimension of the quantity plane angle. + + + + + Element containing the dimension of any item. Note: this element is meant to be used to allow counted items to be included in the dimensioning of a derived quantity, e.g., electrons per time; usage of this element does not conform to the SI description of the dimension of a quantity in terms of seven base quantities. + + + + + + Container for prefixes. + + + + + Element containing information about a prefix. + + + + + Element containing the prefix name. + + + + + Element containing prefix symbols. + + + + + + URI indicating the unitID of the starting unit for the conversion. For units which are defined in the same document, the URI should consist of a pound sign (#) followed by the ID value. + + + + URI indicating the unitID of the starting unit for the conversion. For units which are defined in the same document, the URI should consist of a pound sign (#) followed by the ID value. + + + + + + Name of relevant publication. + + + + Name of relevant publication. + + + + + + Relevant URL for available information. + + + + Relevant URL for available information. + + + + + + An exponent of the unit, specified as powerNumerator and powerDenominator. + + + + An integer exponent of the unit. + + + + + An integer value divided into the powerNumerator to create a non integer exponent of a unit. For example 1/2. + + + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + URL to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + URL to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + + + + + Type for the unit container. + + + + + Element for describing units. Use in containers UnitSet or directly incorporate into a host schema. + + + + + + + Type for the unit. + + + + + Container for describing the system(s) of units. + + + + + + + + Container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered root units. + + + + + + + Element for descriptive information, including version changes to the unit. + + + + + + + + + + Used to indicate the version of the unit output from the Units Database. Changes in the time-stamp are made if a substantive change has been made to the unit, such as a change in the unit definition or changes in conversion factors. + + + + + Reference to a representation of the unit or quantity in terms of the 7 SI base dimensions. + + + + + + Type for the element for listing the unit code value from a specific code list. + + + + The code associated for this unit in a specific code list. + + + + + The name of the code list. + + + + + The version of the code list containing the unit code. + + + + + Suggested retrieval location for this version of the code list. + + + + + Organization responsible for publication and/or maintenance of the code list. + + + + + URI for organization responsible for the code list. + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + + + Type for the container for defining derived units in terms of their root units. This allows a precise definition of a wide range of units. The goal is to improve interoperability among applications and databases which use derived units based on commonly encountered base units. + + + + + Element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + + Element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + + + + Type for the element for a root unit (from an extensive enumerated list) allowing an optional prefix and power. E.g., mm^2 + + + + Unit identifier; the enumerated list is basically English unit names in lowercase, with a few upper case exceptions, e.g., 32F, mmHg, pH. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Prefix identifier; e.g., m, k, M, G. [Enumeration order is by prefix magnitude (Y to y) followed by binary prefixes.] + + + + + + + Type for the element for those special cases where the root unit needed is not included in the enumerated list in the above element. + + + + URI to identify the unit. + + + + + URI identifying the source and possibly the definition of the unit. + + + + + Optional unit annotation; e.g., a unit name if the unit identifier above is an uncommon code. + + + + + + + + + Type for the container for providing conversion information to other units. + + + + + Element for providing factors for a conversion equation from another unit; y = d + ((b / c) (x + a)). Note: The related "conversion to" equation is a simple inversion of the above equation; i.e., x = ((c / b) (y - d)) - a. + + + + + Element for describing a conversion that cannot be described by the linear expression in the element Float64ConversionFrom. + + + + + Element for providing conversion based on SOAP/WSDL calls to a remote server. + + + + + + + Type for the element for providing factors for a conversion equation from another unit; y = d + ((b / c) (x + a)) + + + + + + + + + Number to be added at the start of the conversion (prior to multiplication or division) [factor 'a' in equation]. + + + + + Indicates the position of the least +significant digit (in decimal) of +the initialAddend; the position of +this digit is given by ten to +additive inverse of this number. + + + + + Number by which to multiply sum of initial addend and initial value [factor 'b' in equation]. + + + + + Number of significant digits in the multiplicand value. + + + + + Divisor to be applied to the value at the same time as the multiplicand [factor 'c' in equation]. + + + + + Number of significant digits in the divisor value. + + + + + Number to be added at the end of the conversion [factor 'd' in equation]. + + + + + Indicates the position of the least +significant digit (in decimal) of +the finalAddend; the position of +this digit is given by ten to +additive inverse of this number. + + + + + Indicates if the conversion is exact. + + + + + + Type for the element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Description of the conversion. + + + + + + + URL for external description of the conversion or for an online convertor. + + + + + + + Type for the element for providing unit conversion information for conversions that are more complex than the Float64ConversionFrom linear equation. + + + + + Description of the service. + + + + + + + + URL for external WSDL definition file. + + + + + + + Type for a set of counted items. + + + + + + + + Type for a single counted item. + + + + + + + + + + + + + + + Type for quantity container. + + + + + + + + Type for the quantity. + + + + + + Element containing various quantity symbols. + + + + + Element for specifying particular units associated with the quantity. + + + + + Element for descriptive information, including version changes to the quantity. + + + + + + + + + + Type of the quantity. For example base or derived. + + + + + + + + + + + + + + + Type for the dimension container. + + + + + Element to express a unit or quantity in terms of the SI base quantities length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. + + + + + + + Type for dimension. + + + + This unbounded sequence allows any order of any number of elements; e.g., L^1 · L^-1. + + + + + + + + + + + + Element containing the dimension of any item. Note: this element is meant to be used to allow counted items to be included in the dimensioning of a derived quantity, e.g., electrons per time; usage of this element does not conform to the SI description of the dimension of a quantity in terms of seven base quantities. + + + + + + + Boolean to designate that a quantity or unit is dimensionless. + + + + + + Type of the quantity length. + + + + Symbol of the quantity length. + + + + + + + Type of the quantity mass. + + + + Symbol of the quantity mass. + + + + + + + Type of the quantity time. + + + + Symbol of the quantity time. + + + + + + + Type of the quantity electric current. + + + + Symbol of the quantity electric current. + + + + + + + Type of the quantity thermodynamic temperature. + + + + Symbol of the quantity thermodynamic temperature. + + + + + + + Type of the quantity amount of substance. + + + + Symbol of the quantity amount of substance. + + + + + + + Type of the quantity luminous intensity. + + + + Symbol of the quantity luminous intensity. + + + + + + + Type of the quantity plane angle. + + + + Symbol of the quantity plane angle. + + + + + + + Type of the quantity represented by a counted item, e.g., electron + + + + Unique URL for identifying or describing the item. + + + + + Symbol for the item. + + + + + + + + Type for container for prefixes. + + + + + + + + Type for element for describing prefixes. Use in container PrefixSet. + + + + + + + + + The base of the prefix system, i.e., 10 (SI) or 2 (binary). + + + + + + + + + + + The exponential power of the prefix with relation to the base. + + + + + + + Type for name. Used for names in units, quantities, and prefixes. + + + + + + + + + + Type for unit system. + + + + Name of the unit system. For example, SI, inch-pound, CGS, and MKS. + + + + + Description of the unit relative to the unit system. Examples are SI_base and non-SI_not_acceptable. + + + + + + + Type for symbols. Used in units, quantities, and prefixes. + + + + + + + + Type of symbol representation. Examples include ASCII, unicode, HTML, and MathML. + + + + + + + + + + + + + + + + + + + + Type for notes. Used in units and conversion factors. + + + + + + + + + + Type for definition. + + + + + + + + + + + + Type for history. + + + + + + + + + + + + Type for remark. + + + + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + + + + + Type for reference to a unit or quantity. + + + + URL to the reference item. + + + + + Name of the referenced item. + + + + + Primary language of the element and/or its attributes. [See RFC 4646, RFC 4647 and ISO 639.] + + + + diff --git a/sources/unitsml-xml-schema/sections/00-foreword.adoc b/sources/unitsml-xml-schema/sections/00-foreword.adoc new file mode 100644 index 0000000..b0c4217 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/00-foreword.adoc @@ -0,0 +1,35 @@ + +.Foreword +The Calendaring and Scheduling Consortium ("`CalConnect`") is a global +non-profit organization with the aim to facilitate interoperability of +collaborative technologies and tools through open standards. + +CalConnect works closely with international and regional partners, +of which the full list is available on our website +(https://www.calconnect.org/about/liaisons-and-relationships). + +The procedures used to develop this document and those intended for its +further maintenance are described in the CalConnect Directives. + +In particular the different approval criteria needed for the different +types of CalConnect documents should be noted. This document was drafted in +accordance with the editorial rules of the CalConnect Directives. + +Attention is drawn to the possibility that some of the elements of this +document may be the subject of patent rights. CalConnect shall not be +held responsible for identifying any or all such patent rights. Details +of any patent rights identified during the development of the document +will be provided in the Introduction. + +//// +// TODO: re-enable when we finish the IPR policy +and/or on the CalConnect list of patent +declarations received (see www.calconnect.com/patents). +//// + +Any trade name used in this document is information given for the +convenience of users and does not constitute an endorsement. + +This document was prepared by Technical Committee +_{technical-committee}_. + diff --git a/sources/unitsml-xml-schema/sections/00-intro.adoc b/sources/unitsml-xml-schema/sections/00-intro.adoc new file mode 100644 index 0000000..c4b051a --- /dev/null +++ b/sources/unitsml-xml-schema/sections/00-intro.adoc @@ -0,0 +1,9 @@ +== Introduction + +The UnitsML XML Schema defines the structure and content of the +representation of UnitsML objects in XML. + +It is defined as an XML Schema definition (XSD) for use in XML +applications. The schema is intended to be used in conjunction with the +UnitsML specification, which defines the semantics of the UnitsML +vocabulary. diff --git a/sources/unitsml-xml-schema/sections/01-scope.adoc b/sources/unitsml-xml-schema/sections/01-scope.adoc new file mode 100644 index 0000000..9850c5e --- /dev/null +++ b/sources/unitsml-xml-schema/sections/01-scope.adoc @@ -0,0 +1,4 @@ +== Scope + +This document describes the UnitsML XML Schema (UnitsML XSD), which is an +XML Schema definition for the representation of UnitsML objects in XML. diff --git a/sources/unitsml-xml-schema/sections/02-normrefs.adoc b/sources/unitsml-xml-schema/sections/02-normrefs.adoc new file mode 100644 index 0000000..f53842b --- /dev/null +++ b/sources/unitsml-xml-schema/sections/02-normrefs.adoc @@ -0,0 +1,6 @@ +[bibliography] +== Normative references + +* [[[w3c_xmlschema,W3C xmlschema-1]]] +* [[[w3c_xmlschema-1,W3C xmlschema11-1]]] +* [[[w3c_xmlschema-2,W3C xmlschema11-2]]] diff --git a/sources/unitsml-xml-schema/sections/03-terms.adoc b/sources/unitsml-xml-schema/sections/03-terms.adoc new file mode 100644 index 0000000..05c991f --- /dev/null +++ b/sources/unitsml-xml-schema/sections/03-terms.adoc @@ -0,0 +1,48 @@ +== Terms and definitions + +=== unit + +standard quantity used to express a physical quantity + +=== basic unit + +unit not derived from other units + +=== composite unit + +unit derived from two or more basic units conjoined by multiplication or division + +=== prefix + +modifier to a unit with a fixed factor + +=== quantity + +type of measurement that is represented by a unit + +[example] +distance, moment of force, temperature, energy. + +=== dimension + +basic physical quantity that can be expressed in terms of fundamental +quantities + +[example] +length, mass, time, plane angle. + +=== unit name + +name of a unit + +=== unit symbol + +abbreviated representation of a unit + +=== unit reference + +reference identifier to a unit in a database + +=== unit dimensions + +fundamental quantities to which the unit applies diff --git a/sources/unitsml-xml-schema/sections/04-conventions.adoc b/sources/unitsml-xml-schema/sections/04-conventions.adoc new file mode 100644 index 0000000..5cfa8b5 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/04-conventions.adoc @@ -0,0 +1,90 @@ +== Conventions + +=== General + +Elements and attributes defined in the UnitsML XML schema are described in +following clauses. + +Each element and attribute is described in a separate entry, with entries +arranged in alphabetical order. + +=== Element + +Each element entry contains the following information: + +* The XML Name (tag or generic identifier) of the element or attribute that is +used in UnitsML XML files. ++ +[example] +==== +`` +==== + +* The informational name of the element or attribute. ++ +[example] +==== +Unit +==== + +* A description of the element or attribute. ++ +[example] +==== +For the element ``: "Specifies a unit of measurement." +==== + +* A list of all of the attributes that may be applied to the element, with first +the attribute name and then the attribute's informal expanded name. Attribute +names are prefixed with an at sign (`@`). + +* The content model or type of the element's content. If the element has a type, +the type is given first, with a link to the type definition. If the element +does not have a type, the content model is described in detail, supporting +groups, sequences, choices, one of and any of. ++ +[example] +==== +string, integer, boolean, or a reference to a simple or complex type defined in +the schema. +==== + + +=== Attribute + +Each attribute entry contains the following information: + +* The XML Name of the attribute. ++ +[example] +==== +`@quantityType` +==== + +* The informational name of the attribute. ++ +[example] +==== +Quantity Type +==== + +* A description of the attribute +[example] +==== +Type of the quantity. +==== + +* The data type of the attribute's value. ++ +[example] +==== +string, integer, boolean, or a reference to a simple type defined in the schema. +==== + +* A list of all of the elements or groups of elements in which the attribute may +be used, with first the element name and then the element's informal +expanded name. Element names are not prefixed. + +* For each element or group of elements in which the attribute may be used, a +block of usage information with required or suggested values and other +information. diff --git a/sources/unitsml-xml-schema/sections/05-schema.adoc b/sources/unitsml-xml-schema/sections/05-schema.adoc new file mode 100644 index 0000000..b9e1712 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/05-schema.adoc @@ -0,0 +1,28 @@ +== Schema + +This document describes the final UnitsML 1.0 XML schema. Its namespace is +`https://schema.unitsml.org/unitsml/1.0`, and the schema source is included in +the UnitsML distribution as `unitsml.xsd`. The published schema reference is +https://schema.unitsml.org/unitsml/1.0. + +The root element of the schema is ``, which contains all other +elements. + +The schema is defined using the W3C XML Schema Definition Language +(<>), and conforms to <> and +<>. + +The UnitsML XML schema may be used in the following ways: + +* To validate UnitsML XML documents, ensuring that they conform to the + structure and content rules defined in the schema. + +* To incorportate UnitsML XML into XML application schemas, allowing for the + integration of UnitsML data with other XML-based data formats. + +* To generate code or data structures in programming languages that + support XML schema, facilitating the processing of UnitsML XML + documents. + +The UnitsML XML schema is maintained by the CalConnect TC UNITS Technical +Committee, and is available from https://www.unitsml.org. diff --git a/sources/unitsml-xml-schema/sections/06-elements.adoc b/sources/unitsml-xml-schema/sections/06-elements.adoc new file mode 100644 index 0000000..7b88964 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/06-elements.adoc @@ -0,0 +1,9 @@ +== Elements + +[lutaml_xsd,schemas/unitsml-v1.0.xsd,schema,include_path=templates] +---- +{% for item in schema.elements_sorted_by_name %} +{% render "element", item: item, schema: schema %} + +{% endfor %} +---- diff --git a/sources/unitsml-xml-schema/sections/07-complex-types.adoc b/sources/unitsml-xml-schema/sections/07-complex-types.adoc new file mode 100644 index 0000000..dc24dc3 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/07-complex-types.adoc @@ -0,0 +1,9 @@ +== Complex types + +[lutaml_xsd,schemas/unitsml-v1.0.xsd,schema,include_path=templates] +---- +{% for item in schema.complex_types_sorted_by_name %} +{% render "complex_type", item: item, schema: schema %} + +{% endfor %} +---- diff --git a/sources/unitsml-xml-schema/sections/08-attribute-groups.adoc b/sources/unitsml-xml-schema/sections/08-attribute-groups.adoc new file mode 100644 index 0000000..016ff03 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/08-attribute-groups.adoc @@ -0,0 +1,9 @@ +== Attribute groups + +[lutaml_xsd,schemas/unitsml-v1.0.xsd,schema,include_path=templates] +---- +{% for item in schema.attribute_groups_sorted_by_name %} +{% render "attribute_group", item: item, schema: schema %} + +{% endfor %} +---- diff --git a/sources/unitsml-xml-schema/sections/99-bibliography.adoc b/sources/unitsml-xml-schema/sections/99-bibliography.adoc new file mode 100644 index 0000000..f494396 --- /dev/null +++ b/sources/unitsml-xml-schema/sections/99-bibliography.adoc @@ -0,0 +1,2 @@ +[bibliography] +== Bibliography diff --git a/sources/unitsml-xml-schema/templates/_attribute.adoc b/sources/unitsml-xml-schema/templates/_attribute.adoc new file mode 100644 index 0000000..52f849f --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_attribute.adoc @@ -0,0 +1,24 @@ +{%- assign attribute_name = attribute.referenced_name | default: attribute.name | default: attribute.ref -%} +{%- assign attribute_type = attribute.referenced_type | default: attribute.type -%} +{%- capture attribute_docs -%} +{% for paragraph in attribute.annotation.documentation -%} +{{ paragraph.content }} + +{% endfor -%} +{%- endcapture -%} +{%- assign attribute_docs = attribute_docs | strip -%} +{%- capture constraints -%} +{% render "attribute_value_constraints", attribute: attribute %} +{%- endcapture -%} +{%- assign constraints = constraints | strip -%} + +`@{{ attribute_name }}`:: {% if attribute_type %}`{{ attribute_type }}` {% endif %}`[{{ attribute.cardinality | default: "0..1" }}]` +{% if attribute_docs != "" %} ++ +-- +{{ attribute_docs }} +-- +{% endif %} +{% if constraints != "" %} +{{ constraints }} +{% endif %} diff --git a/sources/unitsml-xml-schema/templates/_attribute_group.adoc b/sources/unitsml-xml-schema/templates/_attribute_group.adoc new file mode 100644 index 0000000..e344c4e --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_attribute_group.adoc @@ -0,0 +1,57 @@ +{%- assign item_attributes = item.attribute_elements -%} +{%- assign used_by_items = item.used_by -%} +{%- capture docs -%} +{% for paragraph in item.annotation.documentation -%} +{{ paragraph.content }} + +{% endfor -%} +{%- endcapture -%} +{%- assign docs = docs | strip -%} +{%- capture used_by_list -%} +{% for used_by in used_by_items -%} +* {{ used_by.name }} (<>) +{% endfor -%} +{%- endcapture -%} +{%- assign used_by_list = used_by_list | strip -%} +{%- capture attribute_list -%} +{% for attribute in item_attributes -%} +{% render "attribute", attribute: attribute %} + +{% endfor -%} +{%- endcapture -%} +{%- assign attribute_list = attribute_list | strip -%} + +[[xsd_{{ item.name }}]] +=== `{{ item.name }}` + +==== Group + +{% if docs != "" %} +{{ docs }} +{% else %} +No documentation supplied. +{% endif %} + +{% if used_by_items.size > 0 %} +This attribute group is used by: + +{{ used_by_list }} +{% endif %} + +==== Structure diagram + +{% render "diagram", item: item, attributes: item_attributes, schema: schema %} + +==== Attributes + +{% if item_attributes.size > 0 %} +{{ attribute_list }} +{% else %} +No attributes defined. +{% endif %} + +.XSD source of `{{ item.name }}` +[source,xml] +----- +{{ item.to_formatted_xml }} +----- diff --git a/sources/unitsml-xml-schema/templates/_attribute_value_constraints.adoc b/sources/unitsml-xml-schema/templates/_attribute_value_constraints.adoc new file mode 100644 index 0000000..fad266c --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_attribute_value_constraints.adoc @@ -0,0 +1,65 @@ +{%- assign simple_type = attribute.simple_type -%} +{%- if simple_type == nil and attribute.referenced_object -%} +{%- assign simple_type = attribute.referenced_object.simple_type -%} +{%- endif -%} +{%- if simple_type -%} +{%- assign restriction = simple_type.restriction -%} +{%- assign union = simple_type.union -%} +{%- if restriction -%} +{%- assign enum_values = restriction.enumeration | map: "value" -%} +{%- assign pattern_values = restriction.pattern | map: "value" -%} +{%- capture constraint_body -%} +{% if restriction.base -%} +Base type: `{{ restriction.base }}` +{% endif -%} +{% if enum_values.size > 0 %} + +Allowed values: + +{% for enum_value in enum_values %} +* `{{ enum_value }}` +{% endfor %} +{% endif -%} +{% if pattern_values.size > 0 %} + +Patterns: + +{% for pattern_value in pattern_values %} +* `{{ pattern_value }}` +{% endfor %} +{% endif -%} +{%- endcapture -%} +{%- assign constraint_body = constraint_body | strip -%} +{%- if constraint_body != "" %} ++ +-- +{{ constraint_body }} +-- +{% endif -%} +{%- elsif union -%} +{%- capture union_body -%} +{% if union.member_types -%} +Member types: `{{ union.member_types }}` +{% endif -%} +{% for union_simple_type in union.simple_type -%} +{% assign union_restriction = union_simple_type.restriction -%} +{% assign union_enum_values = union_restriction.enumeration | map: "value" -%} +{% if union_enum_values.size > 0 %} + +Allowed `{{ union_restriction.base }}` values: + +{% for union_enum_value in union_enum_values %} +* `{{ union_enum_value }}` +{% endfor %} +{% endif -%} +{% endfor -%} +{%- endcapture -%} +{%- assign union_body = union_body | strip -%} +{%- if union_body != "" %} ++ +-- +{{ union_body }} +-- +{% endif -%} +{%- endif -%} +{%- endif -%} diff --git a/sources/unitsml-xml-schema/templates/_child_elements.adoc b/sources/unitsml-xml-schema/templates/_child_elements.adoc new file mode 100644 index 0000000..7219604 --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_child_elements.adoc @@ -0,0 +1,34 @@ +{%- assign marker = marker | default: "*" -%} +{%- assign child_marker = marker | append: "*" -%} +{%- capture cardinality -%}[{{ child.min_occurrences | default: "1" }}..{{ child.max_occurrences | default: "1" }}]{%- endcapture -%} +{%- if child.annotation? or child.attribute? or child.attribute_group? -%} +{%- elsif child.sequence? %} +{{ marker }} Sequence {{ cardinality }} +{% for element in child.resolved_element_order -%} +{% render "child_elements", child: element, marker: child_marker %} +{% endfor -%} +{%- elsif child.choice? %} +{{ marker }} Choice {{ cardinality }} +{% for element in child.resolved_element_order -%} +{% render "child_elements", child: element, marker: child_marker %} +{% endfor -%} +{%- elsif child.all? %} +{{ marker }} All {{ cardinality }} +{% for element in child.resolved_element_order -%} +{% render "child_elements", child: element, marker: child_marker %} +{% endfor -%} +{%- elsif child.any? %} +{{ marker }} Any element from any namespace ({{ child.process_contents | default: "strict" }} processing) {{ cardinality }} +{%- elsif child.simple_content? %} +{{ marker }} Simple content based on `{{ child.base_type | default: child.base }}` {{ cardinality }} +{%- elsif child.element? -%} +{%- assign element_name = child.referenced_name | default: child.name | default: child.ref -%} +{%- assign element_type = child.referenced_type | default: child.type -%} +{{ marker }} `<{{ element_name }}>`{% if element_type %} of type `{{ element_type }}`{% endif %} {{ cardinality }} +{%- elsif child.child_elements.size > 0 -%} +{%- assign group_name = child.name | default: child.ref | default: "anonymous" -%} +{{ marker }} Group `{{ group_name }}` {{ cardinality }} +{% for element in child.child_elements -%} +{% render "child_elements", child: element, marker: child_marker %} +{% endfor -%} +{%- endif -%} diff --git a/sources/unitsml-xml-schema/templates/_complex_type.adoc b/sources/unitsml-xml-schema/templates/_complex_type.adoc new file mode 100644 index 0000000..934b550 --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_complex_type.adoc @@ -0,0 +1,106 @@ +{%- assign item_attributes = item.attribute_elements -%} +{%- assign used_by_items = item.used_by -%} +{%- assign content_model_items = item.resolved_element_order -%} +{%- capture docs -%} +{% for paragraph in item.annotation.documentation -%} +{{ paragraph.content }} + +{% endfor -%} +{%- endcapture -%} +{%- assign docs = docs | strip -%} +{%- capture used_by_list -%} +{% for used_by in used_by_items -%} +* {{ used_by.name }} (<>) +{% endfor -%} +{%- endcapture -%} +{%- assign used_by_list = used_by_list | strip -%} +{%- assign example_element = used_by_items | first -%} +{%- assign example_element_name = example_element.name -%} +{%- capture attribute_list -%} +{% for attribute in item_attributes -%} +{% render "attribute", attribute: attribute %} + +{% endfor -%} +{%- endcapture -%} +{%- assign attribute_list = attribute_list | strip -%} +{%- capture content_model_list -%} +{% for child in content_model_items -%} +{% render "child_elements", child: child %} +{% endfor -%} +{%- endcapture -%} +{%- assign content_model_list = content_model_list | strip -%} +{%- capture example_attributes -%} +{% for attr in item_attributes -%} +{% render "xml_example_attribute", attr: attr -%} +{% endfor -%} +{%- endcapture -%} +{%- capture example_children -%} +{% if item.mixed -%} + +{% endif -%} +{% for child in content_model_items -%} +{% render "xml_example_child", child: child, indent: " " -%} +{% endfor -%} +{%- endcapture -%} + +[[xsd_{{ item.name }}]] +=== `{{ item.name }}` + +==== General + +{% if docs != "" %} +{{ docs }} +{% else %} +No documentation supplied. +{% endif %} + +{% if used_by_items.size > 0 %} +This complex type is used by: + +{{ used_by_list }} +{% endif %} + +==== Structure diagram + +{% render "diagram", item: item, attributes: item_attributes, children: content_model_items, schema: schema %} + +==== Attributes + +{% if item_attributes.size > 0 %} +{{ attribute_list }} +{% else %} +No attributes defined. +{% endif %} + +==== Content model + +{% if item.mixed %} +This complex type allows mixed content. + +{% endif %} +{% if content_model_list != "" %} +{{ content_model_list }} +{% else %} +No child elements defined. +{% endif %} + +{% if example_element_name %} +[example] +.Illustrative element using `{{ item.name }}` +==== +[source,xml] +----- +<{{ example_element_name }}{{ example_attributes }}{% if example_children != "" %}> +{% if example_children != "" %}{{ example_children }}{% endif %} + +{% else %}/> +{% endif %} +----- +==== +{% endif %} + +.XSD source of `{{ item.name }}` +[source,xml] +----- +{{ item.to_formatted_xml }} +----- diff --git a/sources/unitsml-xml-schema/templates/_diagram.adoc b/sources/unitsml-xml-schema/templates/_diagram.adoc new file mode 100644 index 0000000..30ec16c --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_diagram.adoc @@ -0,0 +1,24 @@ +{%- assign root_id = "schema_" | append: item.name -%} +The diagram shows attributes and the content model in schema order. +Element edges show occurrence ranges; see the declarations below for all constraints. + +.Structure of `{{ item.name }}` +[plantuml,format=svg] +.... +@startuml xsd-{{ item.name }} +!pragma layout smetana +left to right direction +hide empty members +hide circle +skinparam classAttributeIconSize 0 +skinparam shadowing false +class "{{ item.name }}{% if item.element? and item.type %} : {{ item.type }}{% endif %}" as {{ root_id }} [[#xsd_{{ item.name }}]] { +{% for attribute in attributes %} +{%- assign attribute_name = attribute.referenced_name | default: attribute.name | default: attribute.ref -%} +{%- assign attribute_type = attribute.referenced_type | default: attribute.type -%} + @{{ attribute_name }}{% if attribute_type %} : {{ attribute_type }}{% endif %} [{{ attribute.cardinality | default: "0..1" }}] +{% endfor %} +} +{% render "diagram_children", children: children, parent_id: root_id, schema: schema %} +@enduml +.... diff --git a/sources/unitsml-xml-schema/templates/_diagram_children.adoc b/sources/unitsml-xml-schema/templates/_diagram_children.adoc new file mode 100644 index 0000000..1c489df --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_diagram_children.adoc @@ -0,0 +1,30 @@ +{%- assign position = 0 -%} +{% for child in children %} +{%- assign node_id = parent_id | append: "_" | append: forloop.index0 -%} +{%- assign minimum = child.min_occurs | default: child.min_occurrences | default: "1" -%} +{%- assign maximum = child.max_occurs | default: child.max_occurrences | default: "1" | replace: "unbounded", "*" -%} +{%- if child.annotation? or child.attribute? or child.attribute_group? -%} +{%- elsif child.element? -%} +{%- assign position = position | plus: 1 -%} +{%- assign element_name = child.referenced_name | default: child.name | default: child.ref -%} +{%- assign element_type = child.referenced_type | default: child.type -%} +{%- assign global_element = schema.elements_sorted_by_name | where: "name", element_name | first -%} +{%- assign global_type = schema.complex_types_sorted_by_name | where: "name", element_type | first -%} +class "{{ element_name }}{% if element_type %} : {{ element_type }}{% endif %}" as {{ node_id }}{% if global_element %} [[#xsd_{{ global_element.name }}]]{% elsif global_type %} [[#xsd_{{ global_type.name }}]]{% endif %} +{{ parent_id }} --> {{ node_id }} : {{ position }}. [{{ minimum }}..{{ maximum }}] +{%- elsif child.any? %} +{%- assign position = position | plus: 1 -%} +class "Any element\n{{ child.process_contents | default: "strict" }} processing" as {{ node_id }} +{{ parent_id }} --> {{ node_id }} : {{ position }}. [{{ minimum }}..{{ maximum }}] +{%- elsif child.simple_content? %} +{%- assign position = position | plus: 1 -%} +class "Simple content\n{{ child.base_type | default: child.base }}" as {{ node_id }} +{{ parent_id }} --> {{ node_id }} +{%- elsif child.resolved_element_order.size > 0 %} +{%- assign position = position | plus: 1 -%} +{%- capture label -%}{% if child.sequence? %}Sequence{% elsif child.choice? %}Choice{% elsif child.all? %}All{% elsif child.complex_content? %}Complex content{% else %}Group{% endif %}{%- endcapture %} +class "{{ label }}" as {{ node_id }} +{{ parent_id }} --> {{ node_id }} : {{ position }}. +{% render "diagram_children", children: child.resolved_element_order, parent_id: node_id, schema: schema %} +{% endif %} +{% endfor %} diff --git a/sources/unitsml-xml-schema/templates/_element.adoc b/sources/unitsml-xml-schema/templates/_element.adoc new file mode 100644 index 0000000..823f7b9 --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_element.adoc @@ -0,0 +1,107 @@ +{%- assign item_complex_type = item.referenced_complex_type -%} +{%- assign item_attributes = item.attributes -%} +{%- assign used_by_items = item.used_by -%} +{%- assign content_model_items = item_complex_type.resolved_element_order -%} +{%- capture docs -%} +{% for paragraph in item.annotation.documentation -%} +{{ paragraph.content }} + +{% endfor -%} +{%- endcapture -%} +{%- assign docs = docs | strip -%} +{%- capture used_by_list -%} +{% for used_by in used_by_items -%} +* {{ used_by.name }} (<>) +{% endfor -%} +{%- endcapture -%} +{%- assign used_by_list = used_by_list | strip -%} +{%- capture attribute_list -%} +{% for attribute in item_attributes -%} +{% render "attribute", attribute: attribute %} + +{% endfor -%} +{%- endcapture -%} +{%- assign attribute_list = attribute_list | strip -%} +{%- capture content_model_list -%} +{% for child in content_model_items -%} +{% render "child_elements", child: child %} +{% endfor -%} +{%- endcapture -%} +{%- assign content_model_list = content_model_list | strip -%} +{%- capture example_attributes -%} +{% for attr in item_attributes -%} +{% render "xml_example_attribute", attr: attr -%} +{% endfor -%} +{%- endcapture -%} +{%- capture example_children -%} +{% if item_complex_type.mixed -%} + +{% endif -%} +{% for child in content_model_items -%} +{% render "xml_example_child", child: child, indent: " " -%} +{% endfor -%} +{%- endcapture -%} + +[[xsd_{{ item.name }}]] +=== `<{{ item.name }}>` + +==== General + +{% if docs != "" %} +{{ docs }} +{% else %} +No documentation supplied. +{% endif %} + +{% if used_by_items.size > 0 %} +This element is used by: + +{{ used_by_list }} +{% endif %} + +==== Structure diagram + +{% render "diagram", item: item, attributes: item_attributes, children: content_model_items, schema: schema %} + +==== Attributes + +{% if item_attributes.size > 0 %} +{{ attribute_list }} +{% else %} +No attributes defined. +{% endif %} + +==== Content model + +{% if item.type %} +This element uses the `{{ item.type }}` type (<>). + +{% endif %} +{% if item_complex_type.mixed %} +This element allows mixed content. + +{% endif %} +{% if content_model_list != "" %} +{{ content_model_list }} +{% else %} +No child elements defined. +{% endif %} + +[example] +.Illustrative usage of `<{{ item.name }}>` +==== +[source,xml] +----- +<{{ item.name }}{{ example_attributes }}{% if example_children != "" %}> +{% if example_children != "" %}{{ example_children }}{% endif %} + +{% else %}/> +{% endif %} +----- +==== + +.XSD source of `<{{ item.name }}>` +[source,xml] +----- +{{ item.to_formatted_xml }} +----- diff --git a/sources/unitsml-xml-schema/templates/_xml_example_attribute.adoc b/sources/unitsml-xml-schema/templates/_xml_example_attribute.adoc new file mode 100644 index 0000000..33cc7a6 --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_xml_example_attribute.adoc @@ -0,0 +1,2 @@ +{%- assign attribute_name = attr.referenced_name | default: attr.name | default: attr.ref -%} +{%- assign attribute_value = attr.fixed | default: attr.default | default: attr.referenced_type | default: attr.type | default: "..." %} {{ attribute_name }}="{{ attribute_value }}"{%- comment -%}{%- endcomment -%} diff --git a/sources/unitsml-xml-schema/templates/_xml_example_child.adoc b/sources/unitsml-xml-schema/templates/_xml_example_child.adoc new file mode 100644 index 0000000..0daf809 --- /dev/null +++ b/sources/unitsml-xml-schema/templates/_xml_example_child.adoc @@ -0,0 +1,26 @@ +{%- assign indent = indent | default: " " -%} +{%- assign child_indent = indent | append: " " -%} +{%- if child.annotation? or child.attribute? or child.attribute_group? -%} +{%- elsif child.sequence? -%} +{% for element in child.resolved_element_order -%} +{% render "xml_example_child", child: element, indent: indent %} +{% endfor -%} +{%- elsif child.choice? %} +{{ indent }} +{% for element in child.resolved_element_order -%} +{% render "xml_example_child", child: element, indent: child_indent %} +{% endfor -%} +{%- elsif child.all? -%} +{% for element in child.resolved_element_order -%} +{% render "xml_example_child", child: element, indent: indent %} +{% endfor -%} +{%- elsif child.any? %} +{{ indent }} +{%- elsif child.element? -%} +{%- assign element_name = child.referenced_name | default: child.name | default: child.ref -%} +{{ indent }}<{{ element_name }}>... +{%- elsif child.child_elements.size > 0 -%} +{% for element in child.child_elements -%} +{% render "xml_example_child", child: element, indent: indent %} +{% endfor -%} +{%- endif -%}