MauroImportExport 1.0.0.891

MauroImportExport Module

Overview

The MauroImportExport module provides a pluggable import / export framework with:

• Discoverable handlers (exporters & importers) catalogued via IModelTransferRegistry.
• Declarative parameter definitions (TransferParameterDefinition) supporting Boolean, Choice, and String types.
• A per‑execution ambient context (TransferExecutionContext) allowing handlers to access parameter values through TransferParameterReader without changing existing method signatures.
• Multi‑file export support (IMultiFileExporter) with UI integration for folder vs zip destination.
• Deterministic ordering for JSON + Mermaid outputs to stabilise hashing / test assertions.

Key Types

Handler Discovery & Registration

Handlers are manually registered in ModelTransferRegistryFactory.CreateDefault(). Future Phase 3 work intends attribute based discovery, e.g.

[ModelTransferExporter("my-format")] // future idea
public sealed class MyCustomExporter : IModelExporter, ITransferParameterProvider { ... }

Adding a New Exporter / Importer

1. Implement IModelExporter or IModelImporter (optionally ITransferParameterProvider, IPluginVersioned).
2. Provide semantic version in PluginVersion (MAJOR.MINOR.PATCH) – align with resource key or behaviour surface changes.
3. (Optional) Expose parameters:

public IReadOnlyCollection<TransferParameterDefinition> GetParameterDefinitions() => new []
{
    new TransferParameterDefinition(
        Key: "my.flag",
        Type: TransferParameterType.Boolean,
        Prompt: "myexporter.flag.prompt", // localisation key
        Description: "Enable special flag",
        DefaultValue: true,
        Choices: null)
};

4. Register in factory:

registry.Register(new MyCustomExporter());

5. Add localisation entries for Prompt key(s).

Parameter Semantics

• Boolean: coerces from bool or "true"/"false" strings.
• Choice: validated (case‑insensitive) against declared Choices; falls back to default on invalid input.
• String: trimmed; empty replaced with default unless AllowEmpty = true.
• Required: throws if missing (or empty when not allowed).

Ambient Execution

At the start of an export/import the UI (or executor) builds a TransferParameterValues instance and pushes it:

using (TransferExecutionContext.Push(values))
{
    await exporter.ExportAsync(model, progress, token);
}

Inside the handler:

bool includeMeta = TransferParameterReader.GetBoolean("includeMetadata", true);
string ordering = TransferParameterReader.GetString("dataTypeOrdering", "Id");

Multi‑File Export

IMultiFileExporter returns a collection of artefacts (file name + bytes). The UI offers:

• Folder output (writes each artefact preserving sub‑paths)
• Zip output (single archive)

Existing multi‑file handlers: svg-diagrams (SVG diagrams), mmd (Mermaid single artefact list path).

UI Integration (TransferParametersPage)

• Radio buttons choose Import vs Export (Export disabled until a model is loaded).
• Picker lists handlers with friendly DisplayName and shows Description.
• Parameter controls are generated by type (Switch / Picker / Entry).
• Previously used parameter values are persisted per (direction + format + key): transfer.params.{export|import}.{format}.{paramKey}.
• Last successful import format remembered (transfer.lastimport.format).
• Execution shows progress bar + detail; cancellation supported.

JSON Export Determinism

Ordering enforced:

• Classes by id ascending.
• Data elements within class by id.
• Data types extracted along traversal then ordered by Id or Label based on parameter. This stabilises content for hashing / diffing.

Display Names / Descriptions

Descriptor fields (examples):

Persistence Key Patterns

• Parameters: transfer.params.{direction}.{format}.{param}
• Last Import Format: transfer.lastimport.format
• (Planned) Last Export Folder: transfer.lastpath.export.{format}

Versioning Guidance

• Increment MAJOR for breaking schema / contract changes (e.g. JSON structure changes).
• Increment MINOR when adding new parameters (backwards compatible).
• Increment PATCH for internal fixes / ordering / localisation additions.

Format-Specific Documentation

Detailed documentation for individual import/export formats:

• OAS (OpenAPI Specification) - Import OpenAPI 3.0/3.1 API specifications with comprehensive mapping strategies
• JSON Schema - Advanced JSON Schema import with multi-draft support
• DITA - DITA 1.3 topic and DITAMAP export for technical documentation

Roadmap (Abbrev)

• Accessibility semantics (screen reader friendly descriptions combining prompt+value).
• Test suite: validation, cancellation, deterministic hashing.
• Round‑trip model smoke tests (JSON, SKOS, XMI, RDFS).
• Attribute based discovery prototype.
• Visual parameter deviation indicators + quick reset.

Contributing

Ensure any new handler:

• Supplies semantic version.
• Provides stable ordering when output ordering affects diffability.
• Adds localisation keys for prompts.
• Includes basic test coverage (future test suite scaffolding forthcoming).

© 2025 Oughitbridge Limited.