Add specification for UnitsDB 1.0.0

metanorma.yml

@@ -3,6 +3,7 @@ metanorma:
   source:
     files:
       - sources/asciiunits/document.adoc
+      - sources/unitsdb/document.adoc
       # - sources/unitsml-guide/document.adoc
       # - sources/unitsml-incorporation/document.adoc
       # - sources/unitsml-ubl-ndr-subset/document.adoc

sources/unitsdb-spec/sections/01-scope.adoc → sources/unitsdb/sections/01-scope.adoc

@@ -4,6 +4,8 @@ This document specifies the data models, structures, and normalization rules for
 UnitsDB, the authoritative database of measurement units, quantities,
 dimensions, and prefixes for the UnitsML framework.
 
+NOTE: This document applies to UnitsDB version 1.0.0.
+
 The specification defines:
 
 * The overall architecture of UnitsDB
@@ -15,15 +17,16 @@ The specification defines:
 
 This document:
 
-* Does not specify the software implementation details for using UnitsDB in applications
+* Does not specify implementation details for using UnitsDB in applications
 * Does not define algorithms for unit conversions or dimensional analysis (though the data provided supports these operations)
 * Does not provide a comprehensive list of all units, quantities, dimensions, and prefixes (these are provided in the actual database)
 
 This specification is intended for:
 
 * Developers implementing UnitsML systems
-* Database administrators managing UnitsDB installations
+* Developers managing UnitsDB database instances
 * Contributors extending or modifying the UnitsDB database
 * Standards developers referencing UnitsDB
 
-The specification enables interoperable representation of measurement units and related concepts across different applications, domains, and systems.
+The specification enables interoperable representation of measurement units and
+related concepts across different applications, domains, and systems.

sources/unitsdb/sections/02-normrefs.adoc

@@ -0,0 +1,4 @@
+[bibliography]
+== Normative references
+
+* [[SI_Brochure,BIPM SI Brochure]], SI Brochure: The International System of Units (SI), 9th edition, 2019, BIPM

sources/unitsdb-spec/sections/05-architecture.adoc → sources/unitsdb/sections/05-architecture.adoc

@@ -1,5 +1,6 @@
 == Architecture
 
+
 === General
 
 The UnitsDB architecture follows a modular design that organizes
@@ -13,26 +14,27 @@ models.
 
 === File organization
 
-UnitsDB is organized into five primary YAML files, each responsible for a different component of the measurement system:
-
+UnitsDB is organized into five primary YAML files, each responsible for a
+different component of the measurement system.
 
-*`dimensions.yaml`::
+`dimensions.yaml`::
 Contains definitions of physical dimensions (length, mass, time, etc.)
 
-*`quantities.yaml`::
+`quantities.yaml`::
 Contains definitions of measurable quantities (length, velocity, force, etc.)
 
-*`units.yaml`::
+`units.yaml`::
 Contains definitions of measurement units (meter, second, newton, etc.)
 
-*`prefixes.yaml`::
+`prefixes.yaml`::
 Contains definitions of unit prefixes (kilo, milli, mega, etc.)
 
-*`unit_systems.yaml`::
+`unit_systems.yaml`::
 Contains definitions of unit systems (SI, non-SI) and their categories
 
 Each file contains entries that follow a consistent model structure as defined using the lutaml-model language.
 
+
 === Entity relationships
 
 The UnitsDB architecture establishes explicit relationships between different entities to create a coherent measurement system:
@@ -56,12 +58,16 @@ The UnitsDB architecture establishes explicit relationships between different en
   +----------------------------------------------------------------+
 ----
 
-The key relationships are:
+The key relationships are described below.
 
 * Dimension ↔ Quantity: Each quantity has exactly one dimension, but multiple quantities can share the same dimension
+
 * Quantity ↔ Unit: Each quantity can be measured by multiple units, and each unit can measure multiple quantities (many-to-many relationship)
+
 * Unit ↔ Dimension: Each unit has exactly one dimension, which must match the dimension of the quantities it measures
+
 * Prefix ↔ Unit: Prefixes can be applied to units to create new prefixed units
+
 * UnitSystem ↔ Unit: Each unit belongs to a specific unit system
 
 These relationships are implemented through cross-references between the different YAML files.
@@ -70,42 +76,40 @@ These relationships are implemented through cross-references between the differe
 
 UnitsDB uses a consistent cross-reference mechanism to link entities across different files:
 
