Register import workflow: auto-create register from JSON or fail clearly

[rubenvdlinde]

Background

Scholiq just shipped 5 wedge specs (scholiq #30-#34, see scholiq#35). The app's seed file lib/Settings/scholiq_register.json follows the same OpenAPI-with-x-openregister format as decidesk's decidesk_register.json — 9 schemas with full x-openregister-lifecycle/-calculations/-notifications/-aggregations declarations.

Problem

There is no clean app-bootstrap path. We tried:

1. POST /api/configurations/import with {json: ...} body → returns HTTP 200 "Import successful" but only 1-2 of 9 schemas land in the DB. No register row is created. No errors or warnings in the response.
2. POST /api/registers/{id}/import (multipart upload) → "importFromJson must be called with a Configuration entity. Direct imports without a Configuration are not allowed."
3. POST /api/configurations/{id}/import after creating a Configuration → HTTP 500 (login redirect HTML).

What we expect

Two viable patterns, in priority order:

Option A (preferred) — Auto-bootstrap

A single endpoint that takes the register JSON file and creates all of: Register row (from info.title + x-openregister.app), Schemas, and links between them.

POST /api/registers/install with file body:

• Reads info.title, info.description, x-openregister.app
• Creates the Register row if it doesn't exist
• Iterates components.schemas.* and creates each schema linked to the register
• Returns the full count of registers + schemas created
• Idempotent: if a schema with the same slug already exists, update it (respecting version comparison)

Option B — Make Configuration the canonical bootstrap

If Configuration entities are the only legitimate import path, then:

• Document this prominently in the OR README
• Have decidesk (and other in-fleet apps) use this pattern as the working example
• Fix the 500 error on POST /api/configurations/{id}/import
• Provide an occ command: occ openregister:register:install /path/to/register.json

Why this matters

Without a working bootstrap, every new app needs N manual API calls to create N schemas, which:

• Doesn't scale beyond demos
• Breaks the "app install → register auto-registers" promise in ADR-022
• Forces apps to ship custom RegisterInstaller PHP per app

Scholiq #35 tracks the app-side. This OR issue is the foundation side.

Acceptance

• One documented path to install a register from JSON
• Working example in decidesk (and/or scholiq) repair-step
• Integration test in OR that imports a 5+ schema register and asserts both register + all schemas exist
• Existing import endpoints either work as expected or return clear errors