Skip to content

Profile Loading Architecture

Implementation Status

This page documents implemented and architecturally committed behavior for profile loading in GKC and SpiritSafe-backed sources.

Contract note:

  • The active runtime profile contract is JSON Entity Profiles materialized from DD Wikibase semantics into SpiritSafe artifacts.
  • YAML-era profile loading compatibility is legacy-only migration support and is not a forward architecture target.

Resolution Model

GKC resolves a profile reference through resolve_profile_path() using the canonical artifact layout:

  • QID (for example Q4) → profiles/QID.json
  • Full entity URI (for example https://datadistillery.wikibase.cloud/entity/Q4) → normalized to profiles/Q4.json
  • Explicit .json profile paths are preserved as provided.

Compatibility behavior for legacy YAML-era layouts remains migration-only and should not be used for new integrations.

Source Modes

Profile loading is source-configured through SpiritSafeSourceConfig:

  • mode: github (default)
  • mode: local

In GitHub mode, SpiritSafe-relative paths resolve to raw GitHub URLs. In local mode, paths resolve against local_root.

Query Reference Resolution

Hydration resolves query_ref deterministically with resolve_query_ref():

  1. Profile-relative first (for registrant layout).
  2. Root-relative fallback.

For registrant profiles, queries/foo.sparql is attempted first as:

  • profiles/<Profile>/queries/foo.sparql

then as:

  • queries/foo.sparql

Failure Behavior

  • Missing profile files raise path resolution errors after fallback attempts.
  • Missing query files raise FileNotFoundError with attempted paths.
  • Hydration can either collect failures or fail fast based on fail_on_query_error.

Explicit Non-Goals

  • Introducing new runtime dependencies on YAML profile loaders, YAML profile validators, or YAML form schema generators.
  • Preserving legacy module boundaries as compatibility shims when moving wizard runtime code into gkc.wizard.

Theoretical Design Notes

  • Optional pinned-ref contract testing against SpiritSafe testing branches is not yet integrated into default CI behavior.
  • Future profile version selection semantics (for example, explicit version targeting) remain open design work.