## Summary Semantic Treehouse will add support for an external data transformation service for MappingVersion specifications. The solution should follow the same design pattern as the current validator service: a version-scoped configuration entity holds the technical settings, the backend assembles and sends a complete request to an external service, and the frontend provides a dedicated module for selecting a version, entering input data, and viewing the result. The current validator flow is the reference design. Today, a SyntaxBinding entity is linked to a MessageModelVersion and contains the validator configuration, including schema, additional rules, and related validation settings. When a user submits a message to validate, the backend sends a complete validation request, including the example or input message, to the external validator endpoint. The new transformation feature should reuse this same solution design, but for MappingVersion and JSONata-based transformation logic. ## Goal Enable users to define and run data transformations against MappingVersion specs by calling an external transformation service with a JSONata transformation specification stored in a dedicated backend entity. ## Solution Design ### Backend architecture The backend will introduce a new entity linked to MappingVersion. This entity will store the JSONata transformation specification and any related technical configuration needed for execution. In the same way that SyntaxBinding belongs to MessageModelVersion, the new transformation binding entity will belong to MappingVersion. The backend controller will: - load the selected transformation binding - verify access using the existing security model - build a complete transformation request - send the request to the external transformation service - return the transformed output and metadata to the frontend The request sent to the external service should include: - the input data to transform - the JSONata specification - any service configuration required to run the transformation This should be implemented using the same architectural style as the validator service, including the same separation of responsibilities between entity, controller, service orchestration, and external endpoint integration. ### Service configuration (Helm and Docker Compose) The transformation integration should follow the existing validator configuration style (`STH_*_ENDPOINT` environment variables and Helm `enabled + url` blocks). Proposed backend environment variable names: - `STH_TRANSFORMATION_ENDPOINT`: URL of the external transformation service endpoint. - `STH_TRANSFORMATION_TIMEOUT_SECONDS`: request timeout for external transformation calls (default proposal: `30`). Proposed Helm values (`deployment/helm-charts/semantic-treehouse/values.yaml`): - `transformationService.enabled` (bool) - `transformationService.url` (string) - `transformationService.timeoutSeconds` (int) Proposed Helm deployment env wiring (`templates/deployment.yaml`): - `STH_TRANSFORMATION_ENDPOINT` should be set from `transformationService.url` only when `transformationService.enabled=true`; otherwise set to empty string. - `STH_TRANSFORMATION_TIMEOUT_SECONDS` should be set from `transformationService.timeoutSeconds`. Proposed Docker Compose variables (`docker-compose.yml` / `.env`): - `STH_TRANSFORMATION_ENDPOINT=http://host.docker.internal:3100/transform` - `STH_TRANSFORMATION_TIMEOUT_SECONDS=30` Behavioral requirement: - If `STH_TRANSFORMATION_ENDPOINT` is empty or unset, transformation calls are disabled and the backend returns a clear configuration error instead of attempting an external request. Documentation requirement: - Add both transformation variables to the environment-variable reference in `README.md`. ### Entity design A new entity is needed for transformation configuration: `TransformationBinding` It should be: - linked to MappingVersion - scoped to the owning project and spec version in the same way as SyntaxBinding - responsible for storing the JSONata transformation specification - extend the existing versioned configuration pattern used elsewhere in the backend - compatible with serializer groups, cloning behavior, timestamps, and access control conventions already used in the codebase This keeps transformation configuration structurally aligned with the validator configuration model and makes the feature consistent with the existing backend design. #### Symfony backend entity proposal: `TransformationBinding` Recommended class location: - `backend/src/Entity/TransformationBinding.php` Recommended repository location: - `backend/src/Repository/TransformationBindingRepository.php` Recommended relation on mapping version: - Add `#[ORM\OneToMany(targetEntity: TransformationBinding::class, mappedBy: 'bindingFor', cascade: ['persist', 'remove'], orphanRemoval: true)]` to `MappingVersion`. Proposed class properties: - `id: ?string` - `name: ?string` (human-readable label) - `enabled: ?bool` (controls whether this binding is available in transformation UI/API) - `bindingFor: ?MappingVersion` (many-to-one owning relation) - `jsonataSpec: ?string` (JSONata expression/specification text, potentially large) - `inputFormat: ?string` (optional hint like `JSON`, future-proofing) - `outputFormat: ?string` (optional hint like `JSON`) - `updatedAt: ?\DateTimeImmutable` (timestamp, `#[Timestampable]`) Validation and serialization recommendations: - `#[Assert\NotBlank]` on `name` and `jsonataSpec` - `#[Assert\Length(max: 255)]` on `name` - Put API fields in `default_read` / `default_write` serializer groups, aligned with existing entities. Doctrine naming and migration convention: - Follow current project convention with camelCase DB table/column names. - Suggested table name: `transformationBinding`. - Suggested join column name: `bindingForId` (to `mappingVersion.id`). Example Symfony entity snippet: ```php <?php namespace App\Entity; use App\Entity\Specification\MappingVersion; use App\Repository\TransformationBindingRepository; use Doctrine\ORM\Mapping as ORM; use Gedmo\Mapping\Annotation\Timestampable; use Symfony\Component\Serializer\Attribute as Json; use Symfony\Component\Validator\Constraints as Assert; #[ORM\Entity(repositoryClass: TransformationBindingRepository::class)] class TransformationBinding implements ProjectScopedEntityInterface, EntityInterface { use ProjectScopedEntityTrait; #[ORM\Id] #[ORM\Column] #[ORM\GeneratedValue(strategy: 'CUSTOM')] #[ORM\CustomIdGenerator(class: 'App\\Doctrine\\IdGenerator\\StIdGenerator')] #[Json\Groups(['default_read'])] private ?string $id = null; #[Assert\Length(max: 255)] #[Assert\NotBlank] #[ORM\Column(length: 255)] #[Json\Groups(['default_read', 'default_write'])] private ?string $name = null; #[ORM\Column(type: 'boolean')] #[Json\Groups(['default_read', 'default_write'])] private ?bool $enabled = false; #[Assert\NotBlank] #[ORM\Column(type: 'text')] #[Json\Groups(['default_read', 'default_write'])] private ?string $jsonataSpec = null; #[Assert\Length(max: 50)] #[ORM\Column(length: 50, nullable: true)] #[Json\Groups(['default_read', 'default_write'])] private ?string $inputFormat = 'JSON'; #[Assert\Length(max: 50)] #[ORM\Column(length: 50, nullable: true)] #[Json\Groups(['default_read', 'default_write'])] private ?string $outputFormat = 'JSON'; #[ORM\ManyToOne(inversedBy: 'transformationBindings')] #[ORM\JoinColumn(nullable: false)] private ?MappingVersion $bindingFor = null; #[Timestampable] #[ORM\Column] #[Json\Groups(['default_read'])] private ?\DateTimeImmutable $updatedAt = null; public function getProject(): ?Project { return $this->getBindingFor()?->getVersionOf()?->getProject(); } public function getId(): ?string { return $this->id; } public function getName(): ?string { return $this->name; } public function setName(?string $name): static { $this->name = $name; return $this; } public function isEnabled(): ?bool { return $this->enabled; } public function setEnabled(bool $enabled): static { $this->enabled = $enabled; return $this; } public function getJsonataSpec(): ?string { return $this->jsonataSpec; } public function setJsonataSpec(?string $jsonataSpec): static { $this->jsonataSpec = $jsonataSpec; return $this; } public function getBindingFor(): ?MappingVersion { return $this->bindingFor; } public function setBindingFor(?MappingVersion $bindingFor): static { $this->bindingFor = $bindingFor; return $this; } } ``` Request assembly note (backend service/controller): - The transformation request payload should be constructed from both the selected `TransformationBinding` and the runtime input message, similar to how `ClientValidationRequest` currently combines `SyntaxBinding` configuration and message content for validator calls. ### Frontend design The frontend should provide a dedicated transformation module that is visually and functionally similar to the Validator module. The transformation UI should: - let users select project, specification, version, and transformation binding - show the MappingVersion context and the linked JSONata configuration - allow users to enter or paste input data for transformation - submit the full transformation request to the backend - display the transformed result and any service response details The layout, interaction model, and component breakdown should closely mirror the Validator module so users can understand the feature immediately and so the implementation remains consistent with existing UX patterns. {width=900 height=502} ## Architecture Overview Frontend transformation module -> backend transformation controller -> transformation binding linked to MappingVersion -> complete transformation request with input data and JSONata spec -> external transformation service -> transformed output -> backend response -> frontend result view ## Acceptance Criteria - [ ] A new transformation entity exists and is linked to MappingVersion. - [ ] The entity stores JSONata transformation configuration. - [ ] The backend can assemble and send a full transformation request to an external service. - [ ] The response from the external service is returned to the frontend. - [ ] The frontend provides a dedicated transformation module similar to the Validator module. - [ ] The solution reuses the existing validator architecture pattern as closely as possible. - [ ] Access control, version scoping, and UI structure remain consistent with the current implementation style. - [ ] Helm values and deployment templates support enabling/disabling and configuring the transformation service endpoint. - [ ] Docker Compose can configure the transformation service via environment variables. - [ ] README environment variable reference includes transformation service configuration variables.