Declare relationship definitions
POST /api/v1/ontology/relationships: request fields and declared response contract.
POST/api/v1/ontology/relationships
| Permission | ontology.declareRelationship |
|---|---|
| Workspace scope | required |
| Scope target | workspace |
Request body
| Field | Type | Required | Nullable | Default |
|---|---|---|---|---|
| definition | object | required | non-null | — |
| definition.relationshipId | string | required | non-null | — |
| definition.edgeKind | string | required | non-null | — |
| definition.displayName | string | required | non-null | — |
| definition.description | string | optional | non-null | — |
| definition.source | object | required | non-null | — |
| definition.source.selector | unknown | required | non-null | — |
| definition.source.role | string | required | non-null | — |
| definition.source.label | string | required | non-null | — |
| definition.source.cardinality | "one" | "many" | required | non-null | — |
| definition.target | object | required | non-null | — |
| definition.target.selector | unknown | required | non-null | — |
| definition.target.role | string | required | non-null | — |
| definition.target.label | string | required | non-null | — |
| definition.target.cardinality | "one" | "many" | required | non-null | — |
| definition.directed | boolean | required | non-null | — |
| definition.propertyContract | object | required | non-null | — |
| definition.propertyContract.schemaVersion | integer | required | non-null | — |
| definition.propertyContract.properties | array | required | non-null | — |
| definition.mutation | object | required | non-null | — |
| definition.mutation.writePolicy | "createOnly" | "upsert" | "accumulate" | required | non-null | — |
| definition.mutation.duplicateIdentity | "endpoints" | "endpointsAndKey" | required | non-null | — |
| definition.mutation.requiresIdempotencyKey | boolean | required | non-null | — |
| definition.mutation.deleteBehavior | "hardDelete" | "tombstone" | "forbidden" | required | non-null | — |
| definition.authority | object | required | non-null | — |
| definition.authority.authors | array | required | non-null | — |
| definition.authority.externalSystemRef | string | optional | non-null | — |
| definition.authority.requiresReconciliation | boolean | required | non-null | — |
| definition.authority.requiresSourceRefs | boolean | required | non-null | — |
| definition.projection | object | required | non-null | — |
| definition.projection.search | boolean | required | non-null | — |
| definition.projection.graph | boolean | required | non-null | — |
| definition.projection.freshnessObjectiveSeconds | integer | required | non-null | — |
| definition.scoring | object | optional | non-null | — |
| definition.scoring.baseWeight | number | required | non-null | — |
| definition.scoring.dailyDecay | number | required | non-null | — |
| expectedVersion | integer | optional | non-null | — |
| acknowledgeBreakingChange | boolean | optional | non-null | — |
Response
201
| Field | Type | Required | Nullable | Default |
|---|---|---|---|---|
| data | unknown | required | non-null | — |
Declared failures
| ONTOLOGY_DECLARE_RELATIONSHIP_FAILED | 400 — not retryable |
|---|
Readback
Read the result back with:
- ontology.getRelationshipDefinition
Request example
Schematic only. Replace placeholders with real values and include all required nested fields.
POST /api/v1/ontology/relationships HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json
{
"definition": {}
}