datacontract-cli 1.1.2__tar.gz → 1.2.0__tar.gz

{datacontract_cli-1.1.2/datacontract_cli.egg-info → datacontract_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacontract-cli
-Version: 1.1.2
+Version: 1.2.0
 Summary: The datacontract CLI is an open source command-line tool for working with Data Contracts. It uses data contract YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.
 Author-email: Jochen Christ <jochen.christ@entropy-data.com>, Stefan Negele <stefan.negele@innoq.com>, Simon Harrer <simon.harrer@entropy-data.com>
 License-Expression: MIT
@@ -40,13 +40,13 @@ Requires-Dist: jsonschema<5.0.0,>=4.23.0
 Requires-Dist: pytz>=2024.1
 Requires-Dist: python-multipart<1.0.0,>=0.0.20
 Requires-Dist: rich<16.0,>=13.7
-Requires-Dist: sqlglot<31.0.0,>=26.6.0
+Requires-Dist: sqlglot<30.18,>=26.6.0
 Requires-Dist: python-dotenv<2.0.0,>=1.0.0
 Requires-Dist: boto3<2.0.0,>=1.34.41
 Requires-Dist: Jinja2<4.0.0,>=3.1.5
 Requires-Dist: jinja_partials<1.0.0,>=0.2.1
 Requires-Dist: datacontract-specification<2.0.0,>=1.2.3
-Requires-Dist: open-data-contract-standard<4.0.0,>=3.1.2
+Requires-Dist: open-data-contract-standard<3.3.0,>=3.2.0
 Requires-Dist: deepdiff<10.0.0,>=6.0.0
 Provides-Extra: avro
 Requires-Dist: avro==1.12.2; extra == "avro"
@@ -67,12 +67,13 @@ Requires-Dist: rich>=12.4.4; extra == "dataframe"
 Provides-Extra: databricks
 Requires-Dist: ibis-framework[databricks]<13.0.0,>=10.0.0; extra == "databricks"
 Requires-Dist: databricks-sql-connector<4.5.0,>=3.7.0; extra == "databricks"
-Requires-Dist: databricks-sdk<0.134.0; extra == "databricks"
+Requires-Dist: databricks-sdk<0.136.0; extra == "databricks"
 Requires-Dist: packaging<27.0,>=21.3; extra == "databricks"
 Provides-Extra: databricks-runtime
 Requires-Dist: datacontract-cli[databricks]; extra == "databricks-runtime"
 Provides-Extra: iceberg
-Requires-Dist: pyiceberg==0.11.1; extra == "iceberg"
+Requires-Dist: pyiceberg[pyarrow,rest-sigv4]==0.12.0; extra == "iceberg"
+Requires-Dist: datacontract-cli[duckdb]; extra == "iceberg"
 Provides-Extra: kafka
 Requires-Dist: datacontract-cli[duckdb,parquet]; extra == "kafka"
 Requires-Dist: confluent-kafka<3.0.0,>=2.6.0; extra == "kafka"
@@ -138,17 +139,17 @@ Requires-Dist: datacontract-cli[all]; extra == "dev"
 Requires-Dist: httpx==0.28.1; extra == "dev"
 Requires-Dist: kafka-python; extra == "dev"
 Requires-Dist: minio==7.2.20; extra == "dev"
-Requires-Dist: moto==5.2.2; extra == "dev"
+Requires-Dist: moto==5.2.3; extra == "dev"
 Requires-Dist: openapi-spec-validator<0.10,>=0.7; extra == "dev"
 Requires-Dist: pandas>=2.1.0; extra == "dev"
 Requires-Dist: pre-commit<4.7.0,>=3.7.1; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-xdist; extra == "dev"
-Requires-Dist: pymssql==2.3.13; extra == "dev"
+Requires-Dist: pymssql==2.4.0; extra == "dev"
 Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "dev"
 Requires-Dist: mysql-connector-python<26.8.0,>=8.0.30; extra == "dev"
-Requires-Dist: ruff==0.16.4; extra == "dev"
+Requires-Dist: ruff==0.16.6; extra == "dev"
 Requires-Dist: testcontainers[kafka,minio,mssql,mysql,postgres]==4.15.0; extra == "dev"
 Requires-Dist: trino==0.339.0; extra == "dev"
 Dynamic: license-file
@@ -296,6 +297,9 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
+# fail when a contract change is backward-incompatible
+$ datacontract breaking v1.odcs.yaml v2.odcs.yaml
+
 # execute schema and quality checks (define credentials as environment variables)
 $ datacontract test odcs.yaml
 

{datacontract_cli-1.1.2 → datacontract_cli-1.2.0}/README.md

@@ -141,6 +141,9 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
+# fail when a contract change is backward-incompatible
+$ datacontract breaking v1.odcs.yaml v2.odcs.yaml
+
 # execute schema and quality checks (define credentials as environment variables)
 $ datacontract test odcs.yaml
 

{datacontract_cli-1.1.2 → datacontract_cli-1.2.0}/datacontract/api.py

@@ -15,11 +15,12 @@ from pydantic import BaseModel, Field, ValidationError
 
 from datacontract.config import Config, known_env_names
 from datacontract.data_contract import DataContract, ExportFormat
+from datacontract.model.breaking import BreakingChangeEntry
 from datacontract.model.changelog import ChangelogEntry
 from datacontract.model.exceptions import DataContractException, DefinitionResolutionError
 from datacontract.model.run import Check, ResultEnum, Run
 
-DATA_CONTRACT_EXAMPLE_PAYLOAD = """apiVersion: v3.1.0
+DATA_CONTRACT_EXAMPLE_PAYLOAD = """apiVersion: v3.2.0
 kind: DataContract
 id: orders
 name: Orders
@@ -323,6 +324,14 @@ app = FastAPI(
                 "url": "https://docs.datacontract.com/commands/changelog",
             },
         },
