feat(core-spec): add optional behavior with actions and effects

[zljie]

Adds optional root-level behavior metadata with actions, rules, and intended read/write/derive effects for planning and attribution.

• core-spec/behavior-layer.schema.json remains the canonical contract. ossie-schema.json embeds a generated resource, including its $id, so consumers can validate offline with just the main schema. scripts/generate-behavior-schema.py --check runs in CI to prevent drift; use --apply after changing the canonical source.
• Optional impact_type enforces the five documented values. Known fields are validated, open extensions and the legacy action_types alias are preserved, and empty action/rule lists remain valid.
• The Python SDK validates Behavior with strict Pydantic types while preserving the dictionary API, valid extensions, and JSON/YAML round trips. No new runtime dependency or schema-file lookup is needed by the SDK.
• Removes the invalid empty Behavior placeholder from the root template; the separate Behavior reference contains a valid minimal block. Adds single-file offline regression coverage for Salesforce and OrionBelt, including valid and invalid payloads.
• Synced with current main and retains the flat document format and 0.2.0.dev0.

Local validation:

• 434 validation/Python tests and 53 standalone duplicate-key validator tests passed.
• OrionBelt: 339 passed, 1 optional DuckDB test skipped; an installed wheel outside the checkout passed 14 offline acceptance/rejection cases using only its bundled main schema.
• The installed SDK wheel validates Behavior and preserves JSON/YAML round trips outside the checkout. Focused Behavior tests also pass on Python 3.11 with Pydantic 2.0.
• Salesforce: Java 21 mvn verify passed (386 cases, 16 existing skips; all 36 new offline Behavior cases passed). The packaged JAR passed 12 acceptance/rejection cases outside the checkout using only its bundled main schema.
• All six examples, both JSON Schema metaschemas, spec/type and Behavior synchronization, Apache RAT, and PR whitespace checks passed.

Behavior annotations describe intended effects; they do not execute actions or enforce business policies. The maintainer has also requested a dev@ vote on adopting this addition.

[jbonofre]

Can you please clarify between behavior-layer.schema.json and osi-schema.json?

[jbonofre]

I'm a bit confused here: it seems we have two behavior type definition:

• in behavior-layer.schema.json with standalone schema
• in osi-schema.json inline as $defs/Behavior, $defs/BehaviorAction, $defs/BehaviorEffect, $defs/BehaviorRule

I see already some differences before the two definitions.

Why not having osi-schema.json reference behavior-layer.schema.json via $ref.

I guess that having two schemas that must kept in sync manually will drift.

[jbonofre]

impact_type is a string here, but an implicit enum in spec.yaml.

[jbonofre]

@zljie any update? Thanks!

[zljie]

Thanks for following up, and apologies for the delay. I’ve narrowed the follow-up to:

• Rebase onto current main and adapt the example to ossie-schema.json and the current single-model document format.
• Make behavior-layer.schema.json the canonical source for behavior validation, reference it via $ref, and remove the duplicate behavior definitions.
• Constrain optional impact_type to state_transition, master_data_mutation, transactional_write, derived_metric_change, and other.
• Align field constraints and documentation, retain action_types compatibility, and add offline reference, validation parity, and Python round-trip coverage.

I’ll reuse the existing local schema resolver and keep this focused on the schema contract. The branch update and CI run are still pending; I’ll post the commit and results once those are complete.

[zljie]

@jbonofre Updated in 622a22f (latest head: 3688717).

• behavior-layer.schema.json is now the canonical source, referenced from ossie-schema.json via $ref; duplicate Behavior definitions are removed.
• Optional impact_type now enforces the five documented values. Known field constraints and docs are aligned, with action_types compatibility retained.
• Synced with current main, updated the P2P example to the flat document format, and added offline validation parity, SDK round-trip coverage, and CI validation of the example.

Local checks passed: 334 validation/Python tests, 53 standalone validator tests, six examples, schema checks, spec/type synchronization, and Apache RAT. GitHub Actions are awaiting maintainer approval. Could you please approve the workflows and take another look? Thanks!

[Copilot]

🟡 Changes recommended

The Python SDK currently accepts and serializes behavior payloads that violate the canonical schema.

1 open finding

• Validate behavior against the canonical schema · New

What changed in this PR

Adds optional behavior metadata—actions, rules, and effects—to the core specification and Python SDK.

Changes:

