Jebi.Rest 1.1.0

Jebi

Jebi is a .NET library that maps JSON data onto a relational database, applying configurable transformation rules to bridge structural differences between source JSON and the target EF Core model.

Architecture

Jebi is split into two distinct layers.

Server (hosted service)

A single combined REST server exposes both the Catalog and Ingestion Plan surfaces.

• Project: apps/Servers/Jebi.Catalog.IngestionPlan.Server.Rest
• Role: Production server for Catalog + Plan REST API

Endpoints:

• api/source/* for JSON schema management
• api/target/* for EF Core DbContext metadata
• api/bindings/* for binding configurations and transformation rules
• api/plan/* for ingestion plan setup and key correlations

Client (NuGet package)

• Package: Jebi.Rest
• Description: Published NuGet package wiring IJebiService against the remote server plus local execution engine

How It Works

Consumer App
  └── IJebiService          (from Jebi.Rest package)
        ├── Catalog calls  ──→ HTTP  → Jebi Server (api/source, api/target, api/bindings)
        ├── Plan calls     ──→ HTTP  → Jebi Server (api/plan)
        └── Execute        ──→ local → JebiIngestionDb + consumer's target DbContext(s)

The server holds all metadata (schemas, target models, binding rules, plans). Execution runs client-side against the consumer's own databases.

Infrastructure Projects

• src/Catalog/Jebi.Catalog.Infrastructure: catalog persistence (source/target/binding)
• src/Ingestion/Jebi.Ingestion.Plan.Infrastructure: plan persistence (setup/key correlations/run results)
• src/Ingestion/Jebi.Ingestion.Execute.Infrastructure: runtime execution (EF provider/target integration)
• src/Shared/Jebi.Shared.Infrastructure: shared EF base components

The server requires two connection strings:

"ConnectionStrings": {
  "JebiCatalogDb": "...",
  "JebiPlanDb": "..."
}

Jebi Registration

REST (production)

builder.Services.AddJebiRest(
    jebiIngestionConnectionString: "Data Source=jebi-execute.db",
    jebiSection: builder.Configuration.GetSection("Jebi"),
    ensureTargetDatabases: true,
    typeof(MyTargetDbContext));

Jebi supports:

• ServerBaseUrl (optional, preferred)
• Endpoints:RestBaseUrl (optional, alternative)
• Auth:ClientId (required)
• Auth:ClientSecret (required)
• Auth:Scope (optional, default jebi.api)
• Auth:TokenEndpoint (optional in REST, default ${resolvedServerBaseUrl}/oauth2/token)

Local (development/testing)

builder.Services.AddJebiLocal(
    jebiCatalogConnectionString: "Data Source=catalog.db",
    jebiIngestionConnectionString: "Data Source=plan.db",
    ensureTargetDatabases: true,
    typeof(MyTargetDbContext));

gRPC (production)

builder.Services.AddJebiGrpc(
    catalogGrpcAddress: "https://catalog.example.com",
    planGrpcAddress: "https://plan.example.com",
    jebiIngestionConnectionString: "Data Source=jebi-execute.db",
    authSection: builder.Configuration.GetSection("Jebi:Auth"),
    ensureTargetDatabases: true,
    typeof(MyTargetDbContext));

For gRPC, TokenEndpoint must be configured explicitly in Jebi:Auth:TokenEndpoint.

For production deployment templates and endpoint matrix, see docs/deployment/endpoints-and-config.md.

Subject-Scoped Persistence (Forward-Compatible)

Catalog and Plan persist a nullable shadow property SubjectId on tenant-scoped entities, populated on write when claim sub is available.

• TenantId filter remains always active.
• SubjectId filter is auto-enabled when a subject is available (override with EnableSubjectFilter).
• Server tenancy can enforce subject presence for API/gRPC requests via Jebi:Tenancy:RequireSubjectForApiRequests=true.
• Schema updates are non-destructive: add SubjectId column plus (TenantId, SubjectId) index.
• Records with SubjectId = null remain shared within the tenant.
• Architectural decision is formalized in docs/adr/0001-subject-filter-auto-enable.md.

Facade Usage

var jebi = serviceProvider.GetRequiredService<IJebiService>();

var binding = await jebi.CreateBindingConfigurationAsync(new JebiCreateBindingConfigurationRequestDto
{
    SourceSchemaName = "CustomerSchema",
    TargetContextName = "MyTargetDbContext",
    Name = "CustomerBinding"
});

await jebi.AddPropertyBindingRuleAsync(new JebiAddPropertyBindingRuleRequestDto
{
    BindingConfigurationId = binding.BindingConfigurationId,
    SourcePropertyName = "CustomerDef.customerId",
    TargetPropertyFullyQualifiedName = "MyApp.Customer.CustomerId"
});

var result = await jebi.RunFromBindingAsync(new JebiRunFromBindingRequestDto
{
    BindingConfigurationName = "CustomerBinding",
    JsonPayload = jsonPayload,
    Options = new JebiIngestionOptionsDto
    {
        ValidateSchema = true,
        PersistRequested = true
    }
});

Solution Filters

Work on a focused subset of the solution using the available filters:

dotnet build Jebi.Catalog.slnf
dotnet build Jebi.Ingestion.slnf
dotnet build Jebi.Packages.slnf
dotnet build Jebi.AppHost.slnf

Architecture Boundaries

Check project boundary rules:

bash scripts/ci/check-project-boundaries.sh

Validates that:

• consumer apps have DisableTransitiveProjectReferences=true
• Jebi surface packages do not expose internal projects as compile dependencies

Also enforced in CI via the Architecture Boundaries workflow.

Docker

Pull and run the combined Catalog+Plan REST server:

docker pull ghcr.io/boffoli/jebi-catalog-ingestionplan-server-rest:latest
docker run -d -p 8080:8080 ghcr.io/boffoli/jebi-catalog-ingestionplan-server-rest:latest

Pull and run the web package demo (consumes Jebi.Rest as NuGet):

docker pull ghcr.io/boffoli/jebi-web-package:latest
docker run -d -p 8081:8080 ghcr.io/boffoli/jebi-web-package:latest

See docs/docker-demo-launchers.md for ready-to-use launcher scripts.