Repository navigation
docs: document significant specification changes and migration impact - #686
Conversation
Record rationale, consumer impact, compatibility and source PRs for major Core, Ontology and Relational Interface changes in unreleased 0.2.0.dev0. Refs apache#603
| | Merged (UTC) | Area / source | Change and rationale | Impact on producers and consumers | | ||
| | --- | --- | --- | --- | | ||
| | 2026-09-16 | Core [#383](https://github.com/apache/ossie/pull/383) | **One model per document.** Model properties moved to the document root to remove the wrapper and make the exchange unit unambiguous. | **Breaking within the unreleased schema.** Unwrap a single `semantic_model`; split a multi-model wrapper into separate documents. Old wrapped documents do not validate against the new root. See [migration guidance](../core-spec/spec.md#migrating-earlier-document-shapes). | | ||
| | 2026-09-22 | Core [#439](https://github.com/apache/ossie/pull/439) | **Register `OSSIE_SQL_2026` as a portable expression dialect.** Its existing language definition could not be used in documents while the dialect token was absent from schema validation. | Additive at merge time; no change to the default dialect. This initially used `expression.dialects`; the later [#617](https://github.com/apache/ossie/pull/617) adds the preferred `expression.sql` form. | | ||
| | 2026-10-04 | Ontology [#458](https://github.com/apache/ossie/pull/458) | **Separate ontology, model, and mapping documents.** Independent references allow an ontology and a semantic model to be reused without embedding copies of either. | Mapping authors can use standalone documents validated by `ontology/mapping.json` and references to one ontology and one model. The older embedded `ontology_mappings` form remains accepted but is deprecated; importers should support the standalone form. | | ||
| | 2026-10-13 | Expression language [#577](https://github.com/apache/ossie/pull/577) | **Explicit `NULLS FIRST` / `NULLS LAST` in window `ORDER BY`.** Engine defaults differ, so explicit ordering is needed for portable window results. | Expression parsers and SQL translators should accept and preserve the new clause. The default when the clause is omitted was *not* decided by this change. | | ||
| | 2026-10-19 | Relational interface [#354](https://github.com/apache/ossie/pull/354) | **Layer 2 Relational Query Interface added.** It describes querying model measures through SQL relations and `MEASURE()` with correct aggregation semantics. | Additive specification document, not a new core JSON/YAML field. Query-engine implementers can adopt the interface; schema-only consumers need no migration. See [relational semantics](../core-spec/relational_semantics.md). | | ||
| | 2026-10-22 | Core [#591](https://github.com/apache/ossie/pull/591) | **Dataset-scoped metrics.** Metrics can live with the dataset they describe instead of all metrics living at the model root. | Additive optional `datasets[].metrics`. Resolving a dataset metric uses unqualified declared field names; model-scoped metric expressions use qualified `dataset.field` names. Consumers must account for both scopes when reading metrics. | | ||
| | 2026-10-26 | Core [#617](https://github.com/apache/ossie/pull/617) | **Portable `expression.sql` and open vendor dialect tokens.** The Ossie-defined portable expression becomes primary, while vendor-specific dialects stay opaque and extensible. | Existing `expression.dialects` remains accepted; writers should prefer `expression.sql` for portable SQL, and readers should give it precedence over a duplicate `OSSIE_SQL_2026` dialect entry. Dialect names are no longer a closed enum; consumers must tolerate unknown values. | | ||
| | 2026-11-01 | Ontology [#668](https://github.com/apache/ossie/pull/668) | **Non-empty ontology identifiers.** Validation now rejects empty names, IRIs, references, and mapping SQL expressions, matching existing restrictions elsewhere. | Authors should supply non-empty values for identifying strings. Some malformed documents that previously passed schema validation now fail earlier, with schema-layer errors. | |
There was a problem hiding this comment.
If I understand the intent (and it has value), I'm a bit concern how to keep this table up to date.
Can we imagine a way to populate that automatically (or semi-automatically)?
By experience on other Apache projects, it's extremely hard to maintain this in sync and it can drift easily.
There was a problem hiding this comment.
Thanks @jbonofre for the feedback. I agree that keeping a revision table synchronized manually could become difficult as the project evolves.
I've pushed a revision in commit 0f0fdde to address this concern:
- Added
scripts/audit-spec-changes.pyto identify candidate specification changes missing from the curated history. - Updated
CONTRIBUTING.mdto integrate significant change-history updates into the contribution process. - Updated the PR template to make this part of normal review.
The audit is intentionally advisory. It helps identify omissions, while maintainers retain responsibility for documenting rationale, compatibility impact, and migration guidance.
It does not guarantee complete coverage, and it does not automatically generate the historical explanations.
The latest CI is still awaiting approval and has not executed.
Would this semi-automated approach address your concern, or would you prefer a lighter-weight solution relying more directly on GitHub PR metadata?
|
Thanks @jbonofre. I've integrated current upstream The curated history now explains the former Fork verification: https://github.com/zljie/OSI/actions/runs/42769556155. Python 3.11–3.14 each passed 571 validation tests, 269 Python model tests, the 12 audit tests, and the 59 duplicate-key validator tests, plus generated-type synchronization and six canonical-example validation commands. The flights mapping example still emits two SQL-expression parsing warnings. All four records match the exact tree of this PR HEAD. Running the advisory audit against the pinned upstream history reported 9 recorded PRs and 44 unlisted candidates. These are suggestions for human review, not confirmed omissions, and the audit remains non-gating. Apache upstream workflows still report |
Summary
Closes #603.
This PR adds a curated history of significant merged Apache Ossie specification changes, explaining their rationale, compatibility implications, and migration guidance. Following maintainer feedback, it includes a semi-automated, advisory maintenance mechanism to reduce documentation drift.
Changes
docs/spec_changes.mdrecords selected merged changes with originating PRs and downstream impact.docs/index.mdandcore-spec/spec.mdlink the history from the existing documentation and version history.CONTRIBUTING.mdand the PR template ask authors to record material specification changes in the same PR, or explain why no entry is warranted.scripts/audit-spec-changes.pyscans local first-parent Git history for candidate specification changes absent from the curated table. It now recognizes both squash subjects ending in(#123)and standardMerge pull request #123subjects, and sorts candidate PR numbers numerically.scripts/tests/test_audit_spec_changes.pyadds 12 offline parser and real-Git command tests, including candidate filtering, recorded entries, explicit refs, empty time windows, invalid inputs, and non-mutation of the checkout.Latest upstream integration
Integrated upstream
mainatd700cdeac41d15a7004eb2f9b0b38a2b1d517a18and resolved the reproduced conflict incore-spec/spec.md. The latest upstream normative content is retained; only this PR's navigation paragraph is reapplied there.The history now identifies
0.3.0.dev0as unreleased and mutable, explains that earlier entries were merged under the former0.2.0.dev0development label, and records merged #691 with its UTC merge date and document-version migration implications. This is not a release announcement, and there will be no0.2.0release.Maintenance approach and scope
Automated discovery suggests candidates; contributors and maintainers still decide materiality and write rationale, compatibility judgments, and migration guidance. The audit remains advisory, not a mandatory CI gate or a complete changelog. Commits without recognizable PR references can be missed, and editorial changes can appear among candidates.
Current scope: 6 commits, 7 changed files relative to the integrated upstream baseline. Changes are limited to documentation, contribution guidance, and advisory audit tooling/tests. No production schema, validator, SDK, or converter behavior is changed by this PR. Verification-only workflows and preparation scripts are not included.
Verification — 2026-11-10
04837b6c2fc0f746100d7399c12df8d878bc27d0.400a5141f1876713956176b68acfeb696cbf647a, the tree of the current PR HEAD. The original branch was advanced without force-pushing.action_required. No Apache upstream CI pass or maintainer approval is claimed. The review thread remains open.AI assistance was used in preparing the documentation, integration, audit fix, and tests. The contributor remains responsible for accuracy, verification, and follow-up.