specitems 1.6.2__tar.gz → 1.6.4__tar.gz

{specitems-1.6.2 → specitems-1.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specitems
-Version: 1.6.2
+Version: 1.6.4
 Summary: Provides interfaces to work with specification items.
 Keywords: certification,documentation,markdown,qualification,requirements-management,traceability
 Author: The specitems Authors

{specitems-1.6.2 → specitems-1.6.4}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "specitems"
-version = "1.6.2"
+version = "1.6.4"
 description = "Provides interfaces to work with specification items."
 authors = [
     {name = "The specitems Authors", email = "specthings@embedded-brains.de"}
@@ -54,6 +54,7 @@ specpickle = "specitems.clipickle:clipickle"
 specdocitems = "specitems.clispecdoc:clispecdocitems"
 spechash = "specitems.clihash:clihash"
 specyamlquery = "specitems.cliyamlquery:cliyamlquery"
+specverify = "specitems.cliverify:cliverify"
 
 [build-system]
 requires = ["uv_build>=0.10.0"]

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/__init__.py

@@ -62,10 +62,8 @@ from .contentcommonmark import (
     CommonMarkContent,
     CommonMarkMapper,
 )
-from .contentmarkdown import (
-    MarkdownContent,
-    MarkdownMapper,
-)
+from .contentmarkdown import (MarkdownContent, MarkdownMapper,
+                              format_markdown_text)
 from .contentsphinx import (
     SphinxContent,
     SphinxMapper,
@@ -128,11 +126,14 @@ from .itemmapper import (
     ItemMapper,
     ItemValueProvider,
     get_value_default,
+    to_at_variables,
+    to_dollar_variables,
     unpack_arg,
     unpack_args,
 )
 from .specdoc import (SpecDocumentConfig, add_specification_documentation,
                       generate_specification_documentation)
+from .specformatter import SpecYAMLFormatter
 from .specverify import (
     SpecVerifier,
     verify_specification_format,
@@ -185,6 +186,7 @@ __all__ = [
     "SpecDocumentConfig",
     "SpecTypeProvider",
     "SpecVerifier",
+    "SpecYAMLFormatter",
     "SphinxContent",
     "SphinxMapper",
     "TextContent",
@@ -197,6 +199,7 @@ __all__ = [
     "create_unique_link",
     "data_digest",
     "escape_code_line",
+    "format_markdown_text",
     "generate_glossary",
     "generate_specification_documentation",
     "get_arguments",
@@ -231,8 +234,10 @@ __all__ = [
     "run_subprocess_action",
     "save_data",
     "split_copyright_statement",
+    "to_at_variables",
     "to_camel_case",
     "to_collection",
+    "to_dollar_variables",
     "to_iterable",
     "unpack_arg",
     "unpack_args",

specitems-1.6.4/src/specitems/cliverify.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+Provides a command line interface to verify the specification item format.
+"""
+
+# Copyright (C) 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import importlib.metadata
+import logging
+from pathlib import Path
+import sys
+
+from .cliutil import get_arguments
+from .items import (ItemCache, ItemCacheConfig, ItemDataByUID,
+                    ItemTypeProvider, SpecTypeProvider)
+from .specformatter import SpecYAMLFormatter
+from .specverify import verify_specification_format
+
+
+# Packages using specitems can register their types through the following
+# plugin mechanism.  They have to add something like this to their
+# `pyproject.toml` file:
+#
+# [project.entry-points."specitems_type_provider.plugins"]
+# mypackage = "mypackage.mymodule:load_mypackage_types"
+def _create_type_provider() -> ItemTypeProvider:
+    data_by_uid: ItemDataByUID = {}
+    for ep in importlib.metadata.entry_points(
+            group="specitems_type_provider.plugins"):
+        load_types = ep.load()
+        data_by_uid.update(load_types())
+    return SpecTypeProvider(data_by_uid)
+
+
+def cliverify(argv: list[str] = sys.argv) -> int:
+    """
+    Verify the specification item format and optionally format the items.
+    """
+
+    def _add_arguments(parser):
+        parser.add_argument("--format-items",
+                            action="store_true",
+                            help="format the items")
+        parser.add_argument("--clang-format-path",
+                            default="clang-format",
+                            help="the path to the clang-format executable")
+        parser.add_argument(
+            "--clang-format-style",
+            action="append",
+            default=[],
+            metavar="CLANG_FORMAT_STYLE",
+            help="a clang-format style name used by the "
+            "specification types and, separated by a colon, "
+            "the associated clang-format style "
+            "file (example: file-scope:.clang-format); "
+            "the style name is not related to the built-in styles "
+            "of clang-format; this option can be given multiple times")
+        parser.add_argument("spec_items_or_directories",
+                            nargs="+",
+                            metavar="SPEC_ITEM_OR_DIRECTORY",
+                            help="specification item file or directory")
+
+    args = get_arguments(argv[1:],
+                         default_log_level="WARNING",
+                         description=cliverify.__doc__,
+                         add_arguments=(_add_arguments, ))
+    uid_log_level = logging.ERROR
+    item_files: list[str] = []
+    spec_dirs: list[str] = []
+    for path in args.spec_items_or_directories:
+        if Path(path).is_file():
+            uid_log_level = logging.INFO
+            item_files.append(path)
+        else:
+            spec_dirs.append(path)
+    config = ItemCacheConfig(paths=spec_dirs)
+    item_cache = ItemCache(config, type_provider=_create_type_provider())
+    for path in item_files:
+        item_cache.add_item_from_file(path, path, initialize_links=False)
+    clang_format_style: dict[str, str] = {}
+    for style_file in args.clang_format_style:
+        style, sep, file = style_file.partition(":")
+        if not sep or not style or not file:
+            logging.error(
+                "the --clang-format-style option value '%s' "
+                "is not in <name>:<path> format", style_file)
+            return 1
+        clang_format_style[style] = file
+    if args.format_items:
+        formatter = SpecYAMLFormatter(clang_format_path=args.clang_format_path,
+                                      clang_format_style=clang_format_style)
+    else:
+        formatter = None
+    return verify_specification_format(item_cache,
+                                       uid_log_level=uid_log_level,
+                                       formatter=formatter).exit_code()

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/cliyamlquery.py

@@ -3,7 +3,7 @@
 Provides a command line interface to Print the specified value of a YAML file.
 """
 
-# Copyright (C) 2024 embedded brains GmbH & Co. KG
+# Copyright (C) 2024, 2026 embedded brains GmbH & Co. KG
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
@@ -29,7 +29,7 @@ Provides a command line interface to Print the specified value of a YAML file.
 import argparse
 import sys
 
-from specitems import EmptyItemCache, Item, ItemMapper, load_data
+from specitems import EmptyItemCache, Item, load_data
 
 
 def cliyamlquery(argv: list[str] = sys.argv) -> None:
@@ -43,4 +43,4 @@ def cliyamlquery(argv: list[str] = sys.argv) -> None:
     parser.add_argument("file", metavar="FILE", nargs=1, help="the YAML file")
     args = parser.parse_args(argv[1:])
     item = Item(EmptyItemCache(), "/x", load_data(args.file[0]))
-    print(ItemMapper(item).substitute(f"${{.:{args.path[0]}}}"))
+    print(item.get_value(args.path[0]))

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/contentmarkdown.py

@@ -53,6 +53,13 @@ def _simple_row(row: Iterable[str], maxi: Iterable[int]) -> str:
     return f" | {line} |"
 
 
+def format_markdown_text(text: str) -> str:
+    """ Format the Markdown text. """
+    return mdformat.text(text,
+                         options=_MDFORMAT_OPTIONS,
+                         extensions=_MDFORMAT_EXTENSIONS)
+
+
 class MarkdownContent(TextContent):
     """ This class builds MyST Markdown content. """
 

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/itemmapper.py

@@ -37,10 +37,39 @@ from .items import Item, ItemType
 ItemGetValue = Callable[["ItemGetValueContext"], Any]
 ItemGetValueMap = dict[str, tuple[ItemGetValue, Any]]
 
-_VAR_NAME = "(?:[a-zA-Z0-9._/-]+|\\*):[\\[\\]a-zA-Z0-9._/-]+(?::[^${}]*)?"
-_VAR_SINGLE = re.compile(f"^[$@]\\{{{_VAR_NAME}\\}}$")
-_VAR_TOKENS = re.compile(f"(?:(\\$+|@+)\\{{{_VAR_NAME}\\}})|"
-                         r"(?:(\$+|@+)\{)")
+_VAR_NAME = "(?:[a-zA-Z0-9._/-]+|\\*):[\\[\\]a-zA-Z0-9._/-]+(?::[^$`{}]*)?"
+_VAR_SINGLE = re.compile(f"^[$@][{{`]{_VAR_NAME}[}}`]$")
+_VAR_TOKENS = re.compile(f"(?:(\\$+|@+)[{{`]{_VAR_NAME}[}}`])|"
+                         r"(?:(\$+|@+)[{{`])")
+
+
+def _to_something(mobj: re.Match, prefix: str, postfix: str) -> str:
+    designator = mobj.group(1)
+    token = mobj.group(0)
+    if designator:
+        brace = len(designator)
+        if brace & 1 == 0:
+            return token
+        return f"{token[:brace - 1]}{prefix}{token[brace + 1:-1]}{postfix}"
+    return token
+
+
+def _to_at(mobj: re.Match) -> str:
+    return _to_something(mobj, "@`", "`")
+
+
+def to_at_variables(text: str) -> str:
+    """ Convert the text to use ``@`...``` for all substitution variables.  """
+    return _VAR_TOKENS.sub(_to_at, text)
+
+
+def _to_dollar(mobj: re.Match) -> str:
+    return _to_something(mobj, "${", "}")
+
+
+def to_dollar_variables(text: str) -> str:
+    """ Convert the text to use ``${...}`` for all substitution variables.  """
+    return _VAR_TOKENS.sub(_to_dollar, text)
 
 
 class _ItemMapperError(Exception):
@@ -111,6 +140,8 @@ def unpack_arg(arg: str) -> str:
                     arg_2.append(",")
                 case "f":
                     arg_2.append("\f")
+                case "g":
+                    arg_2.append("`")
                 case "n":
                     arg_2.append("\n")
                 case "r":

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/items.py

@@ -33,6 +33,7 @@ import base64
 import dataclasses
 import hashlib
 import itertools
+import logging
 import os
 import pickle
 import re
@@ -407,6 +408,56 @@ class Item:
         """
         return self.data.get(key, default)
 
+    def get_value(self, path: str) -> Any:
+        """ Get the attribute value associated with the attribute path. """
+        value = self.data
+        path = path.strip("/")
+        while path:
+            key_end = path.find("/")
+            if key_end >= 0:
+                key_index = path[:key_end]
+                path = path[key_end + 1:]
+            else:
+                key_index = path
+                path = ""
+            parts = key_index.split("[")
+            try:
+                index = int(parts[1].split("]")[0])
+            except IndexError:
+                index = -1
+            value = value[parts[0]]
+            if index >= 0:
+                value = value[index]
+        return value
+
+    def set_value(self, path: str, value: Any) -> None:
+        """ Set the attribute value associated with the attribute path. """
+        parent = self.data
+        path = path.strip("/")
+        while path:
+            key_end = path.find("/")
+            if key_end >= 0:
+                key_index = path[:key_end]
+                path = path[key_end + 1:]
+            else:
+                key_index = path
+                path = ""
+            parts = key_index.split("[")
+            try:
+                index = int(parts[1].split("]")[0])
+            except IndexError:
+                index = -1
+            if path:
+                parent = parent[parts[0]]
+                if index >= 0:
+                    parent = parent[index]
+            else:
+                if index >= 0:
+                    parent = parent[parts[0]]
+                    parent[index] = value
+                else:
+                    parent[parts[0]] = value
+
     def to_abs_uid(self, abs_or_rel_uid: str) -> str:
         """
         Return the absolute UID of an absolute UID or an UID relative to this
@@ -1003,7 +1054,7 @@ class ItemCacheConfig:
     initialize_links: bool = True
     resolve_proxies: bool = True
     permissive_type_errors: bool = False
-    cache_directory: str = "cache"
+    cache_directory: str = ".specitems/cache"
 
 
 class ItemCache(dict):
@@ -1054,6 +1105,21 @@ class ItemCache(dict):
                 return item
             for item in proxy.children("proxy-member-default"):
                 return item
+            logging.warning("%s: cannot resolve proxy for enabled set %s", uid,
+                            sorted(self.enabled_set))
+            for item in proxy.children("proxy-member",
+                                       is_link_enabled=link_is_enabled):
+                logging.warning(
+                    "%s: has disabled proxy member %s enabled by %s", uid,
+                    item.uid, item["enabled-by"])
+            for item in proxy.children("proxy-member-default",
+                                       is_link_enabled=link_is_enabled):
+                logging.warning(
+                    "%s: has disabled default proxy member %s enabled by %s",
+                    uid, item.uid, item["enabled-by"])
+            logging.info(
+                "%s: note that items may get enabled recursively; "
+                "maybe a parent is disabled", uid)
         return proxy
 
     @property

specitems-1.6.4/src/specitems/specformatter.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: BSD-2-Clause
+""" Provides a specification item formatter. """
+
+# Copyright (C) 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import abc
+import subprocess
+from typing import Any
+
+import yaml
+
+from .contentmarkdown import format_markdown_text
+from .items import Item
+from .itemmapper import to_at_variables, to_dollar_variables
+
+
+class SpecFormatter(abc.ABC):
+    """ Provides a method to format values. """
+
+    def __init__(self, clang_format_path: str,
+                 clang_format_style: dict[str, str]) -> None:
+        super().__init__()
+        self.clang_format_path = clang_format_path
+        self.clang_format_style = clang_format_style
+
+    @abc.abstractmethod
+    def format_value(self, item: Item, path: str, value: Any,
+                     fmt: dict) -> None:
+        """ Format the value and set the item value according to the path. """
+
+    @abc.abstractmethod
+    def save(self, item: Item) -> None:
+        """ Save the item if it has a matching format. """
+
+
+def _format_clang(formatter: SpecFormatter, _item: Item, value: str,
+                  fmt: dict) -> str:
+    name = fmt["style"]
+    try:
+        style = formatter.clang_format_style[name]
+    except KeyError as err:
+        raise ValueError(f"unknown clang-format style '{name}', "
+                         "configure it via --clang-format-style") from err
+    cmd = [
+        formatter.clang_format_path, f"--style={style}",
+        "--assume-filename=specitems.c"
+    ]
+    result = subprocess.run(cmd,
+                            input=value,
+                            capture_output=True,
+                            encoding="utf-8",
+                            check=True)
+    return result.stdout
+
+
+def _format_myst(_formatter: SpecFormatter, _item: Item, value: str,
+                 _fmt: dict) -> str:
+    value = to_at_variables(value)
+    value = format_markdown_text(value)
+    return to_dollar_variables(value)
+
+
+class _ListOrder(dict):
+    pass
+
+
+def _format_list_order(_formatter: SpecFormatter, item: Item, value: Any,
+                       fmt: dict) -> Any:
+    # pylint: disable=attribute-defined-outside-init
+    value_2 = _ListOrder(value)
+    value_2.the_list = item.get_value(  # type: ignore[attr-defined]
+        fmt["path"])
+    value_2.key = fmt["key"]  # type: ignore[attr-defined]
+    return value_2
+
+
+def _format_list_order_representer(
+        representer: yaml.representer.BaseRepresenter, data: Any):
+    assert isinstance(representer, yaml.representer.SafeRepresenter)
+    order: dict[str, int] = {}
+    for index, element in enumerate(data.the_list):
+        order[element[data.key]] = index
+    if data.keys() != order.keys():
+        raise ValueError(
+            "the dictionary and order list key sets are not equal: "
+            f"{sorted(set(data.keys()).symmetric_difference(order.keys()))}")
+    return representer.represent_dict(
+        sorted(data.items(), key=lambda x: order[x[0]]))
+
+
+yaml.add_representer(_ListOrder, _format_list_order_representer)
+
+
+class _FormatInt(int):
+    pass
+
+
+def _format_int_presenter(representer: yaml.representer.BaseRepresenter,
+                          data: Any):
+    return representer.represent_scalar('tag:yaml.org,2002:int',
+                                        data.fmt.format(data))
+
+
+yaml.add_representer(_FormatInt, _format_int_presenter)
+
+
+def _format_int_fmt(value: Any, format_string: str) -> Any:
+    # pylint: disable=attribute-defined-outside-init
+    value = _FormatInt(value)
+    value.fmt = format_string
+    return value
+
+
+def _format_int_string(_formatter: SpecFormatter, _item: Item, value: Any,
+                       fmt: dict) -> Any:
+    return _format_int_fmt(value, fmt["format"])
+
+
+def _format_int_attribute(_formatter: SpecFormatter, item: Item, value: Any,
+                          fmt: dict) -> Any:
+    try:
+        format_string = item.get_value(fmt["path"])
+    except KeyError:
+        format_string = fmt.get("default")
+        if format_string is None:
+            raise
+    return _format_int_fmt(value, format_string)
+
+
+_YAML_FORMATTER = {
+    "myst": _format_myst,
+    "clang": _format_clang,
+    "int-format-string": _format_int_string,
+    "int-format-attribute": _format_int_attribute,
+    "list-order": _format_list_order,
+}
+
+
+class SpecYAMLFormatter(SpecFormatter):
+    """ Provides a method to format values for YAML files. """
+
+    # pylint: disable=too-few-public-methods
+    def format_value(self, item: Item, path: str, value: Any,
+                     fmt: dict) -> None:
+        value = _YAML_FORMATTER[fmt["type"]](self, item, value, fmt)
+        item.set_value(path, value)
+
+    def save(self, item: Item) -> None:
+        if item.file.endswith(".yml"):
+            item.save()

{specitems-1.6.2 → specitems-1.6.4}/src/specitems/specverify.py

@@ -34,10 +34,11 @@ represented by a :py:class:`LoggingStatus` object.
 
 import logging
 import re
-from typing import Any, NamedTuple
+from typing import Any, NamedTuple, Optional
 
 from .cliutil import LoggingStatus, monitor_logging
 from .items import Item, ItemCache
+from .specformatter import SpecFormatter
 
 _VerifierMap = dict[str, "_Verifier"]
 
@@ -202,10 +203,14 @@ def _prefix(prefix: _Path) -> str:
 
 class _Verifier:
 
-    def __init__(self, name: str, verifier_map: _VerifierMap) -> None:
+    def __init__(self,
+                 name: str,
+                 verifier_map: _VerifierMap,
+                 formatter: Optional[SpecFormatter] = None) -> None:
         self._name = name
         self._verifier_map = verifier_map
         self.is_subtype = False
+        self.formatter = formatter
         verifier_map[name] = self
 
     def verify_info(self, path: _Path) -> None:
@@ -312,13 +317,23 @@ class _ItemVerifier(_Verifier):
     """
 
     def __init__(self, name: str, verifier_map: _VerifierMap,
-                 info_map: dict[str, Any], item: Item) -> None:
-        super().__init__(name, verifier_map)
+                 formatter: Optional[SpecFormatter], info_map: dict[str, Any],
+                 item: Item) -> None:
+        super().__init__(name, verifier_map, formatter)
         self._info_map = info_map
         self._item = item
         self._subtype_key = ""
         self._subtype_verifiers: _VerifierMap = {}
 
+    def _format(self, formatter: SpecFormatter, path: _Path, value: Any,
+                type_info: Any) -> None:
+        fmt = type_info.get("format")
+        if fmt is not None:
+            logging.info("%s format using type '%s'", _prefix(path),
+                         fmt["type"])
+            _, _, attribute_path = path.path.partition(":")
+            formatter.format_value(path.item, attribute_path, value, fmt)
+
     def verify_bool(self, path: _Path, value: Any, type_info: Any) -> set[str]:
         """Verify a boolean value according to an optional assertion.
 
@@ -495,6 +510,9 @@ class _ItemVerifier(_Verifier):
                 logging.error(
                     "%s has unverfied keys for type '%s' and its subtypes: %s",
                     _prefix(path), self._name, sorted(unverified_keys))
+        formatter = self.formatter
+        if formatter is not None:
+            self._format(formatter, path, value, type_info)
         return verified_keys
 
     def verify_int_or_float(self, path: _Path, value: Any,
@@ -510,8 +528,12 @@ class _ItemVerifier(_Verifier):
         Returns:
             Empty set. Logs an error if assertions fail.
         """
-        if not _assert_int_or_float(path, value, type_info):
+        ok = _assert_int_or_float(path, value, type_info)
+        if not ok:
             logging.error("%s invalid value: %s", _prefix(path), value)
+        formatter = self.formatter
+        if ok and formatter is not None:
+            self._format(formatter, path, value, type_info)
         return set()
 
     def verify_list(self, path: _Path, value: Any, type_info: Any) -> set[str]:
@@ -557,8 +579,12 @@ class _ItemVerifier(_Verifier):
         Returns:
             Empty set. Logs an error if assertions fail.
         """
-        if not _assert_str(path, value, type_info):
+        ok = _assert_str(path, value, type_info)
+        if not ok:
             logging.error("%s invalid value: %s", _prefix(path), value)
+        formatter = self.formatter
+        if ok and formatter is not None:
+            self._format(formatter, path, value, type_info)
         return set()
 
     def verify(self, path: _Path, value: Any) -> set[str]:
@@ -619,7 +645,8 @@ _ASSERT_KEYS = {
 }
 
 
-def _create_verifier(item: Item, verifier_map: _VerifierMap) -> _Verifier:
+def _create_verifier(item: Item, verifier_map: _VerifierMap,
+                     formatter: Optional[SpecFormatter]) -> _Verifier:
     spec_type = item["spec-type"]
     if spec_type in verifier_map:
         verifier = verifier_map[spec_type]
@@ -627,13 +654,14 @@ def _create_verifier(item: Item, verifier_map: _VerifierMap) -> _Verifier:
         return verifier
     spec_info = item["spec-info"]
     assert isinstance(spec_info, dict)
-    return _ItemVerifier(spec_type, verifier_map, spec_info, item)
+    return _ItemVerifier(spec_type, verifier_map, formatter, spec_info, item)
 
 
-def _gather_item_verifiers(item: Item, verifier_map: _VerifierMap) -> None:
+def _gather_item_verifiers(item: Item, verifier_map: _VerifierMap,
+                           formatter: Optional[SpecFormatter]) -> None:
     for link in item.links_to_children():
         if link.role == "spec-member":
-            _create_verifier(link.item, verifier_map)
+            _create_verifier(link.item, verifier_map, formatter)
 
 
 class SpecVerifier:
@@ -647,11 +675,11 @@ class SpecVerifier:
     creation, it resolves subtype refinements and is ready to verify items.
     """
 
-    # pylint: disable=too-few-public-methods
     def __init__(self,
                  item_cache: ItemCache,
                  root_uid: str,
-                 uid_log_level: int = logging.ERROR) -> None:
+                 uid_log_level: int = logging.ERROR,
+                 formatter: Optional[SpecFormatter] = None) -> None:
         """Initialize and build verifier map.
 
         Args:
@@ -664,6 +692,7 @@ class SpecVerifier:
             uid_log_level: The log level to indicate that an UID cannot be
                 resolved.
         """
+        self._formatter = formatter
         verifier_map: _VerifierMap = {}
         _AnyVerifier("any", verifier_map)
         _NameVerifier("name", verifier_map)
@@ -678,8 +707,9 @@ class SpecVerifier:
         except KeyError:
             self._root_verifier = None
         else:
-            self._root_verifier = _create_verifier(root_item, verifier_map)
-            _gather_item_verifiers(root_item, verifier_map)
+            self._root_verifier = _create_verifier(root_item, verifier_map,
+                                                   formatter)
+            _gather_item_verifiers(root_item, verifier_map, formatter)
             for name in sorted(verifier_map):
                 logging.info("type: %s", name)
                 verifier_map[name].resolve_type_refinements()
@@ -694,10 +724,13 @@ class SpecVerifier:
             logging.error("root type item does not exist in item cache")
         else:
             logging.info("start specification item verification")
+            formatter = self._formatter
             for key in sorted(item_cache):
                 item = item_cache[key]
                 self._root_verifier.verify(_Path(item, f"{item.uid}:"),
                                            item.data)
+                if formatter is not None:
+                    formatter.save(item)
             logging.info("finished specification item verification")
 
     def verify(self, item: Item) -> LoggingStatus:
@@ -720,7 +753,8 @@ class SpecVerifier:
 
 def verify_specification_format(
         item_cache: ItemCache,
-        uid_log_level: int = logging.ERROR) -> LoggingStatus:
+        uid_log_level: int = logging.ERROR,
+        formatter: Optional[SpecFormatter] = None) -> LoggingStatus:
     """Verify all items using the specification root type from the item cache.
 
     Emits an error if the item cache has no specification root type.
@@ -729,6 +763,7 @@ def verify_specification_format(
         item_cache: The item cache containing the items to verify.
         uid_log_level: The log level to indicate that an UID cannot be
             resolved.
+        formatter: The optional specification item value formatter.
 
     Returns:
         The status summarizing the verification run.
@@ -738,6 +773,7 @@ def verify_specification_format(
         if root_type_uid is None:
             logging.error("item cache has no root type")
         else:
-            verifier = SpecVerifier(item_cache, root_type_uid, uid_log_level)
+            verifier = SpecVerifier(item_cache, root_type_uid, uid_log_level,
+                                    formatter)
             verifier.verify_all(item_cache)
         return monitor.get_status()