Migrating from 1.x to 2.0
Version 2.0 changes defaults and makes previously implicit or lossy behavior explicit. Review generated graph identifiers and warnings before replacing a 1.x workflow.
Observable changes
Area |
1.x behavior |
2.0 behavior |
|---|---|---|
Python requirement |
Python 3.9-compatible package declaration |
Python 3.10 or newer |
Default base URI |
Shared |
Deterministic |
Explicit identity |
One supplied base URI |
Exact base URI or parent URI plus content UUID |
Python project decoder |
|
|
Invalid stereotypes |
Limited validation and implicit emission |
Normalized, type-checked, and controlled by |
Invalid cardinalities |
Invalid source handling was not policy-controlled |
|
Unresolved diagram references |
Could materialize unresolved reference stubs |
Default |
Path-point order |
Order was lost without a dedicated policy |
Warning by default, with an optional non-normative comment |
|
No dedicated handling |
Warning and omission by default, with an optional non-normative comment |
Metadata and provenance |
Basic generator and creation metadata added automatically |
Deterministic model-only output by default; optional |
Vocabulary target |
OntoUML Vocabulary 1.1.0 |
OntoUML Vocabulary 1.1.1 |
Diagram dimensions |
Vocabulary range excluded zero |
Zero-valued width and height use |
Legacy |
Could be mapped to an unsuitable term |
Empty values are omitted; non-empty values are warned and omitted |
Preserve 1.x-style resource identifiers
If a workflow depends on the former shared namespace, request it explicitly:
python -m json2graph.decode -i my_ontology.json --base-uri https://example.org#
This can create identifier collisions when outputs are combined, especially in
batch conversion. Prefer the default identity or
--base-uri-with-content-id <parent> for content-scoped namespaces.
The Python equivalent is base_uri="https://example.org#" without
append_content_hash.
Select policies explicitly
The 2.0 defaults are:
invalid stereotypes:
preserve;invalid cardinalities:
preserve;unresolved diagrammatic
modelElementreferences:omit;path-point order:
warn;propertyAssignments:warn; andtransformation metadata:
none.
Pin these values in automated workflows when future configuration changes must
not alter behavior. The correct option remains separate and defaults to
disabled.
Review output comparisons
When comparing 1.x and 2.0 graphs:
account for the base-URI change or supply the former URI explicitly;
compare complete-project output with
decode_json_projectand model-only output withdecode_json_modelor--model_only;record the selected policies and review emitted warnings;
expect OntoUML Vocabulary 1.1.1 datatypes and Text handling; and
exclude embedded provenance when deterministic graph equality is required.
Read Policies and configuration and Limitations and diagnostics for the precise 2.0 semantics.