+        {
+            "name": "breaking",
+            "description": "Compare two versions of a data contract and grade each change by compatibility impact.",
+            "externalDocs": {
+                "description": "Documentation",
+                "url": "https://docs.datacontract.com/commands/breaking",
+            },
+        },
     ],
 )
 
@@ -881,6 +890,21 @@ class ChangelogResponse(BaseModel):
     )
 
 
+class BreakingChangesResponse(BaseModel):
+    """Every change between two versions of a data contract, each graded `info`, `warning` or `error`."""
+
+    summary: list[BreakingChangeEntry] = Field(
+        description="One entry per changed element, graded by the most severe change. A property whose type and requiredness "
+        "both changed appears once.",
+    )
+    entries: list[BreakingChangeEntry] = Field(
+        description="Every single change with its grade and the old and new value.",
+    )
+    is_breaking: bool = Field(
+        description="Whether any detected change is classified as an error-level breaking change.",
+    )
+
+
 @app.post(
     "/changelog",
     tags=["changelog"],
@@ -935,6 +959,54 @@ async def changelog_endpoint(
         os.unlink(v2_path)
 
 
+@app.post(
+    "/breaking",
+    tags=["breaking"],
+    operation_id="breakingChangesDataContracts",
+    summary="Show compatibility impact between two data contracts.",
+    description="""
+Compare two versions of an ODCS data contract and detect backward-incompatible changes.
+
+`POST` a JSON body with `v1` (before) and `v2` (after) as YAML strings. A contract that cannot be
+parsed is answered with `422`.
+    """,
+    response_description="The breaking changes detected between the two data contracts.",
+    responses={
+        **AUTHENTICATION_RESPONSES,
+        422: {
+            "description": "One of the two data contracts is not valid YAML or not a valid data contract.",
+            "model": UnprocessableEntityResponse,
+            "content": {"application/json": {"example": {"detail": "Invalid YAML: while parsing a block mapping"}}},
+        },
+    },
+)
+def breaking_endpoint(
+    body: ChangelogRequest,
+    api_key: Annotated[str | None, Depends(api_key_header)] = None,
+) -> BreakingChangesResponse:
+    check_api_key(api_key)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f1:
+        f1.write(body.v1)
+        v1_path = f1.name
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f2:
+        f2.write(body.v2)
+        v2_path = f2.name
+
+    try:
+        result = DataContract(data_contract_file=v1_path).breaking(DataContract(data_contract_file=v2_path))
+        return BreakingChangesResponse(summary=result.summary, entries=result.entries, is_breaking=result.is_breaking)
+    except yaml.YAMLError as e:
+        raise HTTPException(status_code=422, detail=f"Invalid YAML: {e}")
+    except pydantic.ValidationError as e:
+        raise HTTPException(status_code=422, detail=f"Invalid data contract: {e}")
+    except DataContractException as e:
+        raise HTTPException(status_code=422, detail=f"Data Contract Validation Failure: {e}")
+    finally:
+        os.unlink(v1_path)
+        os.unlink(v2_path)
+
+
 @app.post(
     "/export",
     tags=["export"],

datacontract_cli-1.2.0/datacontract/breaking/detector.py

@@ -0,0 +1,101 @@
+from collections import defaultdict
+from collections.abc import Iterable
+
+from datacontract.breaking.rules import DEFAULT_RULES, BreakingChangeRule
+from datacontract.model.breaking import BreakingChangeEntry, BreakingChangeLevel, BreakingChangeResult
+from datacontract.model.changelog import ChangelogEntry, ChangelogResult, ChangelogType
+
+_LEVEL_ORDER = {
+    BreakingChangeLevel.INFO: 0,
+    BreakingChangeLevel.WARNING: 1,
+    BreakingChangeLevel.ERROR: 2,
+}
+
+
+class BreakingChangeDetector:
+    """Classify detailed changelog entries using an ordered rule set."""
+
+    def __init__(self, rules: Iterable[BreakingChangeRule] = DEFAULT_RULES):
+        self._rules = tuple(rules)
+        if not self._rules:
+            raise ValueError("At least one breaking-change rule is required")
+
+    def detect(self, changelog: ChangelogResult) -> BreakingChangeResult:
+        entries = [self._classify(entry) for entry in changelog.entries]
+        # Nothing inside a newly added element can break a consumer: it did not exist before.
+        added = {
+            entry.path
+            for entry in entries
+            if entry.change_type == ChangelogType.added
+            and (
+                entry.path.startswith("schema.")
+                and (len(entry.path.split(".")) == 2 or entry.path.split(".")[-2] == "properties")
+            )
+        }
+        removed_enums = {
+            entry.path
+            for entry in entries
+            if entry.change_type == ChangelogType.removed and entry.path.endswith(".enum")
+        }
+        # Stable IDs may change or swap without changing the set of allowed
+        # values. Match removed/updated values against additions in the same enum.
+        added_values = defaultdict(set)
+        for entry in entries:
+            if entry.rule_id == "enum-constraint-changed" and entry.path.endswith(".value"):
+                if entry.change_type in (ChangelogType.added, ChangelogType.updated):
+                    added_values[entry.path.rsplit(".enum.", 1)[0]].add(entry.new_value)
+        for entry in entries:
+            segments = entry.path.split(".")
+            if any(".".join(segments[:i]) in added for i in range(1, len(segments))):
+                entry.level = BreakingChangeLevel.INFO
+            if entry.rule_id == "enum-constraint-changed":
+                if any(entry.path.startswith(path + ".") for path in removed_enums):
+                    entry.level = BreakingChangeLevel.INFO
+                elif entry.path.endswith(".value") and entry.old_value in added_values.get(
+                    entry.path.rsplit(".enum.", 1)[0], set()
+                ):
+                    entry.level = BreakingChangeLevel.INFO
+        entries_by_prefix = defaultdict(list)
+        for entry in entries:
+            prefix = ""
+            for segment in entry.path.split("."):
+                prefix = f"{prefix}.{segment}" if prefix else segment
+                entries_by_prefix[prefix].append(entry)
+        summary = [self._summarize(entry, entries_by_prefix.get(entry.path, [])) for entry in changelog.summary]
+        return BreakingChangeResult(v1=changelog.v1, v2=changelog.v2, summary=summary, entries=entries)
+
+    def _classify(self, entry: ChangelogEntry) -> BreakingChangeEntry:
+        for rule in self._rules:
+            evaluation = rule.evaluate(entry)
+            if evaluation is not None:
+                return BreakingChangeEntry(
+                    path=entry.path,
+                    change_type=entry.type,
+                    level=evaluation.level,
+                    message=evaluation.message,
+                    rule_id=evaluation.rule_id,
+                    old_value=entry.old_value,
+                    new_value=entry.new_value,
+                )
+        raise ValueError(f"No breaking-change rule classified {entry.path}")
+
+    @staticmethod
+    def _summarize(summary_entry: ChangelogEntry, entries: list[BreakingChangeEntry]) -> BreakingChangeEntry:
+        if not entries:
+            return BreakingChangeEntry(
+                path=summary_entry.path,
+                change_type=summary_entry.type,
+                level=BreakingChangeLevel.INFO,
+                message=f"Changed contract at {summary_entry.path}",
+                rule_id="summary-fallback",
+            )
+        highest = max(entries, key=lambda entry: _LEVEL_ORDER[entry.level])
+        return BreakingChangeEntry(
+            path=summary_entry.path,
+            change_type=summary_entry.type,
+            level=highest.level,
+            message=f"{highest.level.value.capitalize()} impact at {summary_entry.path}",
+            rule_id=f"summary:{highest.rule_id}",
+            old_value=highest.old_value,
+            new_value=highest.new_value,
+        )

datacontract_cli-1.2.0/datacontract/breaking/rules.py

@@ -0,0 +1,235 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import date
+
+from datacontract.model.breaking import BreakingChangeLevel
+from datacontract.model.changelog import ChangelogEntry, ChangelogType
+
+
+@dataclass(frozen=True)
+class RuleEvaluation:
+    rule_id: str
+    level: BreakingChangeLevel
+    message: str
+
+
+class BreakingChangeRule(ABC):
+    rule_id: str
+
+    @abstractmethod
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        """Return a classification when this rule applies to ``entry``."""
+
+
+class SchemaRemovedRule(BreakingChangeRule):
+    rule_id = "schema-removed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        segments = entry.path.split(".")
+        if entry.type == ChangelogType.removed and len(segments) == 2 and segments[0] == "schema":
+            return RuleEvaluation(self.rule_id, BreakingChangeLevel.ERROR, f"Removed schema {segments[1]}")
+        return None
+
+
+class FieldRemovedRule(BreakingChangeRule):
+    rule_id = "field-removed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        segments = entry.path.split(".")
+        if entry.type != ChangelogType.removed or not _is_schema_property_path(segments):
+            return None
+        property_name = segments[-1]
+        return RuleEvaluation(self.rule_id, BreakingChangeLevel.ERROR, f"Removed property {property_name}")
+
+
+class RequiredChangedRule(BreakingChangeRule):
+    rule_id = "required-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.endswith(".required"):
+            return None
+        old = _parse_bool(entry.old_value)
+        new = _parse_bool(entry.new_value)
+        if entry.type == ChangelogType.added and new is True:
+            level = BreakingChangeLevel.ERROR
+        elif entry.type == ChangelogType.removed or new is False:
+            # Dropping the requirement, or writing out the optional default, only loosens the contract.
+            level = BreakingChangeLevel.INFO
+        elif entry.type == ChangelogType.updated and old is False and new is True:
+            level = BreakingChangeLevel.ERROR
+        elif entry.type in (ChangelogType.added, ChangelogType.updated):
+            level = BreakingChangeLevel.WARNING
+        else:
+            return None
+        return RuleEvaluation(self.rule_id, level, _change_message("requiredness", entry))
+
+
+class TypeChangedRule(BreakingChangeRule):
+    rule_id = "type-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.endswith((".logicalType", ".physicalType")):
+            return None
+        if entry.type == ChangelogType.updated:
+            level = BreakingChangeLevel.ERROR
+        elif entry.type == ChangelogType.added:
+            level = BreakingChangeLevel.INFO
+        elif entry.type == ChangelogType.removed:
+            level = BreakingChangeLevel.WARNING
+        else:
+            return None
+        return RuleEvaluation(self.rule_id, level, _change_message("type", entry))
+
+
+class UniqueConstraintRule(BreakingChangeRule):
+    rule_id = "unique-constraint-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.endswith(".unique"):
+            return None
+        old = _parse_bool(entry.old_value)
+        new = _parse_bool(entry.new_value)
+        if new is True and old is not True:
+            level = BreakingChangeLevel.ERROR
+        elif old is True and new is not True:
+            level = BreakingChangeLevel.INFO
+        else:
+            level = BreakingChangeLevel.WARNING
+        return RuleEvaluation(self.rule_id, level, _change_message("uniqueness", entry))
+
+
+class KeyConstraintRule(BreakingChangeRule):
+    rule_id = "key-constraint-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.endswith((".primaryKey", ".primary_key")):
+            return None
+        return RuleEvaluation(self.rule_id, BreakingChangeLevel.WARNING, _change_message("key constraint", entry))
+
+
+class ValidationConstraintRule(BreakingChangeRule):
+    rule_id = "validation-constraint-changed"
+    _suffixes = (
+        ".pattern",
+        ".minLength",
+        ".maxLength",
+        ".minimum",
+        ".maximum",
+        ".exclusiveMinimum",
+        ".exclusiveMaximum",
+    )
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.endswith(self._suffixes):
+            return None
+        old = _parse_number(entry.old_value)
+        new = _parse_number(entry.new_value)
+        if old is None or new is None:
+            level = BreakingChangeLevel.WARNING
+        elif _is_tightening(entry.path, old, new):
+            level = BreakingChangeLevel.ERROR
+        else:
+            level = BreakingChangeLevel.INFO
+        return RuleEvaluation(self.rule_id, level, _change_message("validation constraint", entry))
+
+
+class MetadataFallbackRule(BreakingChangeRule):
+    rule_id = "metadata-or-unknown-change"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation:
+        return RuleEvaluation(self.rule_id, BreakingChangeLevel.INFO, _change_message("contract", entry))
+
+
+class EnumConstraintRule(BreakingChangeRule):
+    rule_id = "enum-constraint-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.startswith("schema.") or ".properties." not in entry.path:
+            return None
+        if entry.path.endswith(".enum"):
+            level = BreakingChangeLevel.ERROR if entry.type == ChangelogType.added else BreakingChangeLevel.INFO
+        elif (
+            ".enum." in entry.path
+            and entry.path.endswith(".value")
+            and ".customProperties." not in entry.path.rsplit(".enum.", 1)[1]
+            and ".authoritativeDefinitions." not in entry.path.rsplit(".enum.", 1)[1]
+        ):
+            level = BreakingChangeLevel.INFO if entry.type == ChangelogType.added else BreakingChangeLevel.ERROR
+        else:
+            return None
+        return RuleEvaluation(self.rule_id, level, _change_message("allowed values", entry))
+
+
+class VectorShapeRule(BreakingChangeRule):
+    rule_id = "vector-shape-changed"
+
+    def evaluate(self, entry: ChangelogEntry) -> RuleEvaluation | None:
+        if not entry.path.startswith("schema.") or not entry.path.endswith(
+            (".logicalTypeOptions.dimensions", ".logicalTypeOptions.elementType")
+        ):
+            return None
+        if entry.path.endswith(".elementType"):
+            old = entry.old_value or "float32"
+            new = entry.new_value or "float32"
+            level = BreakingChangeLevel.INFO if old == new else BreakingChangeLevel.ERROR
+        else:
+            level = BreakingChangeLevel.WARNING if entry.type == ChangelogType.removed else BreakingChangeLevel.ERROR
+        return RuleEvaluation(self.rule_id, level, _change_message("vector shape", entry))
+
+
+def _is_schema_property_path(segments: list[str]) -> bool:
+    return len(segments) >= 3 and segments[0] == "schema" and segments[-2] == "properties"
+
+
+def _parse_bool(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if normalized in {"true", "1"}:
+        return True
+    if normalized in {"false", "0"}:
+        return False
+    return None
+
+
+def _parse_number(value: str | None) -> float | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    try:
+        return float(normalized)
+    except ValueError:
+        try:
+            return float(date.fromisoformat(normalized).toordinal())
+        except ValueError:
+            return None
+
+
+def _is_tightening(path: str, old: float, new: float) -> bool:
+    if path.endswith((".minLength", ".minimum", ".exclusiveMinimum")):
+        return new > old
+    if path.endswith((".maxLength", ".maximum", ".exclusiveMaximum")):
+        return new < old
+    return True
+
+
+def _change_message(subject: str, entry: ChangelogEntry) -> str:
+    if entry.type == ChangelogType.added:
+        return f"Added {subject} at {entry.path}"
+    if entry.type == ChangelogType.removed:
+        return f"Removed {subject} at {entry.path}"
+    return f"Changed {subject} at {entry.path} from {entry.old_value!r} to {entry.new_value!r}"
+
+
+DEFAULT_RULES: tuple[BreakingChangeRule, ...] = (
+    RequiredChangedRule(),
+    SchemaRemovedRule(),
+    FieldRemovedRule(),
+    TypeChangedRule(),
+    UniqueConstraintRule(),
+    KeyConstraintRule(),
+    ValidationConstraintRule(),
+    EnumConstraintRule(),
+    VectorShapeRule(),
+    MetadataFallbackRule(),
+)

{datacontract_cli-1.1.2 → datacontract_cli-1.2.0}/datacontract/changelog/normalize.py

@@ -44,6 +44,13 @@ Current hardcoded natural keys:
 schema[]                                SchemaObject   -> .name     (required: [name])
 schema[].properties[]                   SchemaProperty -> .name     (required: [name], recursive)
 slaProperties[]                          SLAProperty    -> .property
+slaProperties[].customProperties[]       CustomProperty -> .property
+slaProperties[].authoritativeDefinitions[] AuthoritativeDefinition -> .url
+schema[].properties[].enum[]             EnumValue      -> .value (or .id)
+schema[]/properties[].synonyms[]         Synonym        -> .synonym (or .id)
+schema[]/properties[].relationships[]    Relationship   -> .id, else from:to
+context.verifiedStatements[]             VerifiedStatement -> .question (or .id)
+context.constraints[]                    Constraint     -> .constraint (or .id)
 servers[]                                Server         -> .server
 servers[].roles[]                        Role           -> .role
 servers[].customProperties[]             CustomProperty -> .property
@@ -82,15 +89,41 @@ def _normalize_auth_defs(items: list[dict]) -> dict:
     return result
 
 
+def _normalize_keyed(items: list[dict], *keys: str) -> dict:
+    """Key a list of dicts by the first of ``keys`` an item carries, keeping the key in the value.
+
+    Falls back to the list index if none of the key fields is present.
+    """
+    result = {}
+    for i, item in enumerate(items):
+        key = next((str(item[k]) for k in keys if item.get(k) is not None), None) or f"__pos_{i}__"
+        result[key] = item
+    return result
+
+
+def _normalize_context(context) -> object:
+    """Key the lists of a context block; a plain-string context is returned unchanged."""
+    if not isinstance(context, dict):
+        return context
+    entry = dict(context)
+    if isinstance(entry.get("verifiedStatements"), list):
+        entry["verifiedStatements"] = _normalize_keyed(entry["verifiedStatements"], "id", "question")
+    if isinstance(entry.get("constraints"), list):
+        entry["constraints"] = _normalize_keyed(entry["constraints"], "id", "constraint")
+    return entry
+
+
 def _normalize_relationships(items: list[dict], schema_level: bool = True) -> dict:
-    """Key relationships by a stable composite key.
+    """Key relationships by their id (ODCS v3.2.0), else by a stable composite key.
 
     Schema-level: from:to composite. Property-level: to only.
     Falls back to positional index if key fields are absent.
     """
     result = {}
     for i, item in enumerate(items):
-        if schema_level:
+        if item.get("id"):
+            key = str(item["id"])
+        elif schema_level:
             from_val = str(item.get("from", ""))
             to_val = str(item.get("to", ""))
             key = f"{from_val}:{to_val}" if (from_val or to_val) else f"__pos_{i}__"
@@ -125,6 +158,12 @@ def _normalize_schema_fields(entry: dict, *, schema_level: bool) -> dict:
         entry["authoritativeDefinitions"] = _normalize_auth_defs(entry["authoritativeDefinitions"])
     if "relationships" in entry and isinstance(entry["relationships"], list):
         entry["relationships"] = _normalize_relationships(entry["relationships"], schema_level=schema_level)
+    if "synonyms" in entry and isinstance(entry["synonyms"], list):
+        entry["synonyms"] = _normalize_keyed(entry["synonyms"], "id", "synonym")
+    if "enum" in entry and isinstance(entry["enum"], list):
+        entry["enum"] = _normalize_keyed(entry["enum"], "id", "value")
+    if "context" in entry:
+        entry["context"] = _normalize_context(entry["context"])
     return entry
 
 
@@ -134,13 +173,30 @@ def _normalize_properties(properties: list[dict]) -> dict:
     for prop in properties:
         key = prop.get("name", prop.get("id", str(prop)))
         entry = {k: v for k, v in prop.items() if k != "name"}
-        if "properties" in entry and isinstance(entry["properties"], list):
-            entry["properties"] = _normalize_properties(entry["properties"])
+        entry = _normalize_property_children(entry)
         entry = _normalize_schema_fields(entry, schema_level=False)
         result[key] = entry
     return result
 
 
+def _normalize_property_children(entry: dict) -> dict:
+    """Recurse into the nested property definitions of a property: properties, items, map key and value."""
+    if "properties" in entry and isinstance(entry["properties"], list):
+        entry["properties"] = _normalize_properties(entry["properties"])
+    if isinstance(entry.get("items"), dict):
+        entry["items"] = _normalize_schema_fields(
+            _normalize_property_children(dict(entry["items"])), schema_level=False
+        )
+    if isinstance(entry.get("map"), dict):
+        entry["map"] = {
+            side: _normalize_schema_fields(_normalize_property_children(dict(definition)), schema_level=False)
+            if isinstance(definition, dict)
+            else definition
+            for side, definition in entry["map"].items()
+        }
+    return entry
+
+
 def normalize(contract: dict) -> dict:
     """Convert named lists to dicts keyed by their natural key field.
 
@@ -161,7 +217,16 @@ def normalize(contract: dict) -> dict:
         out["schema"] = normalized_schema
 
     if "slaProperties" in out and isinstance(out["slaProperties"], list):
-        out["slaProperties"] = _normalize_by(out["slaProperties"], "property")
+        sla_properties = _normalize_by(out["slaProperties"], "property")
+        for entry in sla_properties.values():
+            if isinstance(entry.get("customProperties"), list):
+                entry["customProperties"] = _normalize_by(entry["customProperties"], "property")
+            if isinstance(entry.get("authoritativeDefinitions"), list):
+                entry["authoritativeDefinitions"] = _normalize_auth_defs(entry["authoritativeDefinitions"])
+        out["slaProperties"] = sla_properties
+
+    if "context" in out:
+        out["context"] = _normalize_context(out["context"])
 
     if "servers" in out and isinstance(out["servers"], list):
         normalized_servers = {}