Suma: utility for the STEP Unified Model-driven Architecture

The build command processes a Metanorma site manifest and generates the specified output.

Parameters:

METANORMA_SITE_MANIFEST

This is the path to the Metanorma site manifest, typically metanorma.yml.

Options:

--[no-]compile

Compile or skip compilation of collection (default: true)

--schemas-all-path=PATH, -s PATH

Generate file that contains all schemas in the collection

--[no-]staged

Memory-bounded build: compile each member in its own process, then reinflate

--[no-]incremental

Re-render only changed schemas and their transitive dependents

--state-file=PATH

Incremental build state file (default: plain_schemas/.suma-build-state.json)

--jobs=N

Concurrent schema export workers (document compilation stays sequential; default: 1)

--provenance=PATH

Write a provenance manifest (sha256 of inputs/outputs + toolchain versions)

--sign=METHOD

Sign the provenance manifest: minisign or sigstore

--sign-key=PATH

Signing key; minisign requires it, sigstore signs keylessly when omitted

The generated schemas-*.yaml file name is derived from the input file name with the word metanorma replaced with schemas.

Repeated builds reuse work and are reproducible: a schema document is rendered again only when its adoc, schema config, schema source, or the rendering toolchain changed, and the collection render is skipped entirely when no site input changed (state: _site/.suma-site-build.json). Metanorma’s random manifest identifiers and per-document type markers are canonicalized, so two identical builds produce byte-identical output. A provenance manifest covers schema_docs, plain_schemas, and _site, and verification reports files that appeared under those roots without being recorded (build metadata such as the site state file is excluded explicitly).

Top-level schema documents render with live cross-reference links: every schema.entity and entity.attribute reference Expressir emits becomes an in-page link, and suma validate anchors verifies that no link is dead.

All documents need to have a schemas.yaml in their document root that lists out which schemas the document includes.

The reformat command provides utilities for reformatting EXPRESS files.

Parameters:

EXPRESS_FILE_PATH

Path to an EXPRESS file or a folder containing EXPRESS files

Options:

--[no-]recursive, -r

Select EXPRESS files recursively based on the specified folder path (default: false)

This command:

• Loads the EXPRESS files specified in the EXPRESS_FILE_PATH

• Reformats and saves the loaded EXPRESS files

The suma generate-schemas command generates an EXPRESS schema manifest file containing all schemas of documents referenced in the Metanorma manifest file, recursively.

Parameters:

METANORMA_MANIFEST_FILE

Path to the Metanorma manifest file (e.g.: "metanorma-smrl-all.yml")

Options:

--exclude_path, -e

Exclude schemas by pattern (e.g. *_lf.exp)

All documents need to have a schemas.yaml in their document root that lists out which schemas the document includes.

The "extract terms" command is implemented for ISO 10303-2, and could also be used for other EXPRESS schema collections that require term extraction for glossary or dictionary applications.

The suma extract-terms command extracts terms from EXPRESS schemas and generates a Glossarist v3 dataset in the output directory. This command processes various types of STEP schemas and creates standardized terminology datasets suitable for glossary and dictionary applications.

Parameters:

SCHEMA_MANIFEST_FILE

Path to the schema manifest file that lists all schemas to process (e.g., "schemas-smrl-all.yml")

GLOSSARIST_OUTPUT_PATH

Path to the output directory where the Glossarist v3 dataset will be generated

Options:

--language_code, -l

Language code for the Glossarist dataset (default: "eng")

--edition=N

Owning edition recorded on each concept

--language-codes=a,b

Additional linked localization languages (the primary language is always included)

The suma ingest-translations command overlays translated content onto extracted concepts. A translations file is a YAML sequence of localized-concept documents, each keyed by concept id (or localized UUID) and carrying the fields to apply:

Every field the entry provides replaces that localization’s field; every field it omits keeps the source-language content (a language absent from the extracted concepts is created with the same stable UUID convention the linked localizations use). Updated concepts are written in place, or to --output when given.

The suma generate-register command reads an EXPRESS schema manifest and emits a Glossarist v3 register.yaml with hierarchical sections. The output is used by the concept browser to render a navigable sidebar of sections and to resolve concept cross-references.

Parameters:

SCHEMA_MANIFEST_FILE

Path to the schema manifest (e.g., "schemas-smrl-part-2.yml")

OUTPUT_PATH

Directory where register.yaml will be written

Options:

--urn, -u

