AISA v2.0 / Technical documentation / connector-capability.schema.json
connector-capability.schema.json
JSON · 363 lines · 8,920 bytes · wiki path 10 Architecture/contracts/connector-capability.schema.json · download the raw file · cited from Contracts · Gating · Decision register
Same folder: Connectors.Abstractions.cs · configuration-change.schema.json · configuration-input.schema.json · eval-set.schema.json · execution-obligations.schema.json · ledger-record.schema.json · message-envelope.schema.json · model-turn.schema.json · module-manifest.schema.json · openapi.yaml · platform-profiles.json · realtime-events.schema.json · runtime-state.schema.json · tool-package.schema.json · validate_case_journeys.py · validate_contracts.py · validate_runtime_contracts.py · validate_tool_packages.py · write-shape.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://aisa.ablera.com/contracts/connector-capability.schema.json",
"title": "Connector capability description (platform seam 2 of 5)",
"description": "Failure and Recovery § 4 (D66): every connector operation is a versioned CONNECTOR_SCOPES row of kind 'operation'; its absence fails closed. An agent discovers which operations exist and what evidence they return; an unknown operation is a capability gap to escalate, never a reason to improvise. Reach rows (kind 'reach') describe how a target is reached — direct only (D132).",
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"connector",
"environment",
"system",
"version",
"target_identity",
"modes"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"reach",
"operation",
"ceiling"
]
},
"connector": {
"type": "string",
"minLength": 1,
"description": "Registered connector key; customer capability data, not a hard-coded estate list."
},
"customer_code": {
"type": "string"
},
"environment": {
"type": "string",
"description": "PROD · STAGING · QA · DEV — a real credential boundary (Trust and Data § 2)"
},
"system": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 1
},
"operation_id": {
"type": "string",
"pattern": "^[a-z][a-z0-9_.\\-]+$",
"description": "e.g. oracle-ipal.select, oracle-ipal.write_a, oracle-ipal.write_b, oracle-ipal.plsql_snapshot, abacus-gateway.get_rates, gitlab.open_merge_request"
},
"input_contract": {
"type": "object",
"description": "JSON Schema of the operation's input; the runtime validates before the call"
},
"target_identity": {
"type": "object",
"additionalProperties": true,
"properties": {
"host": {
"type": "string"
},
"port": {
"type": "integer"
},
"service": {
"type": "string"
},
"paths": {
"type": "array",
"items": {
"type": "string"
}
},
"schema": {
"type": "string"
},
"objects": {
"type": "array",
"items": {
"type": "string"
}
},
"project": {
"type": "string"
},
"queue": {
"type": "string"
},
"mailbox": {
"type": "string"
}
}
},
"effect_class": {
"type": "string",
"enum": [
"read",
"transactional",
"compensable",
"irreversible",
"ddl"
]
},
"authorization": {
"type": "string",
"enum": [
"read_grant",
"write_grant",
"gate"
]
},
"idempotency_key_shape": {
"type": "string",
"description": "how a repeat of the same call is recognised, e.g. 'case_id+step_id+statement_hash'"
},
"timeout_ms": {
"type": "integer",
"minimum": 1
},
"effect_of_timeout": {
"type": "string",
"enum": [
"none",
"unknown",
"applied"
],
"description": "what a timeout means for the target: none (nothing happened), unknown (reconcile first), applied (the effect is there)"
},
"recovery": {
"type": "string",
"enum": [
"retryable",
"reconcile_first",
"never_retry"
]
},
"evidence_returned": {
"type": "array",
"items": {
"type": "string"
},
"description": "the fields the envelope carries back: row_count, returned_ids, version_id, commit_sha, pipeline_id, message_id …"
},
"modes": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"read",
"dry_run",
"write",
"send",
"ddl"
]
}
},
"write_shape": {
"type": "string",
"enum": [
"A",
"B",
"E"
],
"description": "Execution form: A collapsed transaction; B deterministic leased transaction; E external/DDL effect. Persisted as CONNECTOR_SCOPES.EXECUTION_FORM."
},
"route": {
"type": "object",
"additionalProperties": false,
"required": [
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"direct",
"unreachable"
],
"description": "D132: direct connections only; the tunnel route kind is dropped"
},
"verified_on": {
"type": "string",
"format": "date-time"
},
"probe": {
"type": "string",
"description": "the probe that verified it (tns ping, https HEAD, ldap bind …)"
}
}
},
"credential_ref": {
"type": "string",
"description": "Vault path; never a value"
},
"ceiling": {
"type": "object",
"description": "kind = ceiling: the environment × system × target × mode set no grant may exceed"
},
"health": {
"type": "string",
"enum": [
"green",
"amber",
"red",
"unknown"
]
},
"state": {
"type": "string",
"enum": [
"draft",
"published",
"retired"
]
},
"application": {
"type": "string",
"enum": [
"endpoint",
"statement",
"publication",
"ui",
"person"
],
"description": "How an effect is actually made on this target: the system's own configuration endpoint, a parameterised statement template, an ordered publication sequence, a user-interface action, or an assigned person. It also fixes the behaviour of the effect step: 'endpoint', 'statement' and 'publication' are **caused** — the platform runs the operation and reads its evidence; 'ui' and 'person' are **assigned** — the platform raises the action with actor and rendered instruction, parks the case, and closes on a measurement of the target, never on the actor's report. The platform declares no user-interface driver today; a customer that declares one turns that row into a caused operation under the same contract and the same checks. This field is why nothing about the apply is shared between targets."
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "operation"
}
}
},
"then": {
"required": [
"operation_id",
"effect_class",
"authorization",
"timeout_ms",
"effect_of_timeout",
"recovery",
"evidence_returned"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "operation"
},
"effect_class": {
"enum": [
"transactional",
"compensable",
"irreversible",
"ddl"
]
}
}
},
"then": {
"required": [
"write_shape",
"idempotency_key_shape"
],
"properties": {
"authorization": {
"enum": [
"write_grant",
"gate"
]
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "operation"
},
"effect_class": {
"const": "read"
}
}
},
"then": {
"properties": {
"authorization": {
"const": "read_grant"
},
"modes": {
"items": {
"enum": [
"read",
"dry_run"
]
}
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "reach"
}
}
},
"then": {
"required": [
"route",
"credential_ref"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "ceiling"
}
}
},
"then": {
"required": [
"ceiling"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "operation"
},
"effect_class": {
"enum": [
"ddl",
"irreversible"
]
}
},
"required": [
"kind",
"effect_class"
]
},
"then": {
"properties": {
"write_shape": {
"const": "E"
}
}
}
}
]
}