Code Map

One entry per class, grouped by module and package — what each piece does and why it exists. (Records used purely as method parameters/results are grouped with their owning concept.)

model-forge-contract

The public API: everything a host application touches. No Spring, web or persistence dependencies.

de.civitascore.modelforge.facade

Class	Capability
ModelForge	The 18-method embedded facade — the single integration boundary for hosts. See the API reference.

de.civitascore.modelforge.contract

Class	Capability
ArtifactId	Identity handle carrying a CORE URN (logical or versioned).
ArtifactKind	The seven artifact kinds (ELEMENT, MAPPING, PIPELINE, DATA_SOURCE, DATA_SINK, DATA_SET, DATA_STRUCTURE). XSD-backed Elements are ELEMENTs with an XSD representation format, not a separate kind.
ImportSchemaCommand / ImportResult	Element import: JSON Schema in, root pin + imported ids + dependency lists out.
CreateArtifactCommand / SaveArtifactCommand / ArtifactWriteResult	First store (mints the URN) and follow-up versions (with VersionBump); the result carries the assigned pin plus dependency lists.
VersionBump	PATCH / MINOR / MAJOR — the caller's change classification; Model Forge assigns the concrete SemVer.
ArtifactView	Raw stored document of an artifact plus its metadata.
SchemaViewQuery	Read query for the bundled / inlined schema views.
ValidateInstanceCommand / ValidationResult / Diagnostic / DiagnosticSeverity	Validation inputs and outputs; a Diagnostic is one finding (severity, message, code, path).
DependencyQuery / DependencyGraphView	Graph queries (dependencies, dependents, mapsTo, mappedFrom) and their node/edge result shape.
ArtifactSearchQuery / ArtifactSummary	Cross-artifact metadata search and its result row.
ImportSmartDataModelCommand / ImportXRepositoryCommand / XRepositorySearchQuery / XRepositoryHit	Standards import: FIWARE Smart Data Models by URL, xRepository search + XSD import.
ModelForgeException	Base of all semantic Model Forge failures.
ArtifactInUseException	Delete protection: thrown when other artifacts still reference the one being deleted; lists the blockers.
RegistryUnavailableException	The registry (PostgreSQL) is unreachable — infrastructure, not caller error.
ValidationFailedException	A write was rejected because validation produced errors.

| BumpVersionCommand | Carries an artifact's current version forward as a new version at a requested change level. | | ValidateSchemaCommand | Validates one JSON Schema document — the schema-only counterpart to ValidateInstanceCommand. | | DependencyClosureView | The transitive dependency closure of an artifact, including the members the registry does not hold. | | NonConformingArtifact | One stored Element whose schema does not conform to JSON Schema 2020-12, with its diagnostics. |

de.civitascore.modelforge.domain

Class	Capability
Formats	Representation format tokens (jsonschema, xsd, …) shared between content and registry.

de.civitascore.modelforge.urn

Class	Capability
UrnParser	Static string-level URN toolbox: parse/validate (8/9 segments), logicalUrn, versionFromUrn, nameFromUrn, disambiguatorFromUrn, sanitize, and deriveDisambiguator (deterministic token). ArtifactId.logicalUrn()/version()/name() delegate here.

model-forge-runtime

The embedded implementation behind the facade. Package slices are enforced by ArchUnit; nothing here is host-facing.

de.civitascore.modelforge.application

Class	Capability
EmbeddedModelForgeOperations	Implements the ModelForge facade — translates contract commands into service calls and results back into contract records.
SchemaImportService	Element import pipeline: validate → normalise $id → split $defs into separate Elements → store with reference edges → create the DataStructure grouping. Also XSD import and SSRF-guarded import-by-URL.
ElementCommandService	Element write side: store JSON Schema / raw XSD versions, and delete with the dependents check (delete protection).
ElementQueryService	Element read side: the raw stored JSON Schema for a URN.
ViewService	Generates the two read projections: inlined view (every $ref inlined) and bundled view (dependency closure under $defs), both cycle-safe.
ReferenceExistenceValidator	Registry-aware check that every concrete x-core-ref foreign-key target exists.
SmartDataModelsService	Imports a FIWARE Smart Data Model schema by URL through the guarded fetcher.
XRepositoryService	xRepository orchestration: search the catalog, download an XSD, convert to JSON Schema Elements or store as raw XSD.
SchemaImportRequest / SchemaImportResult	Internal input/result pair of the JSON Schema import.
XsdImportRequest	Internal input of a raw XSD import, without JSON Schema conversion.
XRepositoryImportCommand / XRepositorySearchPage	Internal xRepository import parameters and search page shape.
UpstreamException	An external system (xRepository, remote schema host) failed or is unreachable.

de.civitascore.modelforge.core.port

Class	Capability
ArtifactRegistry	The storage boundary: store/fetch/list/delete artifacts, reference edges, XSD namespace index, search, delete-blocking dependents. Every write returns the assigned versioned pin.
ArtifactSearchCriteria / ArtifactSearchResult	Search input/output at the port level.
RemoteSchemaRepository	Fetches external JSON Schemas by URL without exposing HTTP details.
XRepositoryCatalog / XRepositoryArtifact / XRepositorySearchResult	xRepository catalog access (search, XSD download) and its result shapes.
XsdSchemaConverter / XsdSchemaConversionException	XSD → JSON Schema conversion boundary.

| ArtifactVersionIdentity | One stored version reduced to what deciding a reference's resolvability needs. |

de.civitascore.modelforge.graph

Class	Capability
DependencyGraphService	Version-precise in-memory dependency graph: forward/reverse edges, rebuilt from the registry at startup, updated on every write; answers dependencies/dependents and the traversals behind the views.
SchemaRefExtractor	Extracts all outgoing CORE-URN $ref values from a JSON Schema document.