-* References to dimensions use the format `#NISTdX` (e.g., `#NISTd1` for length)
-* References to quantities use the format `#NISTqX` (e.g., `#NISTq1` for length)
-* References to units use the format `#NISTuX` (e.g., `#NISTu1` for meter)
-* References to prefixes use the format `#NISTpX_Y` (e.g., `#NISTp10_3` for kilo)
+* References to dimensions use the format `#NISTdX` (e.g., `#NISTd1` for length).
+* References to quantities use the format `#NISTqX` (e.g., `#NISTq1` for length).
+* References to units use the format `#NISTuX` (e.g., `#NISTu1` for meter).
+* References to prefixes use the format `#NISTpX_Y` (e.g., `#NISTp10_3` for kilo).
 
-These cross-references create a web of relationships that maintain the integrity and coherence of the measurement system.
+These cross-references create a web of relationships that maintain the integrity
+and coherence of the measurement system.
 
-=== Lutaml-model language
+=== Information models
 
-UnitsDB uses the lutaml-model language to define the structure of each data model. The lutaml-model language provides a human-readable way to define class-like structures with attributes and relationships.
+UnitsDB defines five primary classes.
 
-The general pattern for a lutaml-model class definition is:
+`Dimension`::
+Represents the mathematical concept of a physical dimension
 
-[source,lutaml]
-----
-class ClassName {
-  attribute attributeName, AttributeType {
-    definition "Description of the attribute"
-  }
-  // Additional attributes...
-}
-----
+`Quantity`::
+Represents a measurable property with a specific dimension
+
+`Unit`::
+Represents a reference for measuring quantities
 
-UnitsDB defines five primary classes using lutaml-model:
+`Prefix`::
+Represents a multiplier for units
 
-* `Dimension`: Represents the mathematical concept of a physical dimension
-* `Quantity`: Represents a measurable property with a specific dimension
-* `Unit`: Represents a reference for measuring quantities
-* `Prefix`: Represents a multiplier for units
-* `UnitSystem`: Represents a system of units (e.g., SI, non-SI)
+`UnitSystem`::
+Represents a system of units (e.g., SI, non-SI)
 
-Each class definition specifies the attributes that should be present in the corresponding YAML files.
+Each class definition specifies the attributes that should be present in the
+corresponding YAML files.
 
 === Inheritance hierarchies
 
-UnitsDB does not use formal inheritance hierarchies, but it does establish conceptual hierarchies through relationships:
+UnitsDB does not use formal inheritance hierarchies, but it does establish
+conceptual hierarchies through relationships:
 
 * Base dimensions vs. derived dimensions: Derived dimensions are composed of combinations of base dimensions
 * Base quantities vs. derived quantities: Derived quantities reference dimensions that are combinations of base dimensions
@@ -127,7 +131,10 @@ These extension points allow UnitsDB to evolve while maintaining backward compat
 
 === Model mapping to YAML
 
-The lutaml-model class definitions are mapped to YAML structures in the database files. For example, the `Unit` class defined in lutaml-model:
+The lutaml-model class definitions are mapped to YAML structures in the database
+files.
+
+For example, the `Unit` class defined in lutaml-model:
 
 [source,lutaml]
 ----

sources/unitsdb-spec/sections/11-normalization.adoc → sources/unitsdb/sections/11-normalization.adoc

@@ -2,32 +2,14 @@
 
 === General
 
-Data file normalization in UnitsDB refers to the process of organizing and structuring the YAML files that make up the database to ensure consistency, non-redundancy, and integrity. These rules help maintain the quality and reliability of the data while facilitating its use in various applications.
+Data file normalization in UnitsDB refers to the process of organizing and
+structuring the YAML files that make up the database to ensure consistency,
+non-redundancy, and integrity. These rules help maintain the quality and
+reliability of the data while facilitating its use in various applications.
 
 === Normalization principles model
 
-==== General
-
-The normalization principles model defines the fundamental rules that govern how data is organized and referenced throughout the UnitsDB database.
-
-==== Key normalization principles
-
-[source,lutaml]
-----
-class NormalizationPrinciple {
-  attribute principle_type, String {
-    definition "Type of normalization principle"
-  }
-  attribute description, String {
-    definition "Description of the principle"
-  }
-  attribute examples, Array {
-    definition "Examples demonstrating the principle"
-  }
-}
-----
-
-===== Unique identifiers
+==== Unique identifiers
 
 All model instances within UnitsDB (dimensions, quantities, units, prefixes, etc.) must have unique identifiers. These identifiers follow a consistent pattern:
 