• Introduces the canonical behavior schema and documentation.
• Adds SDK round-trip preservation and validation tests.
• Adds a P2P example and CI validation.

File	Description
core-spec/​behavior-layer.schema.json	Defines behavior validation.
core-spec/​behavior-layer.md	Documents the behavior layer.
core-spec/​ossie-schema.json	References the behavior schema.
core-spec/​spec.md	Documents root-level behavior.
core-spec/​spec.yaml	Adds descriptive behavior structures.
examples/​p2p_behavior_effects_minimal.yaml	Demonstrates behavior annotations.
python/​src/​ossie/​models.py	Preserves behavior in SDK models.
python/​tests/​test_models.py	Tests behavior serialization.
validation/​tests/​test_validate.py	Tests behavior constraints and aliases.
.github/​workflows/​validation-ci.yml	Validates the new example.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[zljie]

Implemented in d07d8dc. The SDK keeps the dictionary API but validates declared Behavior/action/effect/rule fields with strict Pydantic types before accepting them, including required fields, aliases, enums, and present-but-null values. Valid extensions and JSON/YAML round trips are preserved without adding a runtime dependency. Tests derive mutations and expected acceptance from the canonical schema for both OssieDocument and OssieSemanticModel; the full SDK/validation suite passes, and focused Behavior tests also pass on Pydantic 2.0.

[jbonofre]

Requesting changes for the $ref resolution problem.

The spec.yaml is minor.

[jbonofre]

The new "$ref": "behavior-layer.schema.json" points at a sibling file, but only validation/validate.py has been updated to resolve it. Other consumers bundle just ossie-schema.json:

• Salesforce converter: pom.xml copies only ossie-schema.json into /schemas/, and SchemaValidator has no way to locate the sibling. A model with behavior will likely fail to load or validate.
• OrionBelt converter: pyproject.toml vendors only ossie-schema.json, and Draft202012Validator is created without a registry. The $ref is unresolvable, so validation would either crash or be skipped, depending on validation.py.

Could we either bundle behavior-layer.schema.json in those consumers with a retriever or registry, or inline the schema into ossie-schema.json? A test in each converter that validates a model containing behavior would also catch this.

[zljie]

Fixed in d07d8dc by making the main schema self-contained. behavior-layer.schema.json remains canonical; a standard-library generator embeds the complete resource (including its $id/$schema/$defs) in ossie-schema.json, and CI --check prevents drift. Existing single-file packaging needs no resolver change. Added offline positive/negative tests in both converters (including aliases, required fields, and invalid effects). Java 21 mvn verify passed, and the packaged Salesforce JAR and installed OrionBelt wheel both validate outside the checkout with only the bundled main schema.

[jbonofre]

The root template adds behavior: {}, but an empty object fails the schema. It requires namespace, behavior_layer_version, rules, and one of actions or action_types. Anyone copying the template gets a document that doesn't validate.

Could we fill in minimal valid placeholders, or drop behavior from the template and document it separately?

We should also have a [VOTE] on the dev@ mailing list.

[zljie]

Fixed in d07d8dc: the root template now omits the optional behavior placeholder. The separate Behavior reference includes the required fields and valid empty actions/rules lists; a regression test checks this block against the canonical schema. I also agree this specification addition needs the dev@ vote. A vote proposal draft is prepared, but no mailing-list vote has been opened yet; that community decision and maintainer approval remain outstanding.

[zljie]

@jbonofre Updated in d07d8dc, after syncing latest main (2b1f9bf).

All three current findings are addressed:

• The main schema now embeds a generated canonical Behavior resource, with a CI synchronization guard, so single-file consumers validate offline.
• The SDK strictly validates Behavior while preserving the dictionary API, extensions, and aliases.
• The root template omits the invalid empty placeholder; the separate Behavior block is tested as valid.

Local verification passed: 434 validation/Python tests, 53 duplicate-key validator tests, OrionBelt 339 passed/1 optional DuckDB skip, and Java 21 Salesforce Maven verify (386 cases/16 existing skips; all 36 new Behavior cases passed). Both installed wheels and the packaged Salesforce JAR were checked outside the checkout; all six examples, schema metaschemas/synchronization, RAT, and PR whitespace checks passed.

The new-head workflows require maintainer approval (action_required). I have also prepared the dev@ vote proposal; no vote is completed yet. Could you please approve the workflows, review the updated implementation, and advise on initiating the project vote? Thanks!