Base URN prefix for the dataset (e.g. urn:iso:std:iso:10303:-2:ed-2:en:tech:*). The wildcard is stripped for the base URN and kept in urnAliases. Required.

--year=N

Edition year recorded on the register

--supersedes=URN

URN/ref of the superseded edition

--edition=N

Edition number, tagged as edition:N; every register also carries a dataset:<id> tag so sibling editions can be grouped.

The URN is fully configurable — every component can be changed to match the dataset being exported. The general structure is:

For example, to export edition 3 in French:

The current ISO 10303-2 SMRL data is edition 2; use ed-2 unless you are re-publishing an earlier edition.

--id

Dataset identifier (e.g. iso10303-2-express). Required.

--ref

Human-readable dataset reference label (e.g. ISO 10303-2 EXPRESS Concepts). Required.

--language_code, -l

Language code for section names (default: "eng")

The generated register contains two top-level groups:

• Resources — integrated resource schemas (path contains schemas/resources/)

• Application Modules — ARM and MIM schemas (path contains schemas/modules/)

Each schema gets a human-readable name via the SchemaNaming module (e.g. topology_schema → "Resource: Topology", Activity_method_assignment_mim → "Module: Activity Method Assignment (MIM)"). Acronyms (AIC, AEC, BREP, 2D, 3D) are preserved; function words (as, of, the) are lowercased per ISO title-case convention.

The suma convert-jsdai command converts JSDAI EXPRESS-G diagram outputs (XML + image file) into SVG and Annotated EXPRESS formats suitable for Metanorma documentation.

JSDAI (Java Step Data Access Interface) Java tool is used by ISO/TC 184/SC 4 to create EXPRESS-G diagrams.

JSDAI generates two files for each diagram:

• a raster image file (GIF or JPEG)

• an XML file containing image metadata and clickable area definitions

This command converts these inputs into:

• an SVG file that embeds the raster image as Base64 with clickable rectangular areas

• an Annotated EXPRESS file with a Metanorma svgmap block for easy copy-paste

Where:

XML_FILE

Path to the JSDAI XML file (e.g., "action_schemaexpg1.xml")

IMAGE_FILE

Path to the raster image file (GIF or JPEG format)

OUTPUT_DIR

Path to the output directory where SVG and EXP files will be generated

This command:

• Parses the JSDAI XML file to extract image metadata and clickable area definitions

• Reads the raster image file and converts it to base64 format

• Generates an SVG file with:

  • The embedded base64-encoded image

  • Clickable rectangular areas (<a> and <rect> elements) corresponding to the XML definitions

  • Proper viewBox dimensions matching the source image

• Generates an Annotated EXPRESS file containing:

  • A Metanorma svgmap block with numbered cross-references

  • Proper anchor IDs for document integration

  • Cross-reference targets extracted from the XML href attributes

The generated SVG and EXP files work together through a numbered mapping system:

1. In the SVG file, each clickable area is assigned a sequential number:

   <a href="1"><rect .../></a>
   <a href="2"><rect .../></a>
   <a href="3"><rect .../></a>

2. In the EXPRESS file, the svgmap block maps these numbers to targets which are either EXPRESS or AsciiDoc anchors.

   Example 4. Resource schema diagram with SVG and Annotated EXPRESS cross-references

   (*"action_schema.__expressg"
   [[action_schema_expg1]]
   [.svgmap]
   ====
   image::action_schemaexpg1.svg[]
   
   * <<express:basic_attribute_schema>>; 1
   * <<express:action_schema>>; 2
   * <<express:support_resource_schema>>; 3
   ====
   *)

   Example 5. Module schema diagram with SVG and Annotated EXPRESS cross-references

   (*"Activity_mim.__expressg"
   [[Activity_mim_expg1]]
   [.svgmap]
   ====
   image::mimexpg1.svg[]
   
   * <<Activity_mim_expg2>>; 1
   * <<express:action_schema>>; 2
   * <<Activity_method_mim_expg1>>; 3
   * <<express:basic_attribute_schema>>; 4
   * <<express:management_resources_schema>>; 5
   ====
   *)

3. When rendered in Metanorma, clicking on "area 1" in the SVG, will navigate to the express:basic_attribute_schema anchor, "area 2" to express:action_schema, and so on.

The mapping is derived from the original JSDAI XML file, where each <img.area> element contains:

coords attribute

converted to SVG <rect> dimensions

href attribute

