reqif

Labs

Syside Automator ReqIF import/export.

This module converts between ReqIF (Requirements Interchange Format) files and SysMLv2 workspaces. It can be driven from the command line or from Python scripts; both surfaces share the same underlying entry points.

Installation

The public functions and CLI both require the [reqif] extra which pulls in additional third-party dependencies. Install it with:

pip install 'syside[reqif]'
# or, for uv-managed projects:
uv add 'syside[reqif]'

When the extra is missing, the captured ImportError is exposed as _missing_extra_error for callers building their own CLI.

Command-line usage

The CLI is reachable both through the top-level syside console script and as a runnable module. The three are equivalent:

syside reqif <subcommand> [options]
python -m syside reqif <subcommand> [options]
python -m syside.reqif <subcommand> [options]

All subcommands operate on the current working directory as the workspace root. The available subcommands are:

• init — write the canonical SysideReqIF SysMLv2 library into the workspace so subsequent imports have something to reference. Use --lib-dir to override the default LIBRARY_DIR location.

• import <file> — convert a .reqif or .reqifz file into SysMLv2 packages under the workspace, performing a fresh build or a delta update depending on existing content. Attachments are extracted into --attachments-dir (default: ATTACHMENTS_DIR).

• lock — assign stable UUIDs and last-change timestamps to any ReqIF-tagged elements that don’t yet have them, so subsequent round-trips preserve identity. --source stamps the minted identities with the ReqIF exchange they belong to.

• link scaffold <file> — reconcile a ReqIF file’s type-level concepts (spec types, their attribute definitions, those attributes’ datatypes and enum values) with the @reqif annotations the workspace already carries for --source, and emit a JSON mapping whose binding fields are pre-filled where the workspace already claims the ReqIF identity and null where it does not. Writes to stdout unless -o names a file.

• link apply <mapping.json> — write, move, or remove @reqif annotations on your own ontology elements so they carry the identities the edited mapping assigns. All-or-nothing: every problem is reported together and nothing is written unless the whole mapping is clean. The JSON is ephemeral — regenerate it with link scaffold whenever needed; the annotations are the durable record.

• export — convert the SysMLv2 models from the workspace into a .reqif or .reqifz file. --source selects which ReqIF exchange to export when elements carry one annotation per exchange partner.

• check reqif <file> — validate that a ReqIF file satisfies the invariants required for round-trippable conversion (relation-group ownership, no hierarchy cycles, no name shadowing, etc.).

• check sysml — validate the workspace SysMLv2 model (currently enforces at most one top-level package per .sysml document, and that all ReqIF tags are locked).

Each subcommand exits 0 on success and raises on failure.

Library usage (deprecated)

Deprecated since version next: major version Every name exported from this module will be removed in the next major version of Syside; the ReqIF functionality will only be reachable through the syside reqif CLI. Reading any of these names emits a DeprecationWarning.

Every CLI subcommand has a public Python counterpart: an options dataclass plus a function named after the subcommand. The functions return the CLI exit code and raise ValueError on validation failures, and operate on the current working directory (use os.chdir to target a different workspace).

from pathlib import Path

from syside.reqif import (
    ImportOptions,
    CheckReqifOptions,
    InitOptions,
    check_reqif,
    import_,
    init,
)

# Initialise the workspace once.
init(InitOptions(lib_dir=None))

# Validate a ReqIF file before importing it.
reqif_file = Path("requirements.reqif")
check_reqif(CheckReqifOptions(file=reqif_file))

# Import the file; attachments land in ./attachments_reqif/.
import_(ImportOptions(file=reqif_file, attachments_dir=None))

The default-path constants (LIBRARY_PKG, LIBRARY_DIR, ATTACHMENTS_DIR) are re-exported here so callers can reference the same defaults the CLI uses without reaching into private modules.

Index

Attributes ¶

DEPRECATION_MESSAGE

R

Text of the DeprecationWarning every public name here raises.

---

Attributes

DEPRECATION_MESSAGE = 'This method/class/attribute will be removed in the next major version of Syside. Please use `syside ...'

Text of the DeprecationWarning every public name here raises.