feat(organisations): project the organisation as an object so a $ref can reach it

[rubenvdlinde]

Why

Several apps grew their own organization schema, and measuring one showed why.

publication.organization and catalog.organization are declared as {"type": "string", "format": "uuid", "$ref": "organization"}. A $ref resolves against a schema, and OpenRegister's Organisation is an entity with no object projection — so there was nothing for that reference to point at, and each app declared its own copy instead.

A schema slug is global per organisation (SchemaMapper::find() matches LOWER(slug) across every app and returns the first row it reaches), so those copies collide. organization is claimed by both opencatalogi and stackiq today.

Adding the identity columns to Organisation made reuse possible at the entity level, and openregister:organisations:adopt (#3340) moves the rows. Neither gives a leaf schema something to reference. This is the missing piece.

Not a new mechanism

OpenRegister already projects nc-user and nc-group exactly this way — and nc-group is even mapped to schema:Organization. OrganisationObjectSourceProvider follows GroupObjectSourceProvider line for line: the same read-only contract, the same acting-user scoping, the same "absent and denied are indistinguishable" rule.

The schema is nc--prefixed for the reason the semantic map already gives for its app-gated rows: it must not collide with the leaf-app organization schemas it exists to replace, which have to keep working until each app has migrated off them.

Three deliberate limits

• Read-only. The authoritative record is the Organisation row. A write path here would be a second way to mutate a tenant, reachable through the object API and bypassing OrganisationService's lifecycle.
• The identity facet only. Quota, users, groups and authorization are tenancy administration. This schema exists so another record can reference an organisation, not so anyone can configure one through the object API.
• Scoped, and not an enumeration oracle. An organisation is the tenant boundary. Admin sees all; anyone else sees only theirs; absent and denied both return null; anonymous sees nothing.

A merged-away organisation is not listed — it owns nothing, and offering it invites a reference to an unusable target. find() still resolves through a merge, so a reference stored before one keeps working.

A defect the tests caught and reading did not

project() was first written with method_exists($organisation, 'getName') before calling the getter. Organisation's accessors are magic (Entity::__call), so method_exists is false for every one of them — the projection would have shipped carrying nothing but an id. A schema that resolves, returns objects, and is empty.

Verification

Live, on a throwaway instance:

Check	Result
GET /api/objects/{directory}/{nc-organisation} as admin	returns the organisation with its identity facet
the same call unauthenticated	total: 0 — not an error, not a row
find by uuid	returns the organisation
seeding on a clean row	creates the schema with its properties and links it to the directory register

10 unit tests pin the projected set, the omissions (quota/users/groups/authorization), the merge exclusion, search, and the anonymous case. A script asserts the provider's projected list and the seeder's declared properties agree, rather than eyeballing it — a property declared and not projected reads as permanently empty, and one projected and not declared is discarded by the store without a word.

Full-tree phpstan clean. phpcs 0 errors, phpmd clean. tests/Unit/Service/ObjectSource: 115 tests green.

One thing worth knowing

ensureSchema() reuses an existing schema and never updates it, by design. A property added to SCHEMA_PROPERTIES therefore does not reach an instance that already seeded that schema — verified by deleting the row and re-running the repair step. Any future property change to a virtual schema needs its own migration. Recorded in the change's tasks.

What this unblocks

opencatalogi can now repoint publication.organization / catalog.organization at nc-organisation and retire its own copy. Stackiq can follow, once the nine properties Organisation has no column for get a home.

🤖 Generated with Claude Code