Skip to content

se-df

SE-DF (Structural Explainability Domain Formalization) is a toolkit for building executable domain specifications.

Rather than treating schemas, controlled vocabularies, documentation, generated code, diagnostics, and formal artifacts as independent projects, SE-DF derives them from a single authoritative domain model.

A domain specification becomes an executable asset.

Purpose

Many domains use a common engineering process:

  • define concepts
  • establish terminology
  • separate controlled vocabularies from structural models
  • generate language bindings
  • validate specifications
  • produce documentation
  • generate diagnostics
  • compare independent implementations
  • produce conformance evidence
  • connect to formal verification

SE-DF provides the reusable infrastructure. Individual domains provide the domain knowledge.

Foundations

  • schema-governed
  • versioned
  • URI-identified
  • hierarchical
  • mapped
  • governed
  • lifecycle-aware
  • data-driven

CEP vocabulary model

See https://github.com/civic-interconnect/civic-interconnect

  • native multilingual lexicalization
  • stable non-host-bound identities
  • explicit release versus concept identity
  • polyhierarchical relations
  • complete lifecycle transitions
  • open/closed value domains
  • typed resolution graph
  • Python/Rust/Lean/schema projections

Philosophy

SE-DF follows a generator-first architecture.

The author maintains a single authoritative domain specification and related documents are derived.

Domain Specification
        ↓
Schemas
        ↓
Language Bindings
        ↓
Diagnostics
        ↓
Documentation
        ↓
Conformance Artifacts
        ↓
Formal Obligations

Typical Workflow

uvx se-df init

uvx se-df validate

uvx se-df generate

uvx se-df translate

uvx se-df compare

uvx se-df check

uvx se-df package

uvx se-df report

uvx se-df run # multi-step

Each command represents a stage of the domain formalization pipeline.

Initial Scope

The first implementation focuses on:

  • concept systems
  • controlled vocabularies
  • structural schemas
  • diagnostics
  • documentation generation
  • Python generation
  • Rust generation
  • conformance artifacts

Additional generators and formal integrations will be added incrementally.

Phase 10 Load

repository files
    ↓
DocumentLoaded
    ↓
LoadResult

Phase 20 Resolve

For each vocabulary document, p20 must resolve:

vocabulary schema reference vocabulary release identity previous/superseded release reference term identities broader/parent term references replacement references mapping source-term references external target identifiers

p20_resolve

LoadResult
    ↓
classify documents by declaration profile
    ↓
extract vocabulary releases and other declaration families
    ↓
normalize identifiers and language tags
    ↓
resolve internal references
    ├── hierarchy references
    ├── replacement references
    ├── value-domain references
    └── mapping source references
    ↓
retain external references as resolved-external or unresolved-external
    ↓
construct typed resolved model
    ↓
compute deterministic dependency order
    ↓
ResolveResult

Resolution needs to answer these questions:

  1. What structural role does each loaded document have?
  2. Which documents define declaration profiles?
  3. Which documents contain authoritative declarations?
  4. Which profile governs each declaration?
  5. Which declaration-level dependencies arise from resolved references?
  6. What topological order covers every declaration exactly once?