From a589fa888786a88e1559838ce136f060bed87557 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 25 Mar 2025 19:45:23 +0800 Subject: [PATCH 1/2] feat: add unitsml urn document draft --- metanorma.yml | 1 + sources/unitsml-urn/document.adoc | 51 ++++ sources/unitsml-urn/sections/00-foreword.adoc | 35 +++ sources/unitsml-urn/sections/00-intro.adoc | 26 ++ sources/unitsml-urn/sections/01-scope.adoc | 12 + sources/unitsml-urn/sections/02-normrefs.adoc | 7 + sources/unitsml-urn/sections/03-terms.adoc | 45 ++++ .../unitsml-urn/sections/04-principles.adoc | 21 ++ sources/unitsml-urn/sections/05-elements.adoc | 229 ++++++++++++++++++ .../unitsml-urn/sections/06-composite.adoc | 152 ++++++++++++ .../sections/07-composite-normalize.adoc | 130 ++++++++++ sources/unitsml-urn/sections/08-urn.adoc | 52 ++++ .../sections/09-namespace-considerations.adoc | 37 +++ .../sections/10-community-considerations.adoc | 47 ++++ .../sections/11-security-considerations.adoc | 12 + sources/unitsml-urn/sections/12-iana.adoc | 48 ++++ .../unitsml-urn/sections/99-bibliography.adoc | 2 + sources/unitsml-urn/sections/a1-ebnf.adoc | 67 +++++ 18 files changed, 974 insertions(+) create mode 100644 sources/unitsml-urn/document.adoc create mode 100644 sources/unitsml-urn/sections/00-foreword.adoc create mode 100644 sources/unitsml-urn/sections/00-intro.adoc create mode 100644 sources/unitsml-urn/sections/01-scope.adoc create mode 100644 sources/unitsml-urn/sections/02-normrefs.adoc create mode 100644 sources/unitsml-urn/sections/03-terms.adoc create mode 100644 sources/unitsml-urn/sections/04-principles.adoc create mode 100644 sources/unitsml-urn/sections/05-elements.adoc create mode 100644 sources/unitsml-urn/sections/06-composite.adoc create mode 100644 sources/unitsml-urn/sections/07-composite-normalize.adoc create mode 100644 sources/unitsml-urn/sections/08-urn.adoc create mode 100644 sources/unitsml-urn/sections/09-namespace-considerations.adoc create mode 100644 sources/unitsml-urn/sections/10-community-considerations.adoc create mode 100644 sources/unitsml-urn/sections/11-security-considerations.adoc create mode 100644 sources/unitsml-urn/sections/12-iana.adoc create mode 100644 sources/unitsml-urn/sections/99-bibliography.adoc create mode 100644 sources/unitsml-urn/sections/a1-ebnf.adoc diff --git a/metanorma.yml b/metanorma.yml index b5d1d47..cf3e66b 100644 --- a/metanorma.yml +++ b/metanorma.yml @@ -4,6 +4,7 @@ metanorma: files: - sources/asciiunits/document.adoc - sources/unitsdb/document.adoc + - sources/unitsml-urn/document.adoc # - sources/unitsml-guide/document.adoc # - sources/unitsml-incorporation/document.adoc # - sources/unitsml-ubl-ndr-subset/document.adoc diff --git a/sources/unitsml-urn/document.adoc b/sources/unitsml-urn/document.adoc new file mode 100644 index 0000000..da16943 --- /dev/null +++ b/sources/unitsml-urn/document.adoc @@ -0,0 +1,51 @@ += CalConnect Standard: UnitsML URN namespace specification +:title: UnitsML URN namespace specification +:docnumber: 36811 +:copyright-year: 2025 +:doctype: standard +:edition: 1 +:status: committee-draft +:revdate: 2025-03-25 +:published-date: 2025-03-25 +:technical-committee: UnitsML +:fullname: Ronald Tse +:surname: Tse +:givenname: Ronald +:affiliation: 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-principles.adoc[] + +include::sections/05-elements.adoc[] + +include::sections/06-composite.adoc[] + +include::sections/07-composite-normalize.adoc[] + +include::sections/08-urn.adoc[] + +include::sections/09-namespace-considerations.adoc[] + +include::sections/10-community-considerations.adoc[] + +include::sections/11-security-considerations.adoc[] + +include::sections/12-iana.adoc[] + +include::sections/99-bibliography.adoc[] + +include::sections/a1-ebnf.adoc[] diff --git a/sources/unitsml-urn/sections/00-foreword.adoc b/sources/unitsml-urn/sections/00-foreword.adoc new file mode 100644 index 0000000..b0c4217 --- /dev/null +++ b/sources/unitsml-urn/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-urn/sections/00-intro.adoc b/sources/unitsml-urn/sections/00-intro.adoc new file mode 100644 index 0000000..71f4e52 --- /dev/null +++ b/sources/unitsml-urn/sections/00-intro.adoc @@ -0,0 +1,26 @@ +== Introduction + +=== General + +Units of measure are fundamental to scientific and technical information exchange. The UnitsML project has developed a comprehensive framework for representing units of measurement in machine-readable format. A critical aspect of this framework is the ability to uniquely and persistently identify units, dimensions, prefixes, quantities, and other related concepts. + +This document describes a Uniform Resource Name (URN) namespace for identifying UnitsML resources. The URN scheme provides a way to reference UnitsML elements across different systems and over time, ensuring consistent identification regardless of location or implementation. + +=== Purpose + +The purpose of the UnitsML URN namespace is to provide persistent, location-independent identifiers for UnitsML resources. This enables: + +* Unique identification of basic UnitsML elements such as units, dimensions, prefixes, quantities, unit systems, quantity kinds, and types of intervals +* Representation of composite expressions combining multiple elements +* References to specific versions of elements +* Machine-readable identifiers that can be used in various contexts, including XML, JSON, and plain text + +=== Relationship to other identification systems + +The UnitsML URN namespace is designed to be compatible with existing identification systems while providing a standardized approach specific to UnitsML resources. It builds upon: + +* RFC 8141, which defines the URN scheme +* The existing NIST UnitsML identifiers (e.g., NISTu11 for newton) +* ISO and OGC URN conventions as defined in RFC 5141 and RFC 5165 + +The UnitsML URN scheme provides a bridge between these systems, allowing for interoperability while maintaining the specific requirements of the UnitsML framework. diff --git a/sources/unitsml-urn/sections/01-scope.adoc b/sources/unitsml-urn/sections/01-scope.adoc new file mode 100644 index 0000000..e94a792 --- /dev/null +++ b/sources/unitsml-urn/sections/01-scope.adoc @@ -0,0 +1,12 @@ +== Scope + +This document specifies the syntax, semantics, and usage guidelines for the UnitsML URN namespace. It covers: + +* The basic structure of UnitsML URNs +* Identification of fundamental UnitsML elements (units, dimensions, prefixes, quantities, unit systems, quantity kinds, types of intervals) +* Representation of composite expressions in URN form +* Rules for constructing and interpreting UnitsML URNs +* Normalization algorithms for comparing equivalent expressions +* Namespace registration information as required by RFC 8141 + +This specification is intended to be used by developers, standards bodies, and organizations implementing UnitsML in their systems. diff --git a/sources/unitsml-urn/sections/02-normrefs.adoc b/sources/unitsml-urn/sections/02-normrefs.adoc new file mode 100644 index 0000000..40f2dca --- /dev/null +++ b/sources/unitsml-urn/sections/02-normrefs.adoc @@ -0,0 +1,7 @@ +[bibliography] +== Normative references + +* [[[unitsml-xml,UnitsML XML schema]]], https://www.unitsml.org +* [[[RFC_8141,IETF RFC 8141]]], _Uniform Resource Names (URNs)_ +* [[[RFC_5234,IETF RFC 5234]]], _Augmented BNF for Syntax Specifications: ABNF_ +* UnitsML, _Units Markup Language Specification_ diff --git a/sources/unitsml-urn/sections/03-terms.adoc b/sources/unitsml-urn/sections/03-terms.adoc new file mode 100644 index 0000000..8c25800 --- /dev/null +++ b/sources/unitsml-urn/sections/03-terms.adoc @@ -0,0 +1,45 @@ +== Terms and definitions + +=== basic element + +fundamental component in the UnitsML framework, including unit, dimension, prefix, quantity, unit system, quantity kind, and type of interval/unit scale + +=== composite expression + +combination of multiple basic elements using mathematical operations such as multiplication, division, and exponentiation + +=== NID + +namespace identifier, registered with IANA for use with URNs + +=== NSS + +namespace specific string, the portion of a URN that follows the "urn:" ":" and conforms to the specification of the NID + +=== unit + +reference quantity with which other quantities of the same kind are compared to express their value + +=== dimension + +expression of the dependence of a physical quantity on the base quantities of a system of quantities, in the form of a product of powers of factors corresponding to the base quantities, omitting any numerical factors + +=== prefix + +named multiple or submultiple of a unit, used to form decimal multiples or submultiples of units + +=== quantity + +property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference + +=== unit system + +set of units, together with a set of equations relating them + +=== quantity kind + +aspect common to mutually comparable quantities + +=== type of interval + +specification of how values in a scale or interval are related to each other, such as logarithmic, linear, or discrete \ No newline at end of file diff --git a/sources/unitsml-urn/sections/04-principles.adoc b/sources/unitsml-urn/sections/04-principles.adoc new file mode 100644 index 0000000..17e5dbc --- /dev/null +++ b/sources/unitsml-urn/sections/04-principles.adoc @@ -0,0 +1,21 @@ +== principles + +The UnitsML URN scheme follows these design principles: + +Simplicity:: +URNs should be easy to construct, parse, and understand + +Readability:: +When possible, URNs should be human-readable + +Uniqueness:: +Each URN must uniquely identify a specific resource + +Persistence:: +The meaning of a URN should not change over time + +Compatibility:: +The scheme should be compatible with existing UnitsML identifiers + +Extensibility:: +The scheme should accommodate future additions to the UnitsML framework diff --git a/sources/unitsml-urn/sections/05-elements.adoc b/sources/unitsml-urn/sections/05-elements.adoc new file mode 100644 index 0000000..44b7ab3 --- /dev/null +++ b/sources/unitsml-urn/sections/05-elements.adoc @@ -0,0 +1,229 @@ +== Syntax + +=== Core + +The basic structure of a UnitsML URN follows the general URN syntax defined in +<>. + +[source] +---- +urn:unitsml:: +---- + +Where: + +`unitsml`:: the NID (Namespace Identifier) + +``:: identifies the type of UnitsML element + +``:: is a unique identifier within the element type +namespace + +=== Entity types + +The UnitsML URN scheme defines the following entity types. + +[cols="1,4,1"] +|=== +|Type code |Description |Example + +|`u` |Unit | `urn:unitsml:u:newton` +|`d` |Dimension | `urn:unitsml:d:mass` +|`p` |Prefix | `urn:unitsml:p:kilo` +|`q` |Quantity | `urn:unitsml:q:luminous_intensity` +|`s` |Unit system |urn: `unitsml:s:si:base` +|`k` |Quantity kind | `urn:unitsml:k:length` +|`i` |Type of interval/unit scale | `urn:unitsml:i:log` +|=== + +Each entity type has its own namespace for identifiers, meaning the same +identifier can be used in different entity types without conflict. + + +=== Identifiers + +In UnitsDB, each entity is assigned the following unique identifiers: + +* `(id:, type:)` an identifier that is a combination of the identifier type and +the identifier itself, which is unique across the identifier type and unique +across all UnitsDB entity types. ++ +[example] +==== +The following is one of the identifiers for the unit "second" in UnitsDB. + +[source,yaml] +---- +id: NISTu3 +type: nist +---- +==== + +* `short:` a short name for the entity, which is unique within its type. ++ +[example] +==== +The following is one of the identifiers for the unit "second" in UnitsDB. + +[source,yaml] +---- +short: second +---- +==== + +These are the two only types of identifiers that are supported in the URN scheme for all entity types. + + +=== Units + +Units are fundamental entities in UnitsML, representing references for measurement. In the URN scheme, units are identified with the type code "u". + +[source] +---- +urn:unitsml:u: +---- + +Where, + +``:: is a unique identifier for the unit, which can be its UnitsDB ID conjoined using the `:` (colon) or the unique short name. + +[source] +---- +// By short name +urn:unitsml:u:newton +urn:unitsml:u:meter +urn:unitsml:u:kilogram + +// By identifier +urn:unitsml:u:nist:NISTu3 +---- + +For prefixed units, the prefix is considered part of the unit name: + +[source] +---- +urn:unitsml:u:millimeter // millimeter as a complete unit +---- + + +=== Dimensions + +Dimensions represent the physical nature of quantities. In the URN scheme, dimensions are identified with the type code "d". + +[source] +---- +urn:unitsml:d: +---- + +Examples: + +[source] +---- +urn:unitsml:d:length // By short name +urn:unitsml:d:mass // mass dimension +urn:unitsml:d:time // time dimension + +// By identifier +urn:unitsml:d:nist:NISTd5 // temperature dimension +---- + +=== Prefixes + +Prefixes are used to form decimal multiples or submultiples of units. In the URN scheme, prefixes are identified with the type code "p". + +[source] +---- +urn:unitsml:p: +---- + +or with explicit base and power values: + +[source] +---- +urn:unitsml:p:: +---- + +Examples: + +[source] +---- +urn:unitsml:p:kilo // By short name (kilo) +urn:unitsml:p:10:3 // Base 10, power 3 (kilo) +urn:unitsml:p:mebi // By short name (mebi) +urn:unitsml:p:2:20 // Base 2, power 20 (mebi) + +urn:unitsml:p:nist:NISTp10_-1 // deci +---- + + +=== Quantities + +Quantities represent properties that can be measured. In the URN scheme, quantities are identified with the type code "q". + +[source] +---- +urn:unitsml:q: +---- + +Examples: + +[source] +---- +urn:unitsml:q:luminous_intensity // By short name +urn:unitsml:q:length // length quantity + +urn:unitsml:q:nist:NISTq12 // velocity quantity +---- + +=== Unit systems + +Unit systems represent coherent sets of units. In the URN scheme, unit systems are identified with the type code "s". + +[source] +---- +urn:unitsml:s: +---- + +Examples: + +[source] +---- +urn:unitsml:s:si-base // SI base unit system +urn:unitsml:s:si-derived-nonspecial +---- + + +=== Quantity kinds + +Quantity kinds represent aspects common to mutually comparable quantities. In the URN scheme, quantity kinds are identified with the type code "k". + +[source] +---- +urn:unitsml:k: +---- + +Examples: + +[source] +---- +urn:unitsml:k:length // Length quantity kind +urn:unitsml:k:energy // Energy quantity kind +---- + +=== Type of interval/unit scale + +Types of interval represent how values in a scale are related. In the URN scheme, interval types are identified with the type code "i". + +[source] +---- +urn:unitsml:i: +---- + +Examples: + +[source] +---- +urn:unitsml:i:log // Logarithmic interval +urn:unitsml:i:discreet // Discrete interval +---- + diff --git a/sources/unitsml-urn/sections/06-composite.adoc b/sources/unitsml-urn/sections/06-composite.adoc new file mode 100644 index 0000000..861177d --- /dev/null +++ b/sources/unitsml-urn/sections/06-composite.adoc @@ -0,0 +1,152 @@ +== Composite expressions + +=== General + +Composite expressions in UnitsML URNs allow for the representation of complex units, dimensions, and quantities. These expressions combine basic elements using mathematical operations to represent derived units or dimensions. + +=== Syntax for composite expressions + +A composite expression is indicated by a double colon after the element type: + +[source] +---- +urn:unitsml::: +---- + +Within the composite expression, the following operators and symbols are used: + +[cols="1,2,2"] +|=== +|Operator |Description |Example + +|* |Multiplication |meter*second +|/ |Division |meter/second +|_e_ |Exponentiation |meter_e_2 +|sqrt() |Square root |sqrt(meter) +|() |Grouping |(newton*meter)/second +|=== + +=== Operations + +==== Multiplication + +Multiplication is represented by the asterisk (*) symbol. It combines two or more elements by multiplication. + +[example] +==== +[source] +---- +urn:unitsml:u::meter*second // meter times second +urn:unitsml:u::newton*meter // newton meter +urn:unitsml:d::length*time // length times time +---- +==== + +==== Division + +Division is represented by the forward slash (/) symbol. It divides one element by another. + +[example] +==== +[source] +---- +urn:unitsml:u::meter/second // meter per second +urn:unitsml:d::length/time // length per time +urn:unitsml:u::(1/3) // fractional number +---- +==== + +==== Exponentiation + +Exponentiation is represented by the `_e_` notation followed by the exponent value. + +[example] +==== +[source] +---- +urn:unitsml:u::meter_e_2 // square meter +urn:unitsml:u::second_e_-1 // per second +urn:unitsml:d::length_e_3 // volume dimension +---- +==== + +==== Square root + +Square root is represented either by the `sqrt()` function or by exponentiation with a fractional exponent. + +[example] +==== +[source] +---- +urn:unitsml:u::sqrt(meter) // square root of meter +urn:unitsml:u::meter_e_0.5 // alternative representation +urn:unitsml:u::meter_e_(1/2) // alternative with fraction +---- +==== + +==== Grouping + +Grouping is represented by parentheses and is used to control the order of operations. + +[example] +==== +[source] +---- +urn:unitsml:u::(newton*meter)/second // newton meter per second +urn:unitsml:u::newton*(meter/second) // newton times meter per second +---- +==== + +=== Conversion from NIST Legacy IDs + +The new URN scheme provides a way to represent the same composite expressions that were previously represented using the NIST legacy ID notation. + +[example] +==== +Legacy ID: `NISTu9.u3e-2/1` + +URN representation: `urn:unitsml:u::radian*second_e_-2` or `urn:unitsml:u::radian/second_e_2` + +This represents "radian per second squared". +==== + +[example] +==== +Legacy ID: `NISTu11.u1e2/1.u27p10'3e-2/1` + +URN representation: `urn:unitsml:u::newton*meter_e_2*kilogram_e_-2` or `urn:unitsml:u::(newton*meter_e_2)/(kilogram_e_2)` + +This represents "newton meter squared per kilogram squared". +==== + +=== Complete examples + +Here are complete examples of composite expressions in URN form: + +[example] +==== +[source] +---- +// Basic units +urn:unitsml:u:meter # Base unit +urn:unitsml:u:millimeter # Prefixed unit + +// Composite units +urn:unitsml:u::meter/second # Meter per second +urn:unitsml:u::meter*second_e_-1 # Alternative representation + +// Dimensions +urn:unitsml:d:length # Base dimension +urn:unitsml:d::length/time # Composite dimension + +// Quantities +urn:unitsml:q:mass # Base quantity +urn:unitsml:q::mass*acceleration # Composite quantity + +// Complex expressions +urn:unitsml:u::radian*second_e_-2 # Radian per second squared +urn:unitsml:u::(newton*meter_e_2)/(kilogram_e_2) # Newton meter squared per kilogram squared +urn:unitsml:u::sqrt(meter) # Square root of meter +urn:unitsml:d::length*time_e_-2 # Acceleration dimension +---- +==== diff --git a/sources/unitsml-urn/sections/07-composite-normalize.adoc b/sources/unitsml-urn/sections/07-composite-normalize.adoc new file mode 100644 index 0000000..95a7d2c --- /dev/null +++ b/sources/unitsml-urn/sections/07-composite-normalize.adoc @@ -0,0 +1,130 @@ +== Composite expression normalization + +=== General + +To ensure consistent interpretation and comparison of composite expressions, a normalization algorithm is defined. This algorithm converts any valid composite expression into a canonical form that can be used for equivalence checking and other operations. + +=== Normalization rules + +The normalization process applies the following rules: + +. *Ordering*: Elements should be ordered alphabetically within each term. +. *Simplification*: Common terms in numerator and denominator should be canceled. +. *Exponent consolidation*: Multiple occurrences of the same element should be consolidated with their exponents added. +. *Grouping*: Parentheses should only be used when necessary for precedence. +. *Names*: Short names should be used consistently within expressions. +. *Form*: Negative exponents are preferred over division for canonical representation. + +=== Normalization algorithm + +The normalization algorithm consists of the following steps: + +. *Parsing*: Parse the composite expression into a structured representation. + +. *Term extraction*: Identify all terms and their associated exponents. + a. For multiplication expressions, extract each term with its positive exponent. + b. For division expressions, extract the denominator terms with negative exponents. + c. For exponentiation, apply the exponent to the base term. + d. For square root, convert to exponentiation with exponent 0.5. + +. *Term combination*: Combine like terms by adding their exponents. + a. Group terms with the same base element. + b. Add the exponents for each group. + c. Remove terms with zero exponent. + +. *Term sorting*: Sort the terms alphabetically by base element name. + +. *Expression reconstruction*: + a. Use multiplication to combine terms with non-zero exponents. + b. Express terms with negative exponents using the `_e_` notation rather than division. + c. Only use parentheses when grouping affects the result. + +=== Step-by-step examples + +Here are step-by-step examples of the normalization process: + +[example] +==== +*Original expression*: `meter*second*meter` + +*Step 1*: Parse the expression. +Terms: `meter`, `second`, `meter` + +*Step 2*: Extract terms and exponents. +Terms with exponents: `meter^1`, `second^1`, `meter^1` + +*Step 3*: Combine like terms. +Grouped terms: `meter^2`, `second^1` + +*Step 4*: Sort terms alphabetically. +Sorted terms: `meter^2`, `second^1` + +*Step 5*: Reconstruct the expression. +Normalized expression: `meter_e_2*second` +==== + +[example] +==== +*Original expression*: `(newton*meter_e_2)/(kilogram_e_2)` + +*Step 1*: Parse the expression. +Terms: `newton`, `meter_e_2` in numerator, `kilogram_e_2` in denominator + +*Step 2*: Extract terms and exponents. +Terms with exponents: `newton^1`, `meter^2`, `kilogram^-2` + +*Step 3*: Combine like terms. +Grouped terms: `newton^1`, `meter^2`, `kilogram^-2` + +*Step 4*: Sort terms alphabetically. +Sorted terms: `kilogram^-2`, `meter^2`, `newton^1` + +*Step 5*: Reconstruct the expression. +Normalized expression: `kilogram_e_-2*meter_e_2*newton` +==== + +[example] +==== +*Original expression*: `meter/second/second` + +*Step 1*: Parse the expression. +Terms: `meter` in numerator, `second`, `second` in denominators + +*Step 2*: Extract terms and exponents. +Terms with exponents: `meter^1`, `second^-1`, `second^-1` + +*Step 3*: Combine like terms. +Grouped terms: `meter^1`, `second^-2` + +*Step 4*: Sort terms alphabetically. +Sorted terms: `meter^1`, `second^-2` + +*Step 5*: Reconstruct the expression. +Normalized expression: `meter*second_e_-2` +==== + +=== Comparison of expressions + +Two composite expressions are considered equivalent if they normalize to the same canonical form. This allows for comparison of expressions that may be written differently but represent the same underlying quantity. + +[example] +==== +Expression 1: `meter/second` +Normalized: `meter*second_e_-1` + +Expression 2: `meter*second_e_-1` +Normalized: `meter*second_e_-1` + +Result: These expressions are equivalent. +==== + +[example] +==== +Expression 1: `newton*meter` +Normalized: `meter*newton` + +Expression 2: `meter*newton` +Normalized: `meter*newton` + +Result: These expressions are equivalent. +==== diff --git a/sources/unitsml-urn/sections/08-urn.adoc b/sources/unitsml-urn/sections/08-urn.adoc new file mode 100644 index 0000000..b14ee72 --- /dev/null +++ b/sources/unitsml-urn/sections/08-urn.adoc @@ -0,0 +1,52 @@ + +== URN Specification for "unitsml" NID + +=== NID Definitions + +[source] +---- +NID = "unitsml" +---- + +=== Syntax for the NSS (Namespace Specific String) + +The general syntax for the unitsml NSS follows this pattern: + +[source] +---- +NSS = element-reference / composite-expression +element-reference = element-type ":" element-id +composite-expression = element-type "::" expression +element-type = "u" / "d" / "p" / "q" / "s" / "k" / "i" +element-id = number / name / hierarchical-id / prefix-with-power +expression = term *( operator term ) +---- + +==== Element type definitions + +[source] +---- +number = 1*DIGIT +name = 1*( ALPHA / DIGIT / "_" / "-" ) +hierarchical-id = name *( ":" name ) +prefix-with-power = base ":" power +base = number +power = ["-"] number +---- + +==== Expression syntax + +[source] +---- +term = simple-term / grouped-term / function-term +simple-term = name [exponent] +grouped-term = "(" expression ")" [exponent] +function-term = function-name "(" expression ")" +function-name = "sqrt" +exponent = "_e_" exponent-value +exponent-value = number / fraction / grouped-exponent +fraction = "(" number "/" number ")" +grouped-exponent = "(" ["-"] number ["." number] ")" +operator = "*" / "/" +---- + diff --git a/sources/unitsml-urn/sections/09-namespace-considerations.adoc b/sources/unitsml-urn/sections/09-namespace-considerations.adoc new file mode 100644 index 0000000..4fd28e5 --- /dev/null +++ b/sources/unitsml-urn/sections/09-namespace-considerations.adoc @@ -0,0 +1,37 @@ +== Namespace considerations + +=== Assignment + +The following provides background information on the process that led to the need for a UnitsML URN namespace and motivation for key aspects of the naming structure. + +The UnitsML Technical Committee has developed a comprehensive framework for representing units of measure in machine-readable formats. As this framework has evolved, the need for persistent, unique identifiers for UnitsML elements has become apparent. + +The UnitsML URN namespace was developed to address this need, providing a way to uniquely identify and reference UnitsML elements across different systems and implementations. The namespace is designed to be compatible with existing UnitsML identifiers while providing a standardized approach to identification. + +=== ID uniqueness + +The unitsml URN namespace ensures uniqueness of identifiers through several mechanisms: + +1. *Element type separation*: Each element type has its own namespace, allowing the same identifier to be used in different element types without conflict. +2. *Dual identification system*: Elements can be identified by either numerical ID or short name, with a one-to-one mapping between these identifiers. +3. *Hierarchical namespaces*: For elements such as unit systems, hierarchical identifiers are used to avoid conflicts. +4. *Centralized registration*: The UnitsML Technical Committee maintains a central registry of identifiers to prevent duplicates. + +=== Identifier assignment + +Identifiers within the unitsml namespace are assigned according to the following principles: + +1. *Numerical IDs*: Numerical IDs are assigned sequentially as new elements are added to the UnitsML database. +2. *Short names*: Short names are derived from the common name of the element, converted to lowercase, with spaces replaced by underscores. +3. *Hierarchical IDs*: Hierarchical IDs follow a logical organization, with broader categories preceding more specific ones. +4. *Prefix powers*: For prefixes, the base and power are included in the identifier to facilitate automated processing. + +=== URN resolution + +Resolution of unitsml URNs to resources is not part of this specification. However, implementations may provide resolution mechanisms to retrieve information about the identified element, such as: + +1. *Web services*: HTTP-based services that return information about the identified element. +2. *Databases*: Local or remote databases that can be queried using the URN. +3. *Registries*: Central registries maintained by standards bodies or organizations. + +The primary purpose of unitsml URNs is to provide stable, unique identifiers for reference, not necessarily to directly access resources. diff --git a/sources/unitsml-urn/sections/10-community-considerations.adoc b/sources/unitsml-urn/sections/10-community-considerations.adoc new file mode 100644 index 0000000..d5bfc18 --- /dev/null +++ b/sources/unitsml-urn/sections/10-community-considerations.adoc @@ -0,0 +1,47 @@ +== Community considerations + +=== General + +The UnitsML URN namespace serves the needs of several communities: + +1. *Scientific and engineering communities*: Researchers, engineers, and scientists who need to exchange measurement data. +2. *Data management organizations*: Groups responsible for managing and exchanging scientific and technical data. +3. *Standards bodies*: Organizations developing standards for measurement and data exchange. +4. *Software developers*: Developers implementing systems that handle measurement data. + +=== Benefits + +The benefits of the unitsml URN namespace for these communities include: + +1. *Unambiguous identification*: Clear, unique identification of measurement units and related concepts. +2. *Interoperability*: Common identification system that works across different platforms and implementations. +3. *Persistence*: Stable references that remain valid over time, independent of physical location. +4. *Machine processability*: Identifiers that can be parsed and processed by software. + +=== Registration and authority + +The UnitsML Technical Committee serves as the authority for the unitsml URN namespace. The committee will: + +1. *Maintain a registry*: Keep a central registry of all assigned identifiers. +2. *Review new additions*: Review and approve new elements to be added to the namespace. +3. *Ensure consistency*: Ensure that new identifiers follow the established patterns and conventions. +4. *Provide documentation*: Maintain documentation on the namespace and its elements. + +=== Process for identifier updates + +The process for updating and adding identifiers to the unitsml namespace includes: + +1. *Proposal*: Submission of a proposal for a new element or identifier. +2. *Review*: Review by the UnitsML Technical Committee for consistency and necessity. +3. *Approval*: Formal approval and assignment of identifiers. +4. *Publication*: Publication of the new identifier in the central registry. +5. *Notification*: Notification to the community of the addition. + +=== Responsibility for the namespace + +The UnitsML Technical Committee takes responsibility for the unitsml namespace, including: + +1. *Ensuring stability*: Maintaining the stability and persistence of identifiers. +2. *Preventing conflicts*: Preventing naming conflicts and duplicate identifiers. +3. *Documentation*: Providing clear documentation on the namespace and its usage. +4. *Accessibility*: Ensuring that information about identifiers is accessible to the community. \ No newline at end of file diff --git a/sources/unitsml-urn/sections/11-security-considerations.adoc b/sources/unitsml-urn/sections/11-security-considerations.adoc new file mode 100644 index 0000000..af3ca24 --- /dev/null +++ b/sources/unitsml-urn/sections/11-security-considerations.adoc @@ -0,0 +1,12 @@ +== Security considerations + +The unitsml URN namespace does not introduce any security issues beyond those associated with the use of URNs in general. However, implementers should be aware of the following considerations: + +1. *Input validation*: When processing unitsml URNs, implementations should validate the input to prevent injection attacks. +2. *Reference integrity*: Systems using unitsml URNs should verify the existence and validity of referenced elements before processing. +3. *Authority*: Implementers should verify that unitsml URNs come from authoritative sources, especially when using them for critical calculations. +4. *Resource consumption*: Processing complex composite expressions may consume significant resources and should be monitored for potential denial-of-service issues. + +These considerations are not unique to the unitsml namespace but are standard practice for systems dealing with external identifiers and references. + +There are no additional security concerns related to the unitsml namespace itself. \ No newline at end of file diff --git a/sources/unitsml-urn/sections/12-iana.adoc b/sources/unitsml-urn/sections/12-iana.adoc new file mode 100644 index 0000000..1adbbe0 --- /dev/null +++ b/sources/unitsml-urn/sections/12-iana.adoc @@ -0,0 +1,48 @@ + +== IANA considerations + +This section provides information required for the registration of the unitsml URN namespace with the Internet Assigned Numbers Authority (IANA), as required by RFC 8141. + +Namespace ID:: unitsml + +Registration information:: +Registration version number::: 1 +Registration date::: 2025-03-25 + +Registrant information:: +Registrant::: UnitsML Technical Committee +Contact information::: (Appropriate contact details to be added) + +Declared registrant of the namespace:: UnitsML Technical Committee + +Declaration of syntactic structure:: The syntax of unitsml URNs follows the pattern: ++ +[source] +---- +urn:unitsml:: +---- +or +[source] +---- +urn:unitsml::: +---- ++ +Where `` is one of "u", "d", "p", "q", "s", "k", or "i", and `` and `` follow the rules specified in this document. + +Relevant ancillary documentation:: This document serves as the primary specification for the unitsml URN namespace. Additional documentation may be provided by the UnitsML Technical Committee. + +Identifier uniqueness considerations:: Uniqueness is ensured through the use of element type namespaces, central registration, and the processes described in this document. + +Identifier persistence considerations:: The UnitsML Technical Committee guarantees the persistence of unitsml URNs through active management of the namespace and adherence to the principles outlined in this document. + +Process of identifier assignment:: Identifiers are assigned by the UnitsML Technical Committee following the processes described in this document. + +Process for identifier resolution:: This namespace does not require resolution services. + +Rules for lexical equivalence:: Two unitsml URNs are considered lexically equivalent if they match exactly after normalization of composite expressions as described in this document. + +Conformance with URN syntax:: All unitsml URNs conform to the syntax requirements of RFC 8141. + +Validation mechanism:: Validation can be performed by checking against the formal grammar provided in this document and by verifying the existence of the referenced element in the UnitsML database. + +Scope:: The unitsml URN namespace is global in scope, intended for use in all contexts where UnitsML elements need to be identified. diff --git a/sources/unitsml-urn/sections/99-bibliography.adoc b/sources/unitsml-urn/sections/99-bibliography.adoc new file mode 100644 index 0000000..f494396 --- /dev/null +++ b/sources/unitsml-urn/sections/99-bibliography.adoc @@ -0,0 +1,2 @@ +[bibliography] +== Bibliography diff --git a/sources/unitsml-urn/sections/a1-ebnf.adoc b/sources/unitsml-urn/sections/a1-ebnf.adoc new file mode 100644 index 0000000..1a1f9b5 --- /dev/null +++ b/sources/unitsml-urn/sections/a1-ebnf.adoc @@ -0,0 +1,67 @@ + +[appendix,obligation=informative] +== ABNF Definition of Namespace ID = "unitsml" + +This appendix provides the formal ABNF (Augmented Backus-Naur Form) definition for the syntax of UnitsML URNs, according to RFC 5234. + +[source] +---- +; Basic rules for UnitsML URNs +unitsml-urn = "urn:unitsml:" element-reference + +; Element reference can be either a simple reference or a composite expression +element-reference = simple-reference / composite-reference + +; Simple reference to an element by type and ID +simple-reference = element-type ":" element-id + +; Composite expression +composite-reference = element-type "::" expression + +; Element types +element-type = "u" / "d" / "p" / "q" / "s" / "k" / "i" + +; Element identifiers can be numeric, named, hierarchical, or prefix specifications +element-id = number / name / hierarchical-id / prefix-with-power + +; Numeric identifier +number = 1*DIGIT + +; Named identifier +name = 1*( ALPHA / DIGIT / "_" / "-" ) + +; Hierarchical identifier with colon separators +hierarchical-id = name *( ":" name ) + +; Prefix specification with base and power +prefix-with-power = base ":" power +base = number +power = ["-"] number + +; Expression syntax for composite expressions +expression = term *( operator term ) + +; Terms can be simple, grouped, or function applications +term = simple-term / grouped-term / function-term + +; Simple term with optional exponent +simple-term = name [exponent] + +; Grouped expression with optional exponent +grouped-term = "(" expression ")" [exponent] + +; Function application +function-term = function-name "(" expression ")" +function-name = "sqrt" + +; Exponent notation +exponent = "_e_" exponent-value +exponent-value = number / fraction / grouped-exponent +fraction = "(" number "/" number ")" +grouped-exponent = "(" ["-"] number ["." number] ")" + +; Operators for combining terms +operator = "*" / "/" +---- + +This ABNF grammar provides a formal definition of the syntax for UnitsML URNs, ensuring consistent parsing and interpretation across implementations. From 63a89c0415a6cfa8a47e33512eb4f7c0e6c6f93f Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Sun, 21 Sep 2025 19:37:25 +0800 Subject: [PATCH 2/2] chore: update --- sources/unitsml-urn/sections/00-intro.adoc | 36 +- sources/unitsml-urn/sections/01-scope.adoc | 8 +- sources/unitsml-urn/sections/02-normrefs.adoc | 3 + sources/unitsml-urn/sections/03-terms.adoc | 28 +- sources/unitsml-urn/sections/05-elements.adoc | 92 +++- .../unitsml-urn/sections/06-composite.adoc | 413 ++++++++++++++++-- .../sections/07-composite-normalize.adoc | 107 +++-- sources/unitsml-urn/sections/08-urn.adoc | 45 +- .../sections/09-namespace-considerations.adoc | 48 +- .../sections/10-community-considerations.adoc | 51 ++- .../sections/11-security-considerations.adoc | 27 +- sources/unitsml-urn/sections/12-iana.adoc | 42 +- .../unitsml-urn/sections/99-bibliography.adoc | 3 + sources/unitsml-urn/sections/a1-ebnf.adoc | 24 +- unitsdb | 2 +- 15 files changed, 739 insertions(+), 190 deletions(-) diff --git a/sources/unitsml-urn/sections/00-intro.adoc b/sources/unitsml-urn/sections/00-intro.adoc index 71f4e52..ee215b0 100644 --- a/sources/unitsml-urn/sections/00-intro.adoc +++ b/sources/unitsml-urn/sections/00-intro.adoc @@ -2,25 +2,43 @@ === General -Units of measure are fundamental to scientific and technical information exchange. The UnitsML project has developed a comprehensive framework for representing units of measurement in machine-readable format. A critical aspect of this framework is the ability to uniquely and persistently identify units, dimensions, prefixes, quantities, and other related concepts. +UnitsML is a comprehensive framework for representing units of measurement in +machine-readable format. A critical aspect of this framework is the ability to +uniquely and persistently identify units, dimensions, prefixes, quantities, and +other related concepts. -This document describes a Uniform Resource Name (URN) namespace for identifying UnitsML resources. The URN scheme provides a way to reference UnitsML elements across different systems and over time, ensuring consistent identification regardless of location or implementation. +This document describes a Uniform Resource Name (URN) namespace for identifying +UnitsML resources. The URN scheme provides a way to reference UnitsML elements +across different systems and over time, ensuring consistent identification +regardless of location or implementation. === Purpose -The purpose of the UnitsML URN namespace is to provide persistent, location-independent identifiers for UnitsML resources. This enables: +The purpose of the UnitsML URN namespace is to provide persistent, +location-independent identifiers for UnitsML resources. + +This enables: + +* Unique identification of basic UnitsML elements such as units, dimensions, +prefixes, quantities, unit systems, quantity kinds, and unit scales -* Unique identification of basic UnitsML elements such as units, dimensions, prefixes, quantities, unit systems, quantity kinds, and types of intervals * Representation of composite expressions combining multiple elements + * References to specific versions of elements -* Machine-readable identifiers that can be used in various contexts, including XML, JSON, and plain text + +* Machine-readable identifiers that can be used in various contexts, including +XML, JSON, and plain text === Relationship to other identification systems -The UnitsML URN namespace is designed to be compatible with existing identification systems while providing a standardized approach specific to UnitsML resources. It builds upon: +The UnitsML URN namespace is designed to be compatible with existing identification systems while providing a standardized approach specific to UnitsML resources. + +It builds upon: * RFC 8141, which defines the URN scheme -* The existing NIST UnitsML identifiers (e.g., NISTu11 for newton) -* ISO and OGC URN conventions as defined in RFC 5141 and RFC 5165 +* UnitsML entity identifiers (e.g., `u:newton` for newton) +* Legacy NIST UnitsML entity identifiers (e.g., `NISTu11` for newton) -The UnitsML URN scheme provides a bridge between these systems, allowing for interoperability while maintaining the specific requirements of the UnitsML framework. +The UnitsML URN scheme provides a bridge between these systems, allowing for +interoperability while maintaining the specific requirements of the UnitsML +framework. diff --git a/sources/unitsml-urn/sections/01-scope.adoc b/sources/unitsml-urn/sections/01-scope.adoc index e94a792..af11047 100644 --- a/sources/unitsml-urn/sections/01-scope.adoc +++ b/sources/unitsml-urn/sections/01-scope.adoc @@ -1,6 +1,9 @@ == Scope -This document specifies the syntax, semantics, and usage guidelines for the UnitsML URN namespace. It covers: +This document specifies the syntax, semantics, and usage guidelines for the +UnitsML URN namespace. + +It covers: * The basic structure of UnitsML URNs * Identification of fundamental UnitsML elements (units, dimensions, prefixes, quantities, unit systems, quantity kinds, types of intervals) @@ -9,4 +12,5 @@ This document specifies the syntax, semantics, and usage guidelines for the Unit * Normalization algorithms for comparing equivalent expressions * Namespace registration information as required by RFC 8141 -This specification is intended to be used by developers, standards bodies, and organizations implementing UnitsML in their systems. +This specification is intended to be used by developers, standards bodies, and +organizations implementing UnitsML in their systems. diff --git a/sources/unitsml-urn/sections/02-normrefs.adoc b/sources/unitsml-urn/sections/02-normrefs.adoc index 40f2dca..633505e 100644 --- a/sources/unitsml-urn/sections/02-normrefs.adoc +++ b/sources/unitsml-urn/sections/02-normrefs.adoc @@ -2,6 +2,9 @@ == Normative references * [[[unitsml-xml,UnitsML XML schema]]], https://www.unitsml.org + * [[[RFC_8141,IETF RFC 8141]]], _Uniform Resource Names (URNs)_ + * [[[RFC_5234,IETF RFC 5234]]], _Augmented BNF for Syntax Specifications: ABNF_ + * UnitsML, _Units Markup Language Specification_ diff --git a/sources/unitsml-urn/sections/03-terms.adoc b/sources/unitsml-urn/sections/03-terms.adoc index 8c25800..5675c37 100644 --- a/sources/unitsml-urn/sections/03-terms.adoc +++ b/sources/unitsml-urn/sections/03-terms.adoc @@ -2,11 +2,13 @@ === basic element -fundamental component in the UnitsML framework, including unit, dimension, prefix, quantity, unit system, quantity kind, and type of interval/unit scale +fundamental component in the UnitsML framework, including unit, dimension, +prefix, quantity, unit system, quantity kind, and unit scale === composite expression -combination of multiple basic elements using mathematical operations such as multiplication, division, and exponentiation +combination of multiple basic elements using mathematical operations such as +multiplication, division, and exponentiation === NID @@ -14,23 +16,29 @@ namespace identifier, registered with IANA for use with URNs === NSS -namespace specific string, the portion of a URN that follows the "urn:" ":" and conforms to the specification of the NID +namespace specific string, the portion of a URN that follows the "urn:" +":" and conforms to the specification of the NID === unit -reference quantity with which other quantities of the same kind are compared to express their value +reference quantity with which other quantities of the same kind are compared to +express their value === dimension -expression of the dependence of a physical quantity on the base quantities of a system of quantities, in the form of a product of powers of factors corresponding to the base quantities, omitting any numerical factors +expression of the dependence of a physical quantity on the base quantities of a +system of quantities, in the form of a product of powers of factors +corresponding to the base quantities, omitting any numerical factors === prefix -named multiple or submultiple of a unit, used to form decimal multiples or submultiples of units +named multiple or submultiple of a unit, used to form decimal multiples or +submultiples of units === quantity -property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference +property of a phenomenon, body, or substance, where the property has a magnitude +that can be expressed as a number and a reference === unit system @@ -40,6 +48,8 @@ set of units, together with a set of equations relating them aspect common to mutually comparable quantities -=== type of interval +=== unit scale -specification of how values in a scale or interval are related to each other, such as logarithmic, linear, or discrete \ No newline at end of file +specification of how values in a measurement scale are related, characterized by +properties such as whether they are continuous or discrete, ordered, +logarithmic, and whether they support interval or ratio comparisons diff --git a/sources/unitsml-urn/sections/05-elements.adoc b/sources/unitsml-urn/sections/05-elements.adoc index 44b7ab3..906b5d5 100644 --- a/sources/unitsml-urn/sections/05-elements.adoc +++ b/sources/unitsml-urn/sections/05-elements.adoc @@ -50,7 +50,13 @@ across all UnitsDB entity types. + [example] ==== -The following is one of the identifiers for the unit "second" in UnitsDB. +The following are identifiers for the unit "second" in UnitsDB. + +[source,yaml] +---- +id: u:second +type: unitsml +---- [source,yaml] ---- @@ -85,7 +91,7 @@ urn:unitsml:u: Where, -``:: is a unique identifier for the unit, which can be its UnitsDB ID conjoined using the `:` (colon) or the unique short name. +``:: is a unique identifier for the unit, which can be its UnitsDB ID directly, its UnitsDB ID conjoined using the `:` (colon), or the unique short name. [source] ---- @@ -94,8 +100,19 @@ urn:unitsml:u:newton urn:unitsml:u:meter urn:unitsml:u:kilogram -// By identifier -urn:unitsml:u:nist:NISTu3 +// By UnitsML identifier +urn:unitsml:u:u:meter // meter unit +urn:unitsml:u:u:second // second unit +urn:unitsml:u:u:kilogram // kilogram unit + +// By NIST identifier +urn:unitsml:u:NISTu1 // meter unit +urn:unitsml:u:NISTu3 // second unit +urn:unitsml:u:NISTu2 // kilogram unit + +// By hierarchical identifier +urn:unitsml:u:unitsml:u:second // second unit +urn:unitsml:u:nist:NISTu3 // second unit ---- For prefixed units, the prefix is considered part of the unit name: @@ -123,8 +140,19 @@ urn:unitsml:d:length // By short name urn:unitsml:d:mass // mass dimension urn:unitsml:d:time // time dimension -// By identifier -urn:unitsml:d:nist:NISTd5 // temperature dimension +// By UnitsML identifier +urn:unitsml:d:d:length // length dimension +urn:unitsml:d:d:mass // mass dimension +urn:unitsml:d:d:temperature // temperature dimension + +// By NIST identifier +urn:unitsml:d:NISTd1 // length dimension +urn:unitsml:d:NISTd2 // mass dimension +urn:unitsml:d:NISTd5 // temperature dimension + +// By hierarchical identifier +urn:unitsml:d:unitsml:d:temperature // temperature dimension +urn:unitsml:d:nist:NISTd5 // temperature dimension ---- === Prefixes @@ -152,7 +180,19 @@ urn:unitsml:p:10:3 // Base 10, power 3 (kilo) urn:unitsml:p:mebi // By short name (mebi) urn:unitsml:p:2:20 // Base 2, power 20 (mebi) -urn:unitsml:p:nist:NISTp10_-1 // deci +// By UnitsML identifier +urn:unitsml:p:p:kilo // kilo +urn:unitsml:p:p:deci // deci +urn:unitsml:p:p:mebi // mebi + +// By NIST identifier +urn:unitsml:p:NISTp10_3 // kilo +urn:unitsml:p:NISTp10_-1 // deci +urn:unitsml:p:NISTp2_20 // mebi + +// By hierarchical identifier +urn:unitsml:p:unitsml:p:deci // deci +urn:unitsml:p:nist:NISTp10_-1 // deci ---- @@ -172,7 +212,19 @@ Examples: urn:unitsml:q:luminous_intensity // By short name urn:unitsml:q:length // length quantity -urn:unitsml:q:nist:NISTq12 // velocity quantity +// By UnitsML identifier +urn:unitsml:q:q:length // length quantity +urn:unitsml:q:q:velocity // velocity quantity +urn:unitsml:q:q:luminous_intensity // luminous intensity + +// By NIST identifier +urn:unitsml:q:NISTq1 // length quantity +urn:unitsml:q:NISTq12 // velocity quantity +urn:unitsml:q:NISTq7 // luminous intensity + +// By hierarchical identifier +urn:unitsml:q:unitsml:q:velocity // velocity quantity +urn:unitsml:q:nist:NISTq12 // velocity quantity ---- === Unit systems @@ -190,6 +242,14 @@ Examples: ---- urn:unitsml:s:si-base // SI base unit system urn:unitsml:s:si-derived-nonspecial + +// By UnitsML identifier +urn:unitsml:s:us:si-base // SI base unit system +urn:unitsml:s:us:si-derived-nonspecial + +// By NIST identifier +urn:unitsml:s:SI_base // SI base unit system +urn:unitsml:s:SI_derived_nonspecial // SI derived nonspecial unit system ---- @@ -210,20 +270,26 @@ urn:unitsml:k:length // Length quantity kind urn:unitsml:k:energy // Energy quantity kind ---- -=== Type of interval/unit scale +=== Unit scales -Types of interval represent how values in a scale are related. In the URN scheme, interval types are identified with the type code "i". +Unit scales represent how values in a measurement scale are related. In the URN scheme, unit scales are identified with the type code "i" (for interval). [source] ---- -urn:unitsml:i: +urn:unitsml:i: ---- +Unit scales are characterized by properties like whether they are continuous or discrete, ordered, logarithmic, and whether they support interval or ratio comparisons. + Examples: [source] ---- -urn:unitsml:i:log // Logarithmic interval -urn:unitsml:i:discreet // Discrete interval +urn:unitsml:i:continuous_ratio // Continuous ratio scale (e.g., length, mass) +urn:unitsml:i:continuous_interval // Continuous interval scale (e.g., Celsius temperature) +urn:unitsml:i:logarithmic_ratio // Logarithmic ratio scale (e.g., decibels) +urn:unitsml:i:logarithmic_field // Logarithmic field scale (e.g., nepers) +urn:unitsml:i:discrete // Discrete scale (e.g., counts) ---- +NOTE: Unit scales are referenced as individual elements and cannot be used in composite expressions. diff --git a/sources/unitsml-urn/sections/06-composite.adoc b/sources/unitsml-urn/sections/06-composite.adoc index 861177d..445c549 100644 --- a/sources/unitsml-urn/sections/06-composite.adoc +++ b/sources/unitsml-urn/sections/06-composite.adoc @@ -4,6 +4,14 @@ Composite expressions in UnitsML URNs allow for the representation of complex units, dimensions, and quantities. These expressions combine basic elements using mathematical operations to represent derived units or dimensions. +Composite expressions are only applicable to three element types: + +* Units (`u`): For derived units created through mathematical operations on other units +* Dimensions (`d`): For combined dimensions that describe a physical property +* Quantities (`q`): For physical quantities that combine multiple base quantities + +NOTE: Unit systems (`s`) and unit scales (`i`) are not used in composite expressions and can only be referenced as individual elements. + === Syntax for composite expressions A composite expression is indicated by a double colon after the element type: @@ -19,68 +27,118 @@ Within the composite expression, the following operators and symbols are used: |=== |Operator |Description |Example -|* |Multiplication |meter*second -|/ |Division |meter/second -|_e_ |Exponentiation |meter_e_2 -|sqrt() |Square root |sqrt(meter) -|() |Grouping |(newton*meter)/second +|`*` |Multiplication |`meter*second` +|`/` |Division |`meter/second` +|`_` |Exponentiation |`meter_2` +|`sqrt(...)` |Square root |`sqrt(meter)` +|`(...)` |Grouping |`(newton*meter)/second` + |=== === Operations ==== Multiplication -Multiplication is represented by the asterisk (*) symbol. It combines two or more elements by multiplication. +Multiplication is represented by the asterisk (`*`) symbol. It combines two or more elements by multiplication. [example] ==== [source] ---- +// Units urn:unitsml:u::meter*second // meter times second urn:unitsml:u::newton*meter // newton meter +urn:unitsml:u::pascal*cubic_meter // pascal cubic meter (energy) + +// Dimensions urn:unitsml:d::length*time // length times time +urn:unitsml:d::length*mass // length times mass +urn:unitsml:d::mass*length*time_-2 // force dimension + +// Quantities +urn:unitsml:q::mass*velocity // momentum +urn:unitsml:q::mass*velocity_2 // kinetic energy +urn:unitsml:q::force*length // work or energy ---- ==== ==== Division -Division is represented by the forward slash (/) symbol. It divides one element by another. +Division is represented by the forward slash (`/`) symbol. It divides one element by another. [example] ==== [source] ---- -urn:unitsml:u::meter/second // meter per second -urn:unitsml:d::length/time // length per time +// Units +urn:unitsml:u::meter/second // meter per second (velocity) +urn:unitsml:u::kilogram/cubic_meter // kilogram per cubic meter (density) +urn:unitsml:u::newton/square_meter // newton per square meter (pressure) urn:unitsml:u::(1/3) // fractional number + +// Dimensions +urn:unitsml:d::length/time // length per time (velocity dimension) +urn:unitsml:d::mass/length_3 // mass per volume (density dimension) +urn:unitsml:d::mass/(length*time) // mass flux dimension + +// Quantities +urn:unitsml:q::length/time // velocity +urn:unitsml:q::mass/volume // density +urn:unitsml:q::energy/time // power ---- ==== ==== Exponentiation -Exponentiation is represented by the `_e_` notation followed by the exponent value. +Exponentiation is represented by the underscore (`_`) notation followed by the exponent value. [example] ==== [source] ---- -urn:unitsml:u::meter_e_2 // square meter -urn:unitsml:u::second_e_-1 // per second -urn:unitsml:d::length_e_3 // volume dimension +// Units +urn:unitsml:u::meter_2 // square meter (area) +urn:unitsml:u::meter_3 // cubic meter (volume) +urn:unitsml:u::second_-1 // per second (frequency) +urn:unitsml:u::meter_-2 // per square meter + +// Dimensions +urn:unitsml:d::length_2 // area dimension +urn:unitsml:d::length_3 // volume dimension +urn:unitsml:d::time_-1 // frequency dimension +urn:unitsml:d::mass_-1 // specific property dimension + +// Quantities +urn:unitsml:q::length_2 // area +urn:unitsml:q::length_3 // volume +urn:unitsml:q::time_-1 // frequency +urn:unitsml:q::mass*length_-3 // density ---- ==== ==== Square root -Square root is represented either by the `sqrt()` function or by exponentiation with a fractional exponent. +Square root is represented either by the `sqrt(...)` function or by exponentiation with a fractional exponent. [example] ==== [source] ---- +// Units urn:unitsml:u::sqrt(meter) // square root of meter -urn:unitsml:u::meter_e_0.5 // alternative representation -urn:unitsml:u::meter_e_(1/2) // alternative with fraction +urn:unitsml:u::meter_0.5 // alternative representation +urn:unitsml:u::meter_(1/2) // alternative with fraction +urn:unitsml:u::sqrt(pascal*second) // square root of pascal second + +// Dimensions +urn:unitsml:d::sqrt(length) // square root of length dimension +urn:unitsml:d::length_0.5 // alternative representation +urn:unitsml:d::sqrt(mass*length) // square root of mass times length + +// Quantities +urn:unitsml:q::sqrt(energy) // amplitude +urn:unitsml:q::sqrt(power) // root-mean-square value +urn:unitsml:q::energy_0.5 // alternative representation ---- ==== @@ -92,61 +150,328 @@ Grouping is represented by parentheses and is used to control the order of opera ==== [source] ---- -urn:unitsml:u::(newton*meter)/second // newton meter per second +// Units +urn:unitsml:u::(newton*meter)/second // newton meter per second (power) urn:unitsml:u::newton*(meter/second) // newton times meter per second +urn:unitsml:u::(kilogram*meter_2)/second_2 // moment of inertia times angular acceleration + +// Dimensions +urn:unitsml:d::(length*mass)/time // momentum dimension +urn:unitsml:d::(mass*length_2)/time_2 // energy dimension +urn:unitsml:d::mass*(length/time_2) // force dimension + +// Quantities +urn:unitsml:q::(force*length)/time // power +urn:unitsml:q::(mass*velocity_2)/2 // kinetic energy +urn:unitsml:q::mass*(length/time_2) // force +---- +==== + +=== Complete examples + +Here are complete examples of composite expressions in URN form: + +[example] +==== +[source] +---- +// Basic units +urn:unitsml:u:meter # Base unit +urn:unitsml:u:millimeter # Prefixed unit + +// Composite units +urn:unitsml:u::meter/second # Meter per second (velocity) +urn:unitsml:u::meter*second_-1 # Alternative representation +urn:unitsml:u::newton*meter # Newton meter (torque, energy) +urn:unitsml:u::kilogram*meter_2 # Kilogram meter squared (moment of inertia) +urn:unitsml:u::watt*hour # Watt hour (energy) +urn:unitsml:u::meter_2/second_2 # Meter squared per second squared (specific energy) + +// Basic dimensions +urn:unitsml:d:length # Base dimension (L) +urn:unitsml:d:mass # Base dimension (M) +urn:unitsml:d:time # Base dimension (T) + +// Composite dimensions +urn:unitsml:d::length/time # Velocity dimension (L/T) +urn:unitsml:d::length*time_-2 # Acceleration dimension (L/T²) +urn:unitsml:d::mass*length*time_-2 # Force dimension (M·L/T²) +urn:unitsml:d::mass*length_-3 # Density dimension (M/L³) +urn:unitsml:d::mass*length_2*time_-2 # Energy dimension (M·L²/T²) +urn:unitsml:d::length_2*time_-3 # Power per area dimension (L²/T³) + +// Basic quantities +urn:unitsml:q:mass # Base quantity +urn:unitsml:q:length # Base quantity +urn:unitsml:q:time # Base quantity + +// Composite quantities +urn:unitsml:q::mass*acceleration # Force +urn:unitsml:q::length/time # Velocity +urn:unitsml:q::length/time_2 # Acceleration +urn:unitsml:q::force*length # Energy, work +urn:unitsml:q::mass*velocity_2 # Kinetic energy +urn:unitsml:q::mass/volume # Density +urn:unitsml:q::energy/time # Power +urn:unitsml:q::mass*length_2 # Moment of inertia +urn:unitsml:q::sqrt(energy/mass) # Velocity from energy ---- ==== +=== Conversion between AsciiUnits and UnitsML URN + +==== General + +AsciiUnits and UnitsML URN provide two different syntaxes for representing units, dimensions, and quantities. Converting between these two formats enables interoperability between systems that use either notation. + +==== Mapping of operators and syntax + +The following table maps the operators and syntax elements between AsciiUnits and UnitsML URN: + +[cols="2,2,3"] +|=== +|Operation |AsciiUnits |UnitsML URN + +|Basic reference (unit) |`m` |`urn:unitsml:u:meter` +|Basic reference (dimension) |`L` |`urn:unitsml:d:length` +|Basic reference (quantity) |`l` |`urn:unitsml:q:length` +|Multiplication |`m*s` |`urn:unitsml:u::meter*second` +|Division |`m/s` or `m//s` |`urn:unitsml:u::meter/second` +|Exponentiation |`m^2` |`urn:unitsml:u::meter_2` +|Negative exponent |`s^-1` or `s^(-1)` |`urn:unitsml:u::second_-1` +|Square root |`sqrt(m)` |`urn:unitsml:u::sqrt(meter)` +|Grouping |`(m*s)/kg` |`urn:unitsml:u::(meter*second)/kilogram` +|=== + +==== AsciiUnits to UnitsML URN conversion + +To convert an AsciiUnits expression to a UnitsML URN: + +. Identify the element type (unit, dimension, prefix, quantity) +** Units are represented with `u` +** Dimensions are represented with `d` +** Prefixes are represented with `p` +** Quantities are represented with `q` + +. For simple elements, use the format: `urn:unitsml::` +** Example: `m` → `urn:unitsml:u:meter` +** Example: `kg` → `urn:unitsml:u:kilogram` + +. For composite expressions, use the format: `urn:unitsml:::` +** Replace `^` with `_` for exponents +** Use full names instead of symbols (e.g., `meter` instead of `m`) +** Retain operators (`*`, `/`) and grouping (`()`) + +[example] +==== +Converting from AsciiUnits to UnitsML URN: + +[cols="2,3"] +|=== +|AsciiUnits |UnitsML URN + +|// Units +| +|`m^2` |`urn:unitsml:u::meter_2` +|`kg*m/s^2` |`urn:unitsml:u::kilogram*meter*second_-2` +|`J/(kg*K)` |`urn:unitsml:u::joule/(kilogram*kelvin)` +|`sqrt(Hz)` |`urn:unitsml:u::sqrt(hertz)` +|`(N*m)^2/kg` |`urn:unitsml:u::(newton*meter)_2/kilogram` +| +|// Dimensions +| +|`L^2` |`urn:unitsml:d::length_2` +|`L*M/T^2` |`urn:unitsml:d::length*mass*time_-2` +|`L^2*M/T^2` |`urn:unitsml:d::length_2*mass*time_-2` +| +|// Quantities +| +|`length^2` |`urn:unitsml:q::length_2` +|`mass*acceleration` |`urn:unitsml:q::mass*acceleration` +|`energy/time` |`urn:unitsml:q::energy/time` +|=== +==== + +==== UnitsML URN to AsciiUnits conversion + +To convert a UnitsML URN to AsciiUnits: + +. Remove the URN prefix (`urn:unitsml::` or `urn:unitsml:::`) + +. Replace full names with symbols +** Example: `meter` → `m` +** Example: `second` → `s` +** Example: `kilogram` → `kg` + +. Replace `_` with `^` for exponents + +. Retain operators (`*`, `/`) and grouping (`()`) + +[example] +==== +Converting from UnitsML URN to AsciiUnits: + +[cols="3,2"] +|=== +|UnitsML URN |AsciiUnits + +|// Units +| +|`urn:unitsml:u::meter_2` |`m^2` +|`urn:unitsml:u::kilogram*meter*second_-2` |`kg*m*s^-2` +|`urn:unitsml:u::joule/(kilogram*kelvin)` |`J/(kg*K)` +|`urn:unitsml:u::sqrt(hertz)` |`sqrt(Hz)` +|`urn:unitsml:u::(newton*meter)_2/kilogram` |`(N*m)^2/kg` +|`urn:unitsml:u::(newton*meter)/second` |`(N*m)/s` +| +|// Dimensions +| +|`urn:unitsml:d::length_2` |`L^2` +|`urn:unitsml:d::length*mass*time_-2` |`L*M*T^-2` +|`urn:unitsml:d::length_2*time_-3` |`L^2*T^-3` +| +|// Quantities +| +|`urn:unitsml:q::length/time` |`velocity` +|`urn:unitsml:q::mass*length_-3` |`density` +|`urn:unitsml:q::force*distance` |`energy` +|=== +==== + +==== Conversion considerations + +The following considerations should be taken into account when converting +between AsciiUnits and the UnitsML URN composite expression format: + +. Symbol name variants: AsciiUnits supports multiple identifiers per symbol. The +primary name should be used in UnitsML URN. + +. Normalization: Normalize the composite expression after conversion to ensure +consistent representation. See the +<<_composite_expression_normalization,normalization>> section for more details. + +. Prefixes: Both AsciiUnits and the URN composite expression handle prefixes +implicitly (e.g., `km` is parsed as kilometer, and `kilometer` in UnitsML URN is +considered equivalent), therefore the parsing and conversion should be done in a +way that the prefix is understood and retained. + + === Conversion from NIST Legacy IDs -The new URN scheme provides a way to represent the same composite expressions that were previously represented using the NIST legacy ID notation. +The UnitsML URN scheme provides a way to represent the same composite expressions +that were previously represented using the NIST legacy ID notation. + +To convert from NIST legacy IDs to the native UnitsML URN format, follow these steps: + +. *Parse the legacy ID*: NIST legacy IDs follow patterns like `NISTu1`, `NISTd1`, or composite forms like `NISTu9.u3e-2/1` for composite units. + +. *Identify the entity type*: The prefix indicates the entity type: `u` for units, `d` for dimensions, `p` for prefixes, `q` for quantities, etc. + +. *For simple entities*: + .. Obtain the entity's short name from the corresponding YAML file (e.g., "meter" for NISTu1, "length" for NISTd1) + .. Construct the URN as `urn:unitsml::` + .. Example: `NISTu1` → `urn:unitsml:u:meter` + +. *For composite expressions*: + .. Decompose the legacy ID into its components + .. For each component, identify: + * The base entity (e.g., `NISTu9` → `radian`) + * Any exponents (e.g., `e-2/1` → power of -2) + * Prefix information if present (e.g., `p10'3` → kilo) + .. Translate each component into the appropriate segment of the URN expression + .. Connect components using operators (`*`, `/`) based on the relationships in the legacy ID + .. Construct the URN as `urn:unitsml:::` + +. *Handle special cases*: + .. Some legacy composite IDs might reference a dimension directly (e.g., `NISTd11`) + .. For these, identify the corresponding dimension composition (e.g., `length*time_-2` for NISTd11) + .. Construct the URN accordingly + +==== Parsing the Legacy ID Syntax + +The legacy ID syntax for composite expressions follows a pattern: + +* `.....` where each component has the form: + ** `[p']e/` + ** Example: `u3e-2/1` represents "second to power -2" + ** Example: `u27p10'3e-2/1` represents "kilogram to power -2" [example] ==== +This composite unit represents "radian per second squared". + Legacy ID: `NISTu9.u3e-2/1` -URN representation: `urn:unitsml:u::radian*second_e_-2` or `urn:unitsml:u::radian/second_e_2` +Parsing steps: +1. Base ID: NISTu9 → radian +2. Component: u3e-2/1 + * Entity: u3 → second + * Power: -2/1 → -2 -This represents "radian per second squared". +URN representation: +* `urn:unitsml:u::radian*second_-2` +* `urn:unitsml:u::radian/second_2` ==== [example] ==== +This composite unit represents "newton meter squared per kilogram squared". + Legacy ID: `NISTu11.u1e2/1.u27p10'3e-2/1` -URN representation: `urn:unitsml:u::newton*meter_e_2*kilogram_e_-2` or `urn:unitsml:u::(newton*meter_e_2)/(kilogram_e_2)` +Parsing steps: +1. Base ID: NISTu11 → newton +2. First component: u1e2/1 + * Entity: u1 → meter + * Power: 2/1 → 2 +3. Second component: u27p10'3e-2/1 + * Entity: u27 → gram + * Prefix: p10'3 → kilo + * Power: -2/1 → -2 + * Combined: kilogram^-2 + +URN representation: +* `urn:unitsml:u::newton*meter_2*kilogram_-2` +* `urn:unitsml:u::(newton*meter_2)/(kilogram_2)` +==== -This represents "newton meter squared per kilogram squared". +[example] ==== +This composite dimension represents "acceleration dimension". -=== Complete examples +Legacy ID: `NISTd11` -Here are complete examples of composite expressions in URN form: +Parsing steps: +1. Direct reference to NISTd11 which is "length/time²" dimension +2. Consulting the dimensions.yaml file, we find NISTd11 corresponds to: + * length (power: 1) + * time (power: -2) + +URN representation: +* `urn:unitsml:d::length*time_-2` +==== [example] ==== -[source] ----- -// Basic units -urn:unitsml:u:meter # Base unit -urn:unitsml:u:millimeter # Prefixed unit +This composite unit represents "kilogram meter per second" (momentum unit). -// Composite units -urn:unitsml:u::meter/second # Meter per second -urn:unitsml:u::meter*second_e_-1 # Alternative representation +Legacy ID: `NISTu27p10'3.u1.u3e-1/1` -// Dimensions -urn:unitsml:d:length # Base dimension -urn:unitsml:d::length/time # Composite dimension +Parsing steps: +1. First component: NISTu27p10'3 → kilogram +2. Second component: u1 → meter +3. Third component: u3e-1/1 → second^-1 -// Quantities -urn:unitsml:q:mass # Base quantity -urn:unitsml:q::mass*acceleration # Composite quantity +URN representation: +* `urn:unitsml:u::kilogram*meter*second_-1` +* `urn:unitsml:u::kilogram*meter/second` +==== -// Complex expressions -urn:unitsml:u::radian*second_e_-2 # Radian per second squared -urn:unitsml:u::(newton*meter_e_2)/(kilogram_e_2) # Newton meter squared per kilogram squared -urn:unitsml:u::sqrt(meter) # Square root of meter -urn:unitsml:d::length*time_e_-2 # Acceleration dimension ----- +[example] +==== +This composite quantity represents "force". + +URN representation: +* `urn:unitsml:q::mass*acceleration` +* `urn:unitsml:q::mass*length*time_-2` ==== diff --git a/sources/unitsml-urn/sections/07-composite-normalize.adoc b/sources/unitsml-urn/sections/07-composite-normalize.adoc index 95a7d2c..0e1ecdd 100644 --- a/sources/unitsml-urn/sections/07-composite-normalize.adoc +++ b/sources/unitsml-urn/sections/07-composite-normalize.adoc @@ -2,19 +2,35 @@ === General -To ensure consistent interpretation and comparison of composite expressions, a normalization algorithm is defined. This algorithm converts any valid composite expression into a canonical form that can be used for equivalence checking and other operations. +Composite expressions can be complex and may be represented in various ways. +This can lead to ambiguity and inconsistency in interpretation. + +To address this, a normalization process is defined to convert composite +expressions into a canonical form. + +NOTE: Normalization applies to composite expressions for units (`u`), dimensions (`d`), +and quantities (`q`). Unit systems (`s`) and unit scales (`i`) cannot be used in +composite expressions and therefore do not undergo normalization. === Normalization rules The normalization process applies the following rules: -. *Ordering*: Elements should be ordered alphabetically within each term. -. *Simplification*: Common terms in numerator and denominator should be canceled. -. *Exponent consolidation*: Multiple occurrences of the same element should be consolidated with their exponents added. -. *Grouping*: Parentheses should only be used when necessary for precedence. -. *Names*: Short names should be used consistently within expressions. +. *Ordering*: Elements are ordered within each term. Units are ordered by their +dimension type (length, time, mass, etc.) and then alphabetically by their name. + +. *Simplification*: Common terms in numerator and denominator are canceled. + +. *Exponent consolidation*: Multiple occurrences of the same element are +consolidated with their exponents added. + +. *Grouping*: Parentheses are only used when necessary for precedence. + +. *Names*: Short names are used consistently within expressions. + . *Form*: Negative exponents are preferred over division for canonical representation. + === Normalization algorithm The normalization algorithm consists of the following steps: @@ -22,22 +38,26 @@ The normalization algorithm consists of the following steps: . *Parsing*: Parse the composite expression into a structured representation. . *Term extraction*: Identify all terms and their associated exponents. - a. For multiplication expressions, extract each term with its positive exponent. - b. For division expressions, extract the denominator terms with negative exponents. - c. For exponentiation, apply the exponent to the base term. - d. For square root, convert to exponentiation with exponent 0.5. + +.. For multiplication expressions, extract each term with its positive exponent. +.. For division expressions, extract the denominator terms with negative exponents. +.. For exponentiation, apply the exponent to the base term. +.. For square root, convert to exponentiation with exponent 0.5. . *Term combination*: Combine like terms by adding their exponents. - a. Group terms with the same base element. - b. Add the exponents for each group. - c. Remove terms with zero exponent. -. *Term sorting*: Sort the terms alphabetically by base element name. +.. Group terms with the same base element. +.. Add the exponents for each group. +.. Remove terms with zero exponent. + +. *Term sorting*: Sort the terms alphabetically by their dimension type and then +by base element name. . *Expression reconstruction*: - a. Use multiplication to combine terms with non-zero exponents. - b. Express terms with negative exponents using the `_e_` notation rather than division. - c. Only use parentheses when grouping affects the result. + +.. Use multiplication to combine terms with non-zero exponents. +.. Express terms with negative exponents using the `_` notation rather than division. +.. Only use parentheses when grouping affects the result. === Step-by-step examples @@ -51,36 +71,38 @@ Here are step-by-step examples of the normalization process: Terms: `meter`, `second`, `meter` *Step 2*: Extract terms and exponents. -Terms with exponents: `meter^1`, `second^1`, `meter^1` +Terms with exponents: `meter_1`, `second_1`, `meter_1` *Step 3*: Combine like terms. -Grouped terms: `meter^2`, `second^1` +Grouped terms: `meter_2`, `second_1` -*Step 4*: Sort terms alphabetically. -Sorted terms: `meter^2`, `second^1` +*Step 4*: Sort terms alphabetically by their dimension type and then by base element name. +Sorted terms: `meter_2`, `second_1` *Step 5*: Reconstruct the expression. -Normalized expression: `meter_e_2*second` + +Normalized expression: `meter_2*second` ==== [example] ==== -*Original expression*: `(newton*meter_e_2)/(kilogram_e_2)` +*Original expression*: `(newton*meter_2)/(kilogram_2)` *Step 1*: Parse the expression. -Terms: `newton`, `meter_e_2` in numerator, `kilogram_e_2` in denominator +Terms: `newton`, `meter_2` in numerator, `kilogram_2` in denominator *Step 2*: Extract terms and exponents. -Terms with exponents: `newton^1`, `meter^2`, `kilogram^-2` +Terms with exponents: `newton_1`, `meter_2`, `kilogram_-2` *Step 3*: Combine like terms. -Grouped terms: `newton^1`, `meter^2`, `kilogram^-2` +Grouped terms: `newton_1`, `meter_2`, `kilogram_-2` -*Step 4*: Sort terms alphabetically. -Sorted terms: `kilogram^-2`, `meter^2`, `newton^1` +*Step 4*: Sort terms alphabetically by their dimension type and then by base element name. +Sorted terms: `kilogram_-2`, `meter_2`, `newton_1` *Step 5*: Reconstruct the expression. -Normalized expression: `kilogram_e_-2*meter_e_2*newton` + +Normalized expression: `kilogram_-2*meter_2*newton` ==== [example] @@ -91,29 +113,36 @@ Normalized expression: `kilogram_e_-2*meter_e_2*newton` Terms: `meter` in numerator, `second`, `second` in denominators *Step 2*: Extract terms and exponents. -Terms with exponents: `meter^1`, `second^-1`, `second^-1` +Terms with exponents: `meter_1`, `second_-1`, `second_-1` *Step 3*: Combine like terms. -Grouped terms: `meter^1`, `second^-2` +Grouped terms: `meter_1`, `second_-2` -*Step 4*: Sort terms alphabetically. -Sorted terms: `meter^1`, `second^-2` +*Step 4*: Sort terms alphabetically by their dimension type and then by base element name. +Sorted terms: `meter_1`, `second_-2` *Step 5*: Reconstruct the expression. -Normalized expression: `meter*second_e_-2` + +Normalized expression: `meter*second_-2` ==== === Comparison of expressions -Two composite expressions are considered equivalent if they normalize to the same canonical form. This allows for comparison of expressions that may be written differently but represent the same underlying quantity. +Two composite expressions are considered equivalent if they normalize to the +same canonical form. + +This allows for comparison of expressions that may be written differently but +represent the same underlying quantity. [example] ==== Expression 1: `meter/second` -Normalized: `meter*second_e_-1` -Expression 2: `meter*second_e_-1` -Normalized: `meter*second_e_-1` +Normalized: `meter*second_-1` + +Expression 2: `meter*second_-1` + +Normalized: `meter*second_-1` Result: These expressions are equivalent. ==== @@ -121,9 +150,11 @@ Result: These expressions are equivalent. [example] ==== Expression 1: `newton*meter` + Normalized: `meter*newton` Expression 2: `meter*newton` + Normalized: `meter*newton` Result: These expressions are equivalent. diff --git a/sources/unitsml-urn/sections/08-urn.adoc b/sources/unitsml-urn/sections/08-urn.adoc index b14ee72..4f8ed68 100644 --- a/sources/unitsml-urn/sections/08-urn.adoc +++ b/sources/unitsml-urn/sections/08-urn.adoc @@ -1,8 +1,14 @@ == URN Specification for "unitsml" NID +=== General + +This clause specifies the syntax for the UnitsML URN namespace. + === NID Definitions +The NID for the UnitsML URN namespace is defined as follows: + [source] ---- NID = "unitsml" @@ -10,31 +16,57 @@ NID = "unitsml" === Syntax for the NSS (Namespace Specific String) -The general syntax for the unitsml NSS follows this pattern: +The general syntax for the `unitsml` NSS follows this pattern: [source] ---- NSS = element-reference / composite-expression element-reference = element-type ":" element-id -composite-expression = element-type "::" expression +composite-expression = composite-element-type "::" expression element-type = "u" / "d" / "p" / "q" / "s" / "k" / "i" -element-id = number / name / hierarchical-id / prefix-with-power +composite-element-type = "u" / "d" / "q" +element-id = number / name / native-id / hierarchical-id / prefix-with-power expression = term *( operator term ) ---- -==== Element type definitions +The element reference syntax is used to identify a specific element in the +UnitsML namespace. + +==== Element Reference Types + +Different forms of element references are supported: + +* *Simple name reference*: References an element by its unique short name + ** Example: `urn:unitsml:u:meter` for the meter unit + ** Example: `urn:unitsml:d:length` for the length dimension + +* *Native ID reference*: References an element by its native ID from the UnitsDB database + ** Example: `urn:unitsml:u:u:meter` for the meter unit + ** Example: `urn:unitsml:d:d:length` for the length dimension + ** Example: `urn:unitsml:u:NISTu1` for the meter unit (NIST identifier) + ** Example: `urn:unitsml:d:NISTd1` for the length dimension (NIST identifier) + +* *Hierarchical ID reference*: References an element by a system-specific identifier + ** Example: `urn:unitsml:u:unitsml:u:meter` for the meter unit + ** Example: `urn:unitsml:d:unitsml:d:length` for the length dimension + ** Example: `urn:unitsml:u:nist:NISTu1` for the meter unit (NIST identifier) + ** Example: `urn:unitsml:d:nist:NISTd1` for the length dimension (NIST identifier) [source] ---- number = 1*DIGIT name = 1*( ALPHA / DIGIT / "_" / "-" ) +native-id = ("u:" / "d:" / "p:" / "q:" / "us:") name / "NIST" element-type 1*DIGIT ["." *native-element-part] +native-element-part = element-type [prefix-part] ["e" ["-"] number "/" number] +prefix-part = "p" number "'" number hierarchical-id = name *( ":" name ) prefix-with-power = base ":" power base = number power = ["-"] number ---- -==== Expression syntax +The composite expression syntax is used to represent complex units, dimensions, +and quantities. [source] ---- @@ -43,10 +75,9 @@ simple-term = name [exponent] grouped-term = "(" expression ")" [exponent] function-term = function-name "(" expression ")" function-name = "sqrt" -exponent = "_e_" exponent-value +exponent = "_" exponent-value exponent-value = number / fraction / grouped-exponent fraction = "(" number "/" number ")" grouped-exponent = "(" ["-"] number ["." number] ")" operator = "*" / "/" ---- - diff --git a/sources/unitsml-urn/sections/09-namespace-considerations.adoc b/sources/unitsml-urn/sections/09-namespace-considerations.adoc index 4fd28e5..8b86f9e 100644 --- a/sources/unitsml-urn/sections/09-namespace-considerations.adoc +++ b/sources/unitsml-urn/sections/09-namespace-considerations.adoc @@ -2,36 +2,50 @@ === Assignment -The following provides background information on the process that led to the need for a UnitsML URN namespace and motivation for key aspects of the naming structure. +The following provides background information on the process that led to the +need for a UnitsML URN namespace and motivation for key aspects of the naming +structure. -The UnitsML Technical Committee has developed a comprehensive framework for representing units of measure in machine-readable formats. As this framework has evolved, the need for persistent, unique identifiers for UnitsML elements has become apparent. +The CalConnect UnitsML Technical Committee has developed a comprehensive +framework for representing units of measure in machine-readable formats. As this +framework has evolved, the need for persistent, unique identifiers for UnitsML +elements has become apparent. -The UnitsML URN namespace was developed to address this need, providing a way to uniquely identify and reference UnitsML elements across different systems and implementations. The namespace is designed to be compatible with existing UnitsML identifiers while providing a standardized approach to identification. +The UnitsML URN namespace was developed to address this need, providing a way to +uniquely identify and reference UnitsML elements across different systems and +implementations. The namespace is designed to be compatible with existing +UnitsML identifiers while providing a standardized approach to identification. === ID uniqueness -The unitsml URN namespace ensures uniqueness of identifiers through several mechanisms: +The `unitsml` URN namespace ensures uniqueness of identifiers through several +mechanisms: -1. *Element type separation*: Each element type has its own namespace, allowing the same identifier to be used in different element types without conflict. -2. *Dual identification system*: Elements can be identified by either numerical ID or short name, with a one-to-one mapping between these identifiers. -3. *Hierarchical namespaces*: For elements such as unit systems, hierarchical identifiers are used to avoid conflicts. -4. *Centralized registration*: The UnitsML Technical Committee maintains a central registry of identifiers to prevent duplicates. +Element type separation::: Each element type has its own namespace, allowing the +same identifier to be used in different element types without conflict. + +Dual identification system::: Elements can be identified by either identifier or +short name, with a one-to-one mapping between these identifiers. + +Hierarchical namespaces::: For elements such as unit systems, hierarchical identifiers are used to avoid conflicts. + +Centralized registration::: The UnitsML Technical Committee maintains a central registry of identifiers to prevent duplicates. === Identifier assignment Identifiers within the unitsml namespace are assigned according to the following principles: -1. *Numerical IDs*: Numerical IDs are assigned sequentially as new elements are added to the UnitsML database. -2. *Short names*: Short names are derived from the common name of the element, converted to lowercase, with spaces replaced by underscores. -3. *Hierarchical IDs*: Hierarchical IDs follow a logical organization, with broader categories preceding more specific ones. -4. *Prefix powers*: For prefixes, the base and power are included in the identifier to facilitate automated processing. +Numerical IDs::: Numerical IDs are assigned sequentially as new elements are added to the UnitsML database. +Short names::: Short names are derived from the common name of the element, converted to lowercase, with spaces replaced by underscores. +Hierarchical IDs::: Hierarchical IDs follow a logical organization, with broader categories preceding more specific ones. +Prefix powers::: For prefixes, the base and power are included in the identifier to facilitate automated processing. === URN resolution -Resolution of unitsml URNs to resources is not part of this specification. However, implementations may provide resolution mechanisms to retrieve information about the identified element, such as: +Resolution of `unitsml` URNs to resources is not part of this specification. However, implementations may provide resolution mechanisms to retrieve information about the identified element, such as: -1. *Web services*: HTTP-based services that return information about the identified element. -2. *Databases*: Local or remote databases that can be queried using the URN. -3. *Registries*: Central registries maintained by standards bodies or organizations. +Web services::: HTTP-based services that return information about the identified element. +Databases::: Local or remote databases that can be queried using the URN. +Registries::: Central registries maintained by standards bodies or organizations. -The primary purpose of unitsml URNs is to provide stable, unique identifiers for reference, not necessarily to directly access resources. +The primary purpose of `unitsml` URNs is to provide stable, unique identifiers for reference, not necessarily to directly access resources. diff --git a/sources/unitsml-urn/sections/10-community-considerations.adoc b/sources/unitsml-urn/sections/10-community-considerations.adoc index d5bfc18..bab2181 100644 --- a/sources/unitsml-urn/sections/10-community-considerations.adoc +++ b/sources/unitsml-urn/sections/10-community-considerations.adoc @@ -4,44 +4,47 @@ The UnitsML URN namespace serves the needs of several communities: -1. *Scientific and engineering communities*: Researchers, engineers, and scientists who need to exchange measurement data. -2. *Data management organizations*: Groups responsible for managing and exchanging scientific and technical data. -3. *Standards bodies*: Organizations developing standards for measurement and data exchange. -4. *Software developers*: Developers implementing systems that handle measurement data. +. Scientific and engineering communities: Researchers, engineers, and scientists who need to exchange measurement data. +. Data management organizations: Groups responsible for managing and exchanging scientific and technical data. +. Standards bodies: Organizations developing standards for measurement and data exchange. +. Software developers: Developers implementing systems that handle measurement data. === Benefits -The benefits of the unitsml URN namespace for these communities include: +The benefits of the `unitsml` URN namespace for these communities include: -1. *Unambiguous identification*: Clear, unique identification of measurement units and related concepts. -2. *Interoperability*: Common identification system that works across different platforms and implementations. -3. *Persistence*: Stable references that remain valid over time, independent of physical location. -4. *Machine processability*: Identifiers that can be parsed and processed by software. +. Unambiguous identification: Clear, unique identification of measurement units and related concepts. +. Interoperability: Common identification system that works across different platforms and implementations. +. Persistence: Stable references that remain valid over time, independent of physical location. +. Machine processability: Identifiers that can be parsed and processed by software. === Registration and authority -The UnitsML Technical Committee serves as the authority for the unitsml URN namespace. The committee will: +The CalConnect UnitsML Technical Committee serves as the authority for the +`unitsml` URN namespace. -1. *Maintain a registry*: Keep a central registry of all assigned identifiers. -2. *Review new additions*: Review and approve new elements to be added to the namespace. -3. *Ensure consistency*: Ensure that new identifiers follow the established patterns and conventions. -4. *Provide documentation*: Maintain documentation on the namespace and its elements. +The committee will: + +. Maintain a registry: Keep a central registry of all assigned identifiers. +. Review new additions: Review and approve new elements to be added to the namespace. +. Ensure consistency: Ensure that new identifiers follow the established patterns and conventions. +. Provide documentation: Maintain documentation on the namespace and its elements. === Process for identifier updates The process for updating and adding identifiers to the unitsml namespace includes: -1. *Proposal*: Submission of a proposal for a new element or identifier. -2. *Review*: Review by the UnitsML Technical Committee for consistency and necessity. -3. *Approval*: Formal approval and assignment of identifiers. -4. *Publication*: Publication of the new identifier in the central registry. -5. *Notification*: Notification to the community of the addition. +. Proposal: Submission of a proposal for a new element or identifier. +. Review: Review by the UnitsML Technical Committee for consistency and necessity. +. Approval: Formal approval and assignment of identifiers. +. Publication: Publication of the new identifier in the central registry. +. Notification: Notification to the community of the addition. === Responsibility for the namespace -The UnitsML Technical Committee takes responsibility for the unitsml namespace, including: +The CalConnect UnitsML Technical Committee takes responsibility for the unitsml namespace, including: -1. *Ensuring stability*: Maintaining the stability and persistence of identifiers. -2. *Preventing conflicts*: Preventing naming conflicts and duplicate identifiers. -3. *Documentation*: Providing clear documentation on the namespace and its usage. -4. *Accessibility*: Ensuring that information about identifiers is accessible to the community. \ No newline at end of file +. Ensuring stability: Maintaining the stability and persistence of identifiers. +. Preventing conflicts: Preventing naming conflicts and duplicate identifiers. +. Documentation: Providing clear documentation on the namespace and its usage. +. Accessibility: Ensuring that information about identifiers is accessible to the community. \ No newline at end of file diff --git a/sources/unitsml-urn/sections/11-security-considerations.adoc b/sources/unitsml-urn/sections/11-security-considerations.adoc index af3ca24..611f124 100644 --- a/sources/unitsml-urn/sections/11-security-considerations.adoc +++ b/sources/unitsml-urn/sections/11-security-considerations.adoc @@ -1,12 +1,25 @@ == Security considerations -The unitsml URN namespace does not introduce any security issues beyond those associated with the use of URNs in general. However, implementers should be aware of the following considerations: +The `unitsml` URN namespace does not introduce any security issues beyond those +associated with the use of URNs in general. -1. *Input validation*: When processing unitsml URNs, implementations should validate the input to prevent injection attacks. -2. *Reference integrity*: Systems using unitsml URNs should verify the existence and validity of referenced elements before processing. -3. *Authority*: Implementers should verify that unitsml URNs come from authoritative sources, especially when using them for critical calculations. -4. *Resource consumption*: Processing complex composite expressions may consume significant resources and should be monitored for potential denial-of-service issues. +Implementers should be aware of the following considerations: -These considerations are not unique to the unitsml namespace but are standard practice for systems dealing with external identifiers and references. +. Input validation: When processing `unitsml` URNs, implementations should +validate the input to prevent injection attacks. -There are no additional security concerns related to the unitsml namespace itself. \ No newline at end of file +. Reference integrity: Systems using `unitsml` URNs should verify the existence +and validity of referenced elements before processing. + +. Authority: Implementers should verify that `unitsml` URNs come from +authoritative sources, especially when using them for critical calculations. + +. Resource consumption: Processing complex composite expressions may consume +significant resources and should be monitored for potential denial-of-service +issues. + +These considerations are not unique to the `unitsml` namespace but are standard +practice for systems dealing with external identifiers and references. + +There are no additional security concerns related to the `unitsml` namespace +itself. \ No newline at end of file diff --git a/sources/unitsml-urn/sections/12-iana.adoc b/sources/unitsml-urn/sections/12-iana.adoc index 1adbbe0..eb4082f 100644 --- a/sources/unitsml-urn/sections/12-iana.adoc +++ b/sources/unitsml-urn/sections/12-iana.adoc @@ -1,7 +1,9 @@ == IANA considerations -This section provides information required for the registration of the unitsml URN namespace with the Internet Assigned Numbers Authority (IANA), as required by RFC 8141. +This section provides information required for the registration of the unitsml +URN namespace with the Internet Assigned Numbers Authority (IANA), as required +by <>. Namespace ID:: unitsml @@ -15,7 +17,7 @@ Contact information::: (Appropriate contact details to be added) Declared registrant of the namespace:: UnitsML Technical Committee -Declaration of syntactic structure:: The syntax of unitsml URNs follows the pattern: +Declaration of syntactic structure:: The syntax of `unitsml` URNs follows the pattern: + [source] ---- @@ -27,22 +29,38 @@ or urn:unitsml::: ---- + -Where `` is one of "u", "d", "p", "q", "s", "k", or "i", and `` and `` follow the rules specified in this document. +Where `` is one of "u", "d", "p", "q", "s", "k", or "i", and +`` and `` follow the rules specified +in this document. -Relevant ancillary documentation:: This document serves as the primary specification for the unitsml URN namespace. Additional documentation may be provided by the UnitsML Technical Committee. +Relevant ancillary documentation:: This document serves as the primary +specification for the `unitsml` URN namespace. Additional documentation may be +provided by the UnitsML Technical Committee. -Identifier uniqueness considerations:: Uniqueness is ensured through the use of element type namespaces, central registration, and the processes described in this document. +Identifier uniqueness considerations:: Uniqueness is ensured through the use of +element type namespaces, central registration, and the processes described in +this document. -Identifier persistence considerations:: The UnitsML Technical Committee guarantees the persistence of unitsml URNs through active management of the namespace and adherence to the principles outlined in this document. +Identifier persistence considerations:: The UnitsML Technical Committee +guarantees the persistence of `unitsml` URNs through active management of the +namespace and adherence to the principles outlined in this document. -Process of identifier assignment:: Identifiers are assigned by the UnitsML Technical Committee following the processes described in this document. +Process of identifier assignment:: Identifiers are assigned by the UnitsML +Technical Committee following the processes described in this document. -Process for identifier resolution:: This namespace does not require resolution services. +Process for identifier resolution:: This namespace does not require resolution +services. -Rules for lexical equivalence:: Two unitsml URNs are considered lexically equivalent if they match exactly after normalization of composite expressions as described in this document. +Rules for lexical equivalence:: Two `unitsml` URNs are considered lexically +equivalent if they match exactly after normalization of composite expressions as +described in this document. -Conformance with URN syntax:: All unitsml URNs conform to the syntax requirements of RFC 8141. +Conformance with URN syntax:: All `unitsml` URNs conform to the syntax +requirements of RFC 8141. -Validation mechanism:: Validation can be performed by checking against the formal grammar provided in this document and by verifying the existence of the referenced element in the UnitsML database. +Validation mechanism:: Validation can be performed by checking against the +formal grammar provided in this document and by verifying the existence of the +referenced element in the UnitsML database. -Scope:: The unitsml URN namespace is global in scope, intended for use in all contexts where UnitsML elements need to be identified. +Scope:: The `unitsml` URN namespace is global in scope, intended for use in all +contexts where UnitsML elements need to be identified. diff --git a/sources/unitsml-urn/sections/99-bibliography.adoc b/sources/unitsml-urn/sections/99-bibliography.adoc index f494396..d99f83b 100644 --- a/sources/unitsml-urn/sections/99-bibliography.adoc +++ b/sources/unitsml-urn/sections/99-bibliography.adoc @@ -1,2 +1,5 @@ [bibliography] == Bibliography + +* [[[RFC_8141,IETF RFC 8141]]], _Uniform Resource Names (URNs)_ +* [[[RFC_5234,IETF RFC 5234]]], _Augmented BNF for Syntax Specifications: ABNF_ diff --git a/sources/unitsml-urn/sections/a1-ebnf.adoc b/sources/unitsml-urn/sections/a1-ebnf.adoc index 1a1f9b5..5d11bbb 100644 --- a/sources/unitsml-urn/sections/a1-ebnf.adoc +++ b/sources/unitsml-urn/sections/a1-ebnf.adoc @@ -2,7 +2,8 @@ [appendix,obligation=informative] == ABNF Definition of Namespace ID = "unitsml" -This appendix provides the formal ABNF (Augmented Backus-Naur Form) definition for the syntax of UnitsML URNs, according to RFC 5234. +This appendix provides the formal ABNF (Augmented Backus-Naur Form) definition +for the syntax of UnitsML URNs, according to <>. [source] ---- @@ -16,13 +17,16 @@ element-reference = simple-reference / composite-reference simple-reference = element-type ":" element-id ; Composite expression -composite-reference = element-type "::" expression +composite-reference = composite-element-type "::" expression -; Element types +; Element types (all types for simple references) element-type = "u" / "d" / "p" / "q" / "s" / "k" / "i" -; Element identifiers can be numeric, named, hierarchical, or prefix specifications -element-id = number / name / hierarchical-id / prefix-with-power +; Element types that can be used in composite expressions +composite-element-type = "u" / "d" / "q" + +; Element identifiers can be numeric, named, native, hierarchical, or prefix specifications +element-id = number / name / native-id / hierarchical-id / prefix-with-power ; Numeric identifier number = 1*DIGIT @@ -30,6 +34,11 @@ number = 1*DIGIT ; Named identifier name = 1*( ALPHA / DIGIT / "_" / "-" ) +; Native identifier (UnitsML identifiers like u:meter, d:length, or NIST identifiers like NISTu1, NISTd2) +native-id = ("u:" / "d:" / "p:" / "q:" / "us:") name / "NIST" element-type 1*DIGIT ["." *native-element-part] +native-element-part = element-type [prefix-part] ["e" ["-"] number "/" number] +prefix-part = "p" number "'" number + ; Hierarchical identifier with colon separators hierarchical-id = name *( ":" name ) @@ -55,7 +64,7 @@ function-term = function-name "(" expression ")" function-name = "sqrt" ; Exponent notation -exponent = "_e_" exponent-value +exponent = "_" exponent-value exponent-value = number / fraction / grouped-exponent fraction = "(" number "/" number ")" grouped-exponent = "(" ["-"] number ["." number] ")" @@ -64,4 +73,5 @@ grouped-exponent = "(" ["-"] number ["." number] ")" operator = "*" / "/" ---- -This ABNF grammar provides a formal definition of the syntax for UnitsML URNs, ensuring consistent parsing and interpretation across implementations. +This ABNF grammar provides a formal definition of the syntax for UnitsML URNs, +ensuring consistent parsing and interpretation across implementations. diff --git a/unitsdb b/unitsdb index a6898e3..a961467 160000 --- a/unitsdb +++ b/unitsdb @@ -1 +1 @@ -Subproject commit a6898e39be6fe6b7d724cc5853ec759e35379014 +Subproject commit a9614673b163bb5f2921916de7cd0cbbfe16cc29