converted to EXPRESS cross-reference target in the svgmap block

Sequential position

assigned as the numbered href in both SVG and svgmap list

Suma works with any schema collection. Suma::SchemaProfile declares how schema identifiers and paths map to types, how identifiers become display names, and the ordered register categories. Registered profiles:

iso10303

Default; STEP conventions including /applications/ classifying as an application protocol

generic

No STEP conventions (one category for every schema)

ifc

buildingSMART IFC editions: one standalone schema per edition (ifc4, ifc4x3, …​), edition names preserved uppercase (IFC4, IFC4X3), Ifc-prefixed declarations, one Other Schemas register category

An AP publication is a lead schema bundled with the module and resource schemas it USEs. --publication SCHEMA_ID computes the transitive USE-FROM/REFERENCE closure and writes the bundle flat under OUTPUT/<lead_id>/. In the register, application protocols are grouped under a per-publication parent section.

suma export --format owl projects a parsed corpus into OWL/Turtle:

• entities become owl:Class; SUBTYPE OF becomes rdfs:subClassOf

• SELECT types become owl:unionOf; enumerations become owl:oneOf named individuals

• simple type aliases become rdfs:Datatype

• explicit, derived, and inverse attributes become object/datatype properties attached through named owl:Restriction nodes, with cardinality from optionality and aggregate bounds

• WHERE, DERIVE, and INVERSE clauses are preserved as annotated constraints

IRIs derive from the corpus URN scheme (<base>:tech:<schema>.<element>). Per-schema ontologies declare owl:imports for their USE-FROM/REFERENCE targets, and --corpus adds a corpus ontology importing every schema. The projection is validated before writing (materialization, property declarations, orphan classes, dangling superclasses, superclass cycles), and contains no blank nodes, so it is deterministic and golden-comparable.

The package-gcr command bundles extracted concepts into a GCR (Glossarist Concept Repository) archive — the sealed distribution format consumed by the Glossarist Vocabulary Browser:

The archive contains metadata.yaml (identity, statistics), the original register.yaml, and concepts/ in the browser’s canonical flat format (termid, term, one block per language). Both a versioned ({shortname}-{version}.gcr) and an unversioned ({shortname}.gcr) archive are written. Pass --created-at to pin the package timestamp for byte-reproducible archives. Point the browser’s datasets.yml at the published archive (or at the concepts directory in development via localPath).

suma serve serves a resolve --all artifact tree at its URN-derived paths, returning JSON or HTML according to the request’s Accept header:

Production hosting maps the same paths statically; no application server is required.

The resolve command turns URNs into static, dereferenceable artifacts: a canonical JSON document (sorted keys) and an HTML page per URN, written under a path derived from the URN itself. It resolves:

• tech: schema, declared-element, and attribute (OWL property) URNs from a schema manifest

• term: concept URNs from Glossarist concept documents

• the dataset URN from register.yaml

--all also writes index.html, linking every artifact. No server is required.

Suma can be used programmatically in your Ruby applications. The following examples demonstrate common usage patterns.

Schema manifests are loaded via Expressir::SchemaManifest:

Suma’s domain is split into MECE concerns:

• Data models (pure): CollectionManifest, ExpressSchema

• Value objects (pure): SchemaCategory, Urn

• Services (single concern): ManifestTraverser, SchemaDiscovery, SchemaCompiler, SchemaExporter, SchemaIndex, LinkValidator, SchemaComparer, SchemaManifestGenerator, TermExtractor, RegisterManifestGenerator, Processor

• Renderers (pure, composable): SchemaTemplate::Plain, SchemaTemplate::Document

Key invariants:

• The classifier ExpressSchema::Type.classify(id:, path:) is the single source of truth for schema type. SchemaCategory, SchemaNaming, SchemaExporter, and RegisterManifestGenerator all derive from it.

• Urn owns URN semantics (wildcard stripping, base/alias split, leaf composition).

• CollectionManifest is a pure data model; tree walking lives in ManifestTraverser, schema I/O lives in SchemaDiscovery.

• SchemaCompiler orchestrates one Metanorma compilation; the adoc body is injected via a SchemaTemplate::* renderer.

Code-style rules enforced throughout lib/suma/:

• Ruby autoload only — no require_relative

• No send to call private methods

• No instance_variable_set / instance_variable_get

• No respond_to? for type checking

• Utils.log writes to $stderr; debug level gated by SUMA_DEBUG