finos / finos/calm-schema

Remove protocol as an optional property on all relationships

Open
#5 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

### Target Schema:
- **core.json** (CALM core metamodel)

### Description of Change:
Remove the global `protocol` property from **all** relationships in `core.json` on [core.json#L147.](https://github.com/finos/architecture-as-code/blob/main/calm/release/1.0-rc2/meta/core.json#L147). Instead of baking protocol semantics into every relationship, users will attach a dedicated “Binding” interface via the `interfaces` array on a `node-interface` when they define connectivity relationships (e.g. `connects`, `interacts`). The `interface.json` spec already allows arbitrary interfaces via `interface-definition` (no protocol concept built‑in), so protocol modeling will be handled by a user‑supplied schema referenced there.

### Use Cases:
- **Service-to-Service Communication:** Specify HTTP/HTTPS, AMQP, or custom RPC protocols only on true connectivity links.
- **Event Streaming:** Attach Kafka or MQTT binding details (topic, partition, protocol) without polluting non‑streaming relationships.
- **Secure Channels:** Model TLS/mTLS settings via a reusable Binding interface, rather than embedding them in every relationship.

### Current Limitations:
- **Global Protocol Field:** Every relationship (`deployed-in`, `composed-of`, `options`) must accept or ignore a `protocol` value, even when it’s meaningless.
- **No Native Binding Interface:** The `node-interface` def in `interface.json` has no protocol field; tooling today must misuse the core `protocol` property on relationships or invent external conventions.

### Proposed Schema Changes:
```diff
--- core.json
@@ relationships.properties
- "protocol": { "$ref": "#/defs/protocol" }

--- core.json (connects-type)
@@ properties
+ // Optional protocol binding delegated to a user-supplied interface
+ // (removed from global relationships; see interface-definition usage)
```
_No changes required in `interface.json` – it already defines a generic `interface-definition` for users to reference external binding schemas._

### Backward Compatibility:
- **Existing Documents:** Removing `protocol` from the schema properties will **not** immediately invalidate existing CALM documents, because the `relationship` definition uses `additionalProperties: true`. Unknown fields like `protocol` will still be accepted.
- **Deprecation Path:**
1. **Deprecate** `protocol` in the documentation and mark it for removal in a future major release.
2. **Encourage** migration to the new Binding interface pattern over the next release cycle.
3. **Remove** the legacy `protocol` entirely in the subsequent major version once adoption is complete.

### Validation Strategy:
- **Schema Tests:**
- Add positive tests where a `connects` relationship is valid only when a Binding interface with `protocol` is referenced.
- Add negative tests rejecting `protocol` directly on relationships once the deprecation period ends.
- **Example Documents:** Provide JSON/YAML snippets for:
- Simple structural relationships (no protocol)
- Connectivity relationships using the new Binding interface
- **Tooling Validation:** Run existing JSON Schema validators (e.g. AJV, jsonschema) on updated schemas and examples.

### Implementation Impact:
- **Tools & Linters:** Must stop expecting `protocol` under `relationship.properties`, and instead recognize protocol carried via an external interface-definition.
- **Documentation:** Update metamodel docs to:
- Remove examples showing `protocol` on relationships
- Add examples showing `interface-definition` with Binding schema
- **Related Schemas:** Any CALM extensions that referenced the old `protocol` location should be revised.

### Version Strategy:
- **Change Type:** Depending if we want to keep support for additionalProperties:true on relationship it's a Breaking change or increment major version
- **Release Plan:**
1. Publish draft changes under a new release branch.
2. Announce deprecation of `protocol` on relationships with migration guide.
3. Finalize in next formal release cycle.

### Implementation Checklist:
- [ ] Remove `protocol` from `core.json` relationships.
- [ ] Draft and publish a Binding interface schema (e.g. `binding.json`).
- [ ] Add example CALM documents demonstrating new pattern.
- [ ] Write schema validation tests.
- [ ] Update CALM documentation and migration guide.
- [ ] Coordinate major version bump and release timeline.

### Additional Context:
- Leverages existing `interface-definition` in `interface.json` for user‑supplied Binding schemas.
- See GitHub issue #1189 for community discussion and examples of binding interfaces.

Contributor guide

Open the contributing guide

Research direction

Start with the relationships definition around line 147 in core.json and compare it with the generic interface-definition in interface.json. Review issue #1189 and the existing AJV or jsonschema validation setup before checking examples and documentation. Done means the relationship schema no longer declares protocol, Binding-interface examples and validation coverage are updated, and migration guidance reflects the change.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation, tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.