Remove protocol as an optional property on all relationships
- 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
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