apache / apache/ossie

Proposal: Promote Behavior Layer to semantic_model.behavior (Actions/Rules/Effects)

Open
#106 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
2.1k
Forks
267
Avg merge
4d 20h
Merged PRs (30d)
24

Description

# Proposal: Promote Behavior Layer to `semantic_model.behavior` (Actions / Rules / Effects)

## Summary
This proposal introduces an **optional**, **vendor-agnostic** first-class `semantic_model.behavior` block to OSI Core, enabling deterministic action planning and attribution (what changed/why).

Key additions:
- `semantic_model.behavior` (preferred placement)
- `actions` (preferred) with backward-compatible alias `action_types`
- `effects` for machine-readable impact annotations on datasets/fields/metrics/relationships

## Motivation
OSI already supports semantic structure (datasets/relationships/metrics), but many agent-driven use cases require **behavioral semantics**:
- Deterministic action planning: validate that an action plan is executable and consistent with constraints.
- Attribution: explain “what changed/why” for state fields and master data growth.
- Impact analysis: identify which actions can affect a dataset or field (e.g., state transitions).

The current approach embeds behavior as vendor JSON under `custom_extensions`, which makes it harder for generic tools to discover and validate behavior in a standard way.

## Non-goals
- This proposal does **not** prescribe how actions are executed (SQL vs API vs workflow).
- This proposal does **not** replace `custom_extensions` or remove legacy behavior embeddings.

## Design
### 1) First-class placement
Add optional `semantic_model[].behavior`:
- `namespace` (string)
- `behavior_layer_version` (string)
- `actions` (array of actions) OR `action_types` (legacy alias)
- `rules` (array)
- `metadata` (optional)

### 2) Backwards compatibility
- Legacy embedded behavior under `custom_extensions` remains valid.
- New tools SHOULD prefer `semantic_model.behavior` when present.

### 3) Effects (impact annotations)
Add optional `effects[]` to actions.

Minimal fields:
- `entity`: dataset/field/metric/relationship
- `mode`: read/write/derive
- `selectors`: dataset + field_names (or other selectors)
- optional: `impact_type`, `transition`, `set_value`, `confidence`, `notes`

## Example (SAP P2P)
See: `examples/p2p_behavior_effects_minimal.yaml`

## Compatibility & Versioning
- Additive change: `behavior` is optional.
- Proposed bump: `version: 0.1.2` to reflect schema extension.

## Questions for maintainers
1. Is the `semantic_model.behavior` placement acceptable as a first-class block?
2. Should `actions` be the preferred field name with `action_types` as legacy alias?
3. Is the proposed minimal `effects` structure sufficient, or should it be further constrained?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.