@@ -38,7 +20,7 @@ All model instances within UnitsDB (dimensions, quantities, units, prefixes, etc
 
 Where `X` and `Y` are numeric values.
 
-===== References
+==== References
 
 References between entities must use consistent paths:
 
@@ -48,7 +30,7 @@ References between entities must use consistent paths:
 
 These references create a web of relationships that maintain the integrity of the database.
 
-===== Hierarchical organization
+==== Hierarchical organization
 
 The data is organized in a hierarchical manner that reflects the logical relationship between entities:
 
@@ -59,27 +41,6 @@ The data is organized in a hierarchical manner that reflects the logical relatio
 
 === File normalization model
 
-==== General
-
-The file normalization model defines specific rules for each YAML file in the UnitsDB database to ensure internal consistency and proper structure.
-
-[source,lutaml]
-----
-class FileNormalization {
-  attribute file_name, String {
-    definition "Name of the YAML file"
-  }
-  attribute entity_type, String {
-    definition "Type of entity contained in the file"
-  }
-  attribute rules, Array {
-    definition "Normalization rules specific to this file"
-  }
-}
-----
-
-==== File-specific normalization rules
-
 ===== dimensions.yaml
 
 * Each dimension entry must have a unique identifier.
@@ -122,30 +83,6 @@ class FileNormalization {
 
 === Cross-file normalization model
 
-==== General
-
-The cross-file normalization model defines rules that govern relationships between entities across different files in the UnitsDB database.
-
-[source,lutaml]
-----
-class CrossFileNormalization {
-  attribute relationship_type, String {
-    definition "Type of relationship between entities"
-  }
-  attribute source_entity, String {
-    definition "Source entity type"
-  }
-  attribute target_entity, String {
-    definition "Target entity type"
-  }
-  attribute rules, Array {
-    definition "Normalization rules for this relationship"
-  }
-}
-----
-
-==== Cross-file normalization rules
-
 ===== Dimension-quantity relationships
 
 * Each quantity must reference a valid dimension.
@@ -225,84 +162,3 @@ When updating the UnitsDB data files, the following rules should be applied:
 * When an entity needs to be deprecated, it should be marked as such rather than removed.
 * Major structural changes to the data format should be accompanied by a version increment and appropriate documentation.
 
-=== Normalized data examples
-
-==== General
-
-These examples demonstrate how properly normalized data should appear across the different UnitsDB files.
-
-==== Example of normalized data
-
-Here is an example of how normalized data should appear across the different files:
-
-.dimensions.yaml (excerpt)
-[source,yaml]
-----
-NISTd1:
-  length:
-    powerNumerator: 1
-    symbol: L
-    dim_symbols:
-    - id: dim_L
-      ascii: L
-      html: "𝖫"
-      mathml: "<mi mathvariant='sans-serif'>L</mi>"
-      latex: "\\ensuremath{\\mathsf{L}}"
-      unicode: "\U0001D5AB"
-----
-
-.quantities.yaml (excerpt)
-[source,yaml]
-----
-NISTq1:
-  dimension_url: "#NISTd1"
-  quantity_type: base
-  quantity_name:
-  - length
-  unit_reference:
-  - name: meter
-    url: "#NISTu1"
-----
-
-.units.yaml (excerpt)
-[source,yaml]
-----
-NISTu1:
-  dimension_url: "#NISTd1"
-  short: meter
-  root: true
-  unit_system:
-    type: SI_base
-    name: SI
-  unit_name:
-  - meter
-  unit_symbols:
-  - id: m
-    ascii: m
-    html: m
-    mathml: "<mi mathvariant='normal'>m</mi>"
-    latex: "\\ensuremath{\\mathrm{m}}"
-    unicode: m
-  root_units:
-  - unit: meter
-    power_numerator: 1
-  quantity_reference:
-  - name: length
-    url: "#NISTq1"
-----
-
-.prefixes.yaml (excerpt)
-[source,yaml]
-----
-NISTp10_3:
-  name: kilo
-  symbol:
-    ascii: k
-    html: k
-    latex: k
-    unicode: k
-  base: 10
-  power: 3
-----
-
-This example demonstrates the proper normalization of data across the files, with consistent identifiers, references, and structured data.