Embedded Java API

The public integration boundary of Model Forge is the embedded Java facade and the contract records published as Maven artifacts.

Facade

Host applications should inject the public facade:

import de.civitascore.modelforge.facade.ModelForge;
import org.springframework.stereotype.Service;

@Service
class ImportWorkflow {
    private final ModelForge modelForge;

    ImportWorkflow(ModelForge modelForge) {
        this.modelForge = modelForge;
    }
}

The facade returns domain results and raises domain exceptions. It does not use HTTP response types, servlet APIs, HAL links or OpenAPI-specific models.

JSON payloads on the facade are Jackson 3 (tools.jackson.databind.JsonNode) — the same stack a Spring Boot 4 host auto-configures, so host code passes its trees through without any bridging.

Artifact Identity

Model Forge mints every URN whose name it derives: the readable name segment plus a short disambiguator segment (10 base36 chars), so equal display names never collide onto the same logical URN (see URN Format). The protocol is two-phase:

• Create: importSchema (Elements, splits $defs) or createArtifact (Mapping, Pipeline, DataSource, DataSink, DataSet, DataStructure) take a name, mint the URN and return the versioned pin. createArtifact always mints — a caller id in the content is ignored; only importSchema keeps an explicit real CORE-URN $id.
• Update: store the returned (logical) URN and pass it back — importSchema with the URN as the root $id, or saveArtifact with the URN as the artifactId. Versions are always assigned by Model Forge.

Every write result also carries the artifact's dependency lists — outgoing references grouped by the stored reference type (mapping-source, pipeline-node, dataset-ref, schema-ref, …) in document order, read back from the registry after the write. Hosts can mirror these lists into their own persistence; they are recomputed on every save.

Facade methods

The complete public surface — 25 methods on de.civitascore.modelforge.facade.ModelForge:

Writes

Method	Purpose
ImportResult importSchema(ImportSchemaCommand)	Import a JSON Schema as an Element. Splits $defs into separate Elements, mints URNs and creates a DataStructure grouping. Composition into a DataSet is the caller's job (via saveArtifact).
ArtifactWriteResult createArtifact(CreateArtifactCommand)	First store of a Mapping, Pipeline, DataSource, DataSink, DataSet or DataStructure — mints the URN from the name, stamps it into id, returns the versioned pin. Elements are rejected (use importSchema).
ArtifactWriteResult saveArtifact(SaveArtifactCommand)	Follow-up version of an existing artifact by its logical URN, with a VersionBump (PATCH/MINOR/MAJOR).
void deleteArtifact(ArtifactId)	Deletes the artifact (all versions) behind a logical URN. Throws ArtifactInUseException while any other artifact still references it — every reference type blocks (a container is deletable, but its referenced members are protected; only self-references are exempt).
void deleteArtifact(ArtifactId, boolean cascade)	As above, but with cascade=true the target's members (the artifacts it references) are deleted too — each only if, once the container is gone, nothing else still references it. Shared and mutually-referencing members are kept; the cascade recurses into members that become orphaned.
void deleteArtifact(ArtifactId, boolean cascade, boolean force)	With force=true the blocking checks are skipped and the artifact goes, whatever still references it. The platform does not expose this. ModelRegistryGateway always passes force=false, and its own deleteArtifact has no force parameter, so a force delete cannot be triggered through the portal backend.
ArtifactWriteResult bumpVersion(BumpVersionCommand)	A new version without a content change — used when only the version has to move.
void linkToDataSet(ArtifactId dataSet, ArtifactId member)	Adds a reusable artifact to a DataSet manifest, which creates the dataset-ref membership edge.
void unlinkFromDataSet(ArtifactId dataSet, ArtifactId member)	Removes that membership again.

Reads and views

Method	Purpose
Optional<ArtifactView> getArtifact(ArtifactId)	The raw stored document of any artifact (exact version, logical or :latest URN).
Optional<ArtifactView> getBundledView(SchemaViewQuery)	Bundled view — all transitive dependencies embedded under $defs.
Optional<ArtifactView> getInlinedView(SchemaViewQuery)	Inlined view — every CORE-URN $ref recursively inlined.
Set<ArtifactId> existing(Collection<ArtifactId>)	Of the given artifacts, the ones the registry holds. One call instead of one read per candidate.

Validation

Method	Purpose
ValidationResult validateSchema(ValidateSchemaCommand)	Validates a document against the JSON Schema 2020-12 meta-schema (dry run, no write).
ValidationResult validateInstance(ValidateInstanceCommand)	Validates an instance document against a schema.

Dependency graph

Method	Purpose
DependencyGraphView dependencies(DependencyQuery)	Direct dependencies of an artifact (version-precise).
DependencyGraphView dependents(DependencyQuery)	Direct dependents of an artifact.
DependencyGraphView mapsTo(DependencyQuery)	Mappings in which the Element is the source.
DependencyGraphView mappedFrom(DependencyQuery)	Mappings in which the Element is the target.
DependencyClosureView closure(DependencyQuery)	The transitive closure of an artifact's dependencies, not only the direct ones.

Search and standards import

Method	Purpose
List<ArtifactSummary> search(ArtifactSearchQuery)	Cross-artifact metadata search (type, name, title, free text).
ImportResult importFromSmartDataModels(ImportSmartDataModelCommand)	Imports a FIWARE Smart Data Model identified by a (subject, dataModel) pair; Model Forge builds the catalogue URL and fetches it with an SSRF-guarded fetcher.
List<XRepositoryHit> searchXRepository(XRepositorySearchQuery)	Searches the xRepository (xOEV) catalog.
ImportResult importFromXRepository(ImportXRepositoryCommand)	Downloads an XSD from xRepository and imports it — converted to JSON Schema Elements or stored as a raw XSD Element.

Housekeeping

Method	Purpose
List<String> deletionBlockers(ArtifactId)	Why a delete is refused: the artifacts that still reference this one. Ask before deleting, to give the user a reason instead of an exception.
List<ArtifactSummary> orphans(ArtifactKind)	Artifacts of that kind which belong to no DataSet — no dataset-ref in-edge.
List<NonConformingArtifact> nonConformingElements()	Elements that do not satisfy the contract of their kind.

Artifact lifecycle and status are entirely the host application's concern; Model Forge stores immutable versions and keeps no lifecycle state.

Starter Dependency

The artifacts are published to the CIVITAS/CORE platform GitLab Maven registry. Host applications add it as an additional repository:

<repositories>
  <repository>
    <id>model-forge</id>
    <url>https://gitlab.com/api/v4/projects/72402288/packages/maven</url>
  </repository>
</repositories>

<dependency>
  <groupId>de.civitascore</groupId>
  <artifactId>core-model-forge-spring-boot-starter</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

The starter wires the facade, application use cases, ports and PostgreSQL adapter into the host Spring Boot application. CI access needs the consuming project on the Model-Forge project's job-token allowlist; local builds use a deploy/personal token in settings.xml.

Contract Dependency

Use the contract artifact directly when only public records and URN utilities are needed:

<dependency>
  <groupId>de.civitascore</groupId>
  <artifactId>core-model-forge-contract</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

Host Responsibility

If Model Forge functionality is exposed over HTTP, that HTTP API belongs to the host application. The host maps its own controllers, security, authorization, error responses and request limits to embedded Model Forge calls.