Definitions Schema & Validation

[matKlju]

AS A Service-Module developer
I WANT a strict, versioned schema for endpoint definitions[]
SO THAT endpoint configs are predictable, multi-UI safe, and ready for verification & tooling (#871)

Description

Add backend-side schema validation and normalization for the definitions field in the endpoints table.
Scope: structure and data quality only.
Out of scope: execution, testing, lifecycle, LLM runtime.

Acceptance Criteria

1. Schema

• definitions must be an array of EndpointDefinition objects
• Object-root payloads are rejected
• A strict, versioned JSON Schema is enforced (EndpointDefinitionSchemaV1) N/A - will not be implemented.
• Unknown fields are rejected
• Schema version is stored (DB column, metadata, or documented constant)

Each EndpointDefinition includes:

Metadata

• id, label (required)
• description (optional)
• type, dataType, supported, isSelected

Request targeting

• methodType (non-empty string, normalized to uppercase)
• At least one of: path (relative) | url | openApiUrl (absolute)

Request sections

• params, headers, body
  • variables (array)
  • rawData (string)
  • isRawSelected (optional boolean)

Optional

• response (array, schema-validated if present)

---

2. Validation

• Enforced on create and update
• Invalid payloads fail fast
• Errors are UI-safe and include JSON pointer paths

---

3. Normalization

• Deterministic key ordering
• Trimmed strings (labels, paths, URLs, variable names)
• Unique variable names:
  • params: case-sensitive
  • headers: case-insensitive
• Defaults applied:
  • variables: []
  • rawData: ""
  • isRawSelected: false

---

4. Compatibility

• Existing valid endpoints remain valid
• Canvas flows unchanged
• No Ruuter DSL execution changes

---

Non-Goals

• ❌ Test URL / verification
• ❌ Lifecycle flags (active)
• ❌ LLM execution
• ❌ Custom / extension fields

---

Definition of Done

• Invalid definitions fail at backend
• Stored definitions[] are normalized and schema-compliant
• All UIs rely on the same endpoint definition contract
• Ready for verification and LLM tooling without refactor