de.civitascore.modelforge.urn

Class	Capability
UrnService	Mints new URNs from the configured scope/owner/domain plus a name and a fresh random disambiguator — the only place URNs are minted.

de.civitascore.modelforge.persistence.postgres

Class	Capability
PostgresArtifactRegistryClient	The ArtifactRegistry implementation: transactional JdbcClient writes, SemVer assignment, content-hash idempotency, outage translation to RegistryUnavailableException.
ArtifactRepository / ArtifactRow	artifact table access — one row per logical identity.
ArtifactVersionRepository / ArtifactVersionRow	artifact_version table access — immutable SemVer versions.
ArtifactRepresentationRepository / ArtifactRepresentationRow	artifact_representation table access — the stored content (JSONB or XSD text) per version and format.
ArtifactReferenceRepository / ReferenceRow	artifact_reference table access — the complete typed edge graph (including cycles), late-binding target resolution, the blocking-dependents query.
XsdNamespaceRepository	xsd_namespace index — targetNamespace → URN for xs:import resolution.
ReferenceExtraction	Derives the typed reference rows from an artifact document (schema $refs, mapping source/target, pipeline nodes, manifest ref arrays).
SemVer	Parses/compares SemVer strings and computes the next version for a VersionBump.
RegistryMapping	Registry token constants (artifact types, content types) and group ↔ type mapping.
RegistryTime	Null-safe Instant ↔ OffsetDateTime (UTC) conversions for timestamptz columns.
XsdSchemaSupport	Transparent XSD → JSON Schema conversion on read (cached), namespace extraction, xs:import resolution.

de.civitascore.modelforge.validation

Class	Capability
ModelValidator	JSON Schema 2020-12 meta-schema validation (validateSchema) and instance-against-schema validation (validateData).
CoreSchemaValidator	Opt-in validation of an artifact document against the CORE schema its $schema declares (mapping/pipeline/…); documents without a known $schema pass through unvalidated.
CoreJsonSchemaFactory	networknt factory pre-configured with the CORE x-* extension keywords as non-validating annotations.
SchemaErrors	Maps a networknt validation message to a Diagnostic.
JacksonBridge	Serialise/parse bridge between Jackson 3 (tools.jackson) and the Jackson 2 trees networknt requires.

de.civitascore.modelforge.xsd

Class	Capability
XsdToJsonSchemaConverter	Converts an XSD (Apache XmlSchema) into one JSON Schema per named type, with CORE URN $ids and x-xsd-source back-references.

de.civitascore.modelforge.util

Class	Capability
JsonSchema	Shared JSON Schema constants ($schema dialect URI, …).
NameMatch	Relevance scoring for name/title search.
SecureXsdParser	XSD parsing with layered XXE/SSRF protection.
XmlInputGuard	Rejects DOCTYPE/ENTITY declarations before any XML parsing (the XXE entry points).
XsdDocumentation	Extracts xs:annotation/xs:documentation text.
XsdTypeMapping	Classifies XSD built-in types into the JSON type vocabulary.

de.civitascore.modelforge.integrations

Class	Capability
RemoteSchemaFetcher	RemoteSchemaRepository implementation: HTTPS fetch with UrlGuard validation.
util.UrlGuard	SSRF guard: allow-listed schemes/hosts, blocks private address ranges.
RemoteRefResolver	Replaces the http(s) $refs of a fetched document with the schemas they point at.
VendoredSchemaLoader	Resolves the third-party schema documents that ship on the classpath, so a reference to one needs no network call.
xrepository.XRepositoryClient	XRepositoryCatalog implementation against the public xRepository REST API.

model-forge-spring-boot-starter

Class	Capability
ModelForgeAutoConfiguration	Wires the whole runtime into a host context: all beans explicitly created and modelForge*-prefixed, ordered after Flyway/JdbcClient/Jackson; runs Model Forge's own Flyway migration in the model_forge schema.
ModelForgeProperties	Typed model-forge.* configuration (URN scope/owner/domain, registry schema and migration table).

model-forge-admin-ui

Internal developer tool (own Spring Boot + Wicket app); consumes the library through the facade like any host. Always runs against a real Postgres registry (docker compose up -d in the module starts one).

Class	Capability
AdminUiApplication	Spring Boot entry point.
wicket.AdminWicketApplication / wicket.WicketConfig	Wicket setup and page mounting.
wicket.BasePage	Shared layout/navigation.
wicket.components.CodeEditorPanel	CodeMirror-based JSON editor component.
pages.ArtifactListPage	Search/browse all artifacts.
pages.ArtifactViewPage / pages.ArtifactEditPage	Inspect a stored artifact; edit and save a new version.
pages.SchemaViewComparisonPage	Raw vs. bundled vs. inlined view side by side.
pages.GraphPage	vis-network rendering of the dependency graph.
pages.ImportPage / pages.ValidatePage	Import a JSON Schema; dry-run validation.
pages.SmartDataModelImportPage / pages.XRepositoryImportPage	Standards import front-ends.
wicket.tree.ArtifactTree / wicket.tree.ArtifactTreeProvider / wicket.tree.ArtifactTreeNode / wicket.tree.ArtifactTreeNodePanel	Wicket tree view of artifacts and their dependency structure.
ArtifactTypeCatalog	The canonical artifact-type tokens as ModelForge.search stores and returns them.
SchemaCatalog	Picks the JSON Schema that drives editor autocomplete and validation for an artifact.
pages.SeedPage	Imports whole bundled example model sets, discovered on the classpath.
seed.StaSeedConfiguration / seed.SeedImporter / seed.SeedBundle	Optional startup seeding of example STA Elements through the facade, gated by model-forge.admin-ui.seed.enabled (default on) and idempotent — an Element whose logical URN already resolves is skipped.