modelable 1.0.0__py3-none-any.whl

modelable/emitters/json_schema.py

@@ -0,0 +1,458 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from jsonschema import Draft202012Validator
+
+from modelable.compiler.workspace import Workspace
+from modelable.emitters.base import EmittedArtifact, compute_content_hash
+from modelable.emitters.diagnostics import type_loss, validation_failed
+from modelable.governance.por import build_por_reference
+from modelable.parser.ir import (
+    AnnClassification,
+    AnnDeprecated,
+    AnnKey,
+    AnnOwner,
+    AnnPii,
+    AnnServer,
+    ArrayType,
+    ComputedMapping,
+    DecimalType,
+    DirectMapping,
+    DomainDef,
+    EnumType,
+    FieldDef,
+    MapType,
+    ModelVersion,
+    NamedType,
+    ObjectType,
+    PrimitiveType,
+    ProjectionField,
+    ProjectionVersion,
+    RefType,
+    VersionExact,
+    VersionMin,
+    VersionPinned,
+    VersionRange,
+)
+from modelable.registry.resolver import resolve_model_ref
+
+
+def emit_json_schema(workspace: Workspace, out_dir: Path) -> list[EmittedArtifact]:
+    """Emit JSON Schema 2020-12 artifacts for every model and projection version."""
+    artifacts: list[EmittedArtifact] = []
+    for domain in workspace.mdl.domains:
+        for model_name, versions in domain.models.items():
+            for version in versions:
+                artifact = _emit_model_version(domain, model_name, version, out_dir)
+                artifacts.append(artifact)
+
+        for projection_name, versions in domain.projections.items():
+            for version in versions:
+                artifact = _emit_projection_version(domain, projection_name, version, out_dir, workspace.mdl)
+                artifacts.append(artifact)
+    return artifacts
+
+
+def _artifact_id(domain: str, name: str, version: int) -> str:
+    return f"{domain}.{name}.v{version}"
+
+
+def _emit_model_version(domain: DomainDef, model_name: str, version: ModelVersion, out_dir: Path) -> EmittedArtifact:
+    artifact_id = _artifact_id(domain.name, model_name, version.version)
+    schema: dict = {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": artifact_id,
+        "type": "object",
+        "title": model_name,
+        "x-modelable": {
+            "domain": domain.name,
+            "name": model_name,
+            "kind": version.model_kind.value,
+            "version": version.version,
+            "changeKind": version.change_kind.value,
+        },
+        "x-modelable-por": build_por_reference(f"{domain.name}.{model_name}.v{version.version}"),
+    }
+    _add_domain_metadata(schema["x-modelable"], domain)
+
+    properties: dict[str, dict] = {}
+    required: list[str] = []
+    warnings: list[str] = []
+    defs: dict[str, dict] = {}
+
+    for field in version.fields:
+        prop = _field_to_json_schema(field, field.type, defs=defs, path=[field.name])
+        default_value = _field_default(field)
+        if default_value is not None:
+            prop["default"] = default_value
+        if isinstance(field.type, NamedType):
+            warnings.append(type_loss(field.type.name))
+        properties[field.name] = prop
+        if not field.optional:
+            required.append(field.name)
+
+    schema["properties"] = properties
+    if required:
+        schema["required"] = required
+    if defs:
+        schema["$defs"] = defs
+
+    path = out_dir / f"{artifact_id}.json"
+    artifact = EmittedArtifact(
+        target="json-schema",
+        ref=f"{domain.name}.{model_name}@{version.version}",
+        artifact_id=artifact_id,
+        path=path,
+        content=schema,
+        content_hash=compute_content_hash(schema),
+        warnings=warnings,
+    )
+
+    _validate_schema(artifact)
+    return artifact
+
+
+def _emit_projection_version(
+    domain: DomainDef,
+    projection_name: str,
+    version: ProjectionVersion,
+    out_dir: Path,
+    mdl,
+) -> EmittedArtifact:
+    artifact_id = _artifact_id(domain.name, projection_name, version.version)
+    schema: dict = {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": artifact_id,
+        "type": "object",
+        "title": projection_name,
+        "x-modelable": {
+            "domain": domain.name,
+            "name": projection_name,
+            "kind": "projection",
+            "version": version.version,
+            "source": {
+                "model": version.source.model,
+                "version": _version_spec_to_json(version.source.version),
+                "alias": version.source.alias,
+            },
+            "autoGenerated": version.auto_generated,
+        },
+        "x-modelable-por": build_por_reference(f"{domain.name}.{projection_name}.v{version.version}"),
+    }
+    _add_domain_metadata(schema["x-modelable"], domain)
+
+    if version.joins:
+        schema["x-modelable"]["joins"] = [
+            {
+                "model": join.model,
+                "version": _version_spec_to_json(join.version),
+                "alias": join.alias,
+                "on": join.on,
+            }
+            for join in version.joins
+        ]
+
+    if version.where:
+        schema["x-modelable"]["where"] = version.where
+
+    if version.group_by:
+        schema["x-modelable"]["groupBy"] = version.group_by
+
+    properties: dict[str, dict] = {}
+    required: list[str] = []
+    warnings: list[str] = []
+    defs: dict[str, dict] = {}
+
+    for field in version.fields:
+        field_type = _resolve_projection_field_type(field, version, mdl)
+        prop = _field_to_json_schema(field, field_type, defs=defs, path=[field.name])
+        if isinstance(field_type, NamedType):
+            warnings.append(type_loss(field_type.name))
+        _add_lineage(prop, field, version)
+        properties[field.name] = prop
+        # Projection fields are always required in the current IR (no ? syntax).
+        required.append(field.name)
+
+    schema["properties"] = properties
+    if required:
+        schema["required"] = required
+    if defs:
+        schema["$defs"] = defs
+
+    path = out_dir / f"{artifact_id}.json"
+    artifact = EmittedArtifact(
+        target="json-schema",
+        ref=f"{domain.name}.{projection_name}@{version.version}",
+        artifact_id=artifact_id,
+        path=path,
+        content=schema,
+        content_hash=compute_content_hash(schema),
+        warnings=warnings,
+    )
+
+    _validate_schema(artifact)
+    return artifact
+
+
+def _version_spec_to_json(version_spec) -> dict:
+    if isinstance(version_spec, VersionExact):
+        return {"kind": "exact", "version": version_spec.version}
+    if isinstance(version_spec, VersionRange):
+        return {
+            "kind": "range",
+            "minInclusive": version_spec.min_inclusive,
+            "maxExclusive": version_spec.max_exclusive,
+        }
+    if isinstance(version_spec, VersionMin):
+        return {"kind": "min", "minInclusive": version_spec.min_inclusive}
+    if isinstance(version_spec, VersionPinned):
+        return {
+            "kind": "pinned",
+            "version": version_spec.version,
+            "contentHash": version_spec.content_hash,
+        }
+    return {}
+
+
+def _field_default(field: FieldDef):
+    if field.default is None:
+        return None
+    raw = field.default.strip()
+    if isinstance(field.type, PrimitiveType):
+        if field.type.kind == "bool":
+            if raw == "true":
+                return True
+            if raw == "false":
+                return False
+        if field.type.kind in {"int"}:
+            try:
+                return int(raw)
+            except ValueError:
+                return raw
+        if field.type.kind in {"float"}:
+            try:
+                return float(raw)
+            except ValueError:
+                return raw
+    if len(raw) >= 2 and raw[0] == '"' and raw[-1] == '"':
+        return raw[1:-1]
+    return raw
+
+
+def _add_domain_metadata(container: dict, domain: DomainDef) -> None:
+    if domain.owner is not None:
+        container["owner"] = domain.owner
+    if domain.contact is not None:
+        container["contact"] = domain.contact
+    if domain.description is not None:
+        container["description"] = domain.description
+
+
+def _resolve_projection_field_type(
+    field: FieldDef,
+    projection: ProjectionVersion,
+    mdl,
+):
+    """Resolve the JSON Schema type for a projection field from its source model."""
+    if not isinstance(field.mapping, DirectMapping):
+        return None
+
+    # Find the source model version that matches the projection source.
+    source_fqn = projection.source.model
+    try:
+        source_domain, source_model = source_fqn.rsplit(".", 1)
+    except ValueError:
+        return None
+
+    try:
+        resolved = resolve_model_ref(mdl, f"{source_domain}.{source_model}", projection.source.version)
+    except LookupError:
+        return None
+    source_mv = resolved.version
+
+    for src_field in source_mv.fields:
+        if src_field.name == field.mapping.source_field:
+            return src_field.type
+
+    return None
+
+
+def _field_to_json_schema(
+    field: FieldDef, field_type=None, defs: dict[str, dict] | None = None, path: list[str] | None = None
+) -> dict:
+    prop = _type_to_json_schema(field_type, defs=defs, path=path) if field_type is not None else {}
+
+    wire_targets = field.wire_targets()
+    if wire_targets:
+        prop["x-modelable-wire"] = {target: _wire_hint_to_json(hint) for target, hint in sorted(wire_targets.items())}
+
+    for ann in field.annotations:
+        if isinstance(ann, AnnKey):
+            prop["x-modelable-field"] = {**(prop.get("x-modelable-field") or {}), "key": True}
+        elif isinstance(ann, AnnPii):
+            prop["x-modelable-field"] = {**(prop.get("x-modelable-field") or {}), "pii": True}
+        elif isinstance(ann, AnnClassification):
+            prop["x-modelable-classification"] = ann.level
+        elif isinstance(ann, AnnDeprecated):
+            prop["deprecated"] = True
+            prop["x-modelable-field"] = {
+                **(prop.get("x-modelable-field") or {}),
+                "replacedBy": ann.replaced_by,
+            }
+        elif isinstance(ann, AnnOwner):
+            prop["x-modelable-field"] = {
+                **(prop.get("x-modelable-field") or {}),
+                "owner": ann.team,
+            }
+        elif isinstance(ann, AnnServer):
+            prop["x-modelable-field"] = {
+                **(prop.get("x-modelable-field") or {}),
+                "server": True,
+            }
+
+    json_hint = wire_targets.get("json")
+    if (
+        json_hint is not None
+        and json_hint.encoding == "string"
+        and (
+            isinstance(field_type, (DecimalType,))
+            or (isinstance(field_type, PrimitiveType) and field_type.kind == "int")
+        )
+    ):
+        prop["type"] = "string"
+        prop.pop("format", None)
+
+    return prop
+
+
+def _type_to_json_schema(field_type, defs: dict[str, dict] | None = None, path: list[str] | None = None) -> dict:
+    if isinstance(field_type, PrimitiveType):
+        return _primitive_to_json_schema(field_type.kind)
+    if isinstance(field_type, DecimalType):
+        return {
+            "type": "string",
+            "pattern": r"^-?\d+(\.\d+)?$",
+            "x-modelable-field": {"decimalPrecision": field_type.precision, "decimalScale": field_type.scale},
+        }
+    if isinstance(field_type, ArrayType):
+        return {
+            "type": "array",
+            "items": _type_to_json_schema(field_type.item, defs=defs, path=path),
+        }
+    if isinstance(field_type, MapType):
+        return {
+            "type": "object",
+            "additionalProperties": _type_to_json_schema(field_type.value, defs=defs, path=path),
+        }
+    if isinstance(field_type, RefType):
+        return {
+            "type": "string",
+            "x-modelable-ref": field_type.target,
+        }
+    if isinstance(field_type, EnumType):
+        return {
+            "type": "string",
+            "enum": field_type.values,
+        }
+    if isinstance(field_type, NamedType):
+        def_name = _definition_name([field_type.name])
+        if defs is not None:
+            defs.setdefault(
+                def_name,
+                {
+                    "title": field_type.name,
+                    "type": "object",
+                    "x-modelable-field": {"namedType": field_type.name},
+                },
+            )
+            return {"$ref": f"#/$defs/{def_name}"}
+        return {
+            "type": "object",
+            "x-modelable-field": {"namedType": field_type.name},
+        }
+    if isinstance(field_type, ObjectType):
+        def_name = _definition_name(path or ["InlineObject"])
+        if defs is not None:
+            defs.setdefault(def_name, _object_type_to_json_schema(field_type, defs=defs, path=path))
+            return {"$ref": f"#/$defs/{def_name}"}
+        return _object_type_to_json_schema(field_type, defs=defs, path=path)
+
+    return {"type": "object"}
+
+
+def _object_type_to_json_schema(
+    field_type: ObjectType, defs: dict[str, dict] | None = None, path: list[str] | None = None
+) -> dict:
+    prop: dict = {"title": _definition_name(path or ["InlineObject"]), "type": "object"}
+    props: dict[str, dict] = {}
+    req: list[str] = []
+    for f in field_type.fields:
+        child_path = [*(path or []), f.name]
+        props[f.name] = _field_to_json_schema(f, f.type, defs=defs, path=child_path)
+        if not f.optional:
+            req.append(f.name)
+    prop["properties"] = props
+    if req:
+        prop["required"] = req
+    return prop
+
+
+def _definition_name(path: list[str]) -> str:
+    return "".join(_pascalize_part(part) for part in path if part)
+
+
+def _pascalize_part(value: str) -> str:
+    return value[:1].upper() + value[1:] if value else value
+
+
+def _primitive_to_json_schema(kind: str) -> dict:
+    mapping: dict[str, dict] = {
+        "string": {"type": "string"},
+        "bool": {"type": "boolean"},
+        "int": {"type": "integer", "format": "int64"},
+        "float": {"type": "number"},
+        "uuid": {"type": "string", "format": "uuid"},
+        "timestamp": {"type": "string", "format": "date-time"},
+        "date": {"type": "string", "format": "date"},
+        "time": {"type": "string", "format": "time"},
+        "duration": {"type": "string", "format": "duration"},
+        "binary": {"type": "string", "contentEncoding": "base64"},
+        "json": {},
+    }
+    return mapping.get(kind, {"type": "string"})
+
+
+def _add_lineage(prop: dict, field: ProjectionField, projection: ProjectionVersion) -> None:
+    mapping = field.mapping
+    if isinstance(mapping, DirectMapping):
+        prop["x-modelable-lineage"] = {
+            "kind": "direct",
+            "source": f"{mapping.source_alias}.{mapping.source_field}",
+            "sourceModel": projection.source.model,
+        }
+    elif isinstance(mapping, ComputedMapping):
+        prop["x-modelable-lineage"] = {
+            "kind": "computed",
+            "expression": mapping.expression,
+        }
+
+
+def _validate_schema(artifact: EmittedArtifact) -> None:
+    try:
+        Draft202012Validator.check_schema(artifact.content)
+    except Exception as exc:
+        artifact.warnings.append(validation_failed(str(artifact.path), str(exc)))
+
+
+def _wire_hint_to_json(hint) -> dict:
+    data: dict[str, object] = {}
+    if hint.encoding is not None:
+        data["encoding"] = hint.encoding
+    if hint.type is not None:
+        data["type"] = hint.type
+    if hint.case is not None:
+        data["case"] = hint.case
+    if hint.overrides:
+        data["overrides"] = {key: hint.overrides[key] for key in sorted(hint.overrides)}
+    return data