Support for Options Within Patterns Using OneOf in JSON Schema and CLI Updates

[jpgough-ms]

Feature Request

Description of Problem:

Patterns play a crucial role in enabling reuse across platforms and architectures within an organization. However, there are scenarios where patterns must accommodate options or variations.

For example, consider a pattern for a three-tier application. While the server-side application and database remain consistent, there are two distinct ways the application could be consumed:

1. Through a user interface (UI).
2. Through another application (service-to-service) running on the server side.

In such cases, it is beneficial to define one pattern with two configurable options: one for UI consumption and another for service-to-service consumption. Currently, there is no clear mechanism in place to represent these options within the pattern definition.

Potential Solutions:

A potential approach is to leverage JSON Schema to define a OneOf clause. This would allow the pattern to specify multiple valid configurations, providing flexibility while maintaining structure.

Using the CALM JSON schema as a base, a OneOf could be implemented to handle these variations. Here's an example:

{
  "$schema": "https://calm.finos.org/draft/2024-12/meta/core.json",
  "$id": "https://calm.finos.org/draft/2024-12/example/pattern",
  "title": "Three-Tier Application Pattern",
  "properties": {
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "oneOf": [
          {
            "properties": {
              "unique-id": { "const": "web-client" },
              "node-type": { "const": "service" },
              "name": { "const": "Web Client" },
              "description": { "const": "Webclient based interaction with the three tier application" }
            },
            "required": ["unique-id", "node-type", "name", "description"]
          },
          {
            "properties": {
              "unique-id": { "const": "service-client" },
              "node-type": { "const": "service" },
              "name": { "const": "Service Client" },
              "description": { "const": "A service based interaction with the three tier application" }
            },
            "required": ["unique-id", "node-type", "name", "description"]
          }
        ]
      }
    }
  }
}

Aim of This Issue:

The goal is to prototype and explore the feasibility of using OneOf in JSON Schema for defining patterns with configurable options.

This includes:

• Assessing how well this approach works for real-world scenarios, the example above shows only node options, but the reality is relationships will need to be included too
• Determining potential implications for tooling and usability within the Architecture as Code framework.
• Updating the calm generate command to enable users to pick the option of patterns as required

[rocketstack-matt]

Do we think this approach could be adapted to specify specific patterns or indeed instantiations through the requirement of a specific document URI? This could allow architects to be specific.

[jpgough-ms]

@rocketstack-matt if I'm understanding the question correctly, then OneOf can either be used inline (in the pattern) or refer to an external document through normal JSON Schema. It would look something like:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://calm.finos.org/draft/2024-12/patterns/three-tier.json",
  "title": "Three-Tier Application Pattern",
  "type": "object",
  "properties": {
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "https://calm.finos.org/draft/2024-12/nodes/ui-node.json"
          },
          {
            "$ref": "https://calm.finos.org/draft/2024-12/nodes/service-node.json"
          }
        ]
      }
    }
  }
}