pyfect-dev 0.1.0__py3-none-any.whl

pyfect/json_schema/_draft07.py

@@ -0,0 +1,203 @@
+"""Draft-07 to Draft 2020-12 and back."""
+
+from __future__ import annotations
+
+from pyfect.json_schema._converter import Context, convert_schema
+from pyfect.json_schema._keywords import (
+    ANCHOR_REGEXP,
+    JSON_SCHEMA_SINGLE_KEYWORDS,
+    MISSING,
+    contains_cardinality,
+    convert_dependencies,
+    convert_legacy_id,
+    convert_meta_schema_keyword,
+    convert_reference,
+    convert_subschema_keyword,
+    convert_tuple,
+)
+from pyfect.json_schema._model import (
+    META_SCHEMA_URI_DRAFT_07,
+    META_SCHEMA_URI_DRAFT_2020_12,
+    JsonSchema,
+    as_array,
+    as_object,
+    is_array,
+    is_meta_schema_uri,
+    is_object,
+    reject_keyword_collisions,
+    unsupported,
+)
+
+_PRE_2020_TO_2020_COLLISIONS = (
+    "$anchor",
+    "$defs",
+    "$dynamicAnchor",
+    "$dynamicRef",
+    "$vocabulary",
+    "contentSchema",
+    "dependentRequired",
+    "dependentSchemas",
+    "maxContains",
+    "minContains",
+    "prefixItems",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+)
+DRAFT_07_TO_2020_COLLISIONS = (*_PRE_2020_TO_2020_COLLISIONS, "deprecated")
+OPEN_API_30_TO_2020_COLLISIONS = (
+    *_PRE_2020_TO_2020_COLLISIONS,
+    "$comment",
+    "$id",
+    "$schema",
+    "const",
+    "contains",
+    "contentEncoding",
+    "contentMediaType",
+    "else",
+    "examples",
+    "if",
+    "patternProperties",
+    "propertyNames",
+    "then",
+)
+
+
+def from_draft_07(root: JsonSchema) -> JsonSchema:
+    return convert_schema(root, _from_draft_07, track_ids=True, ignore_ref_siblings=True)
+
+
+def _from_draft_07(source: JsonSchema, context: Context) -> JsonSchema:
+    out: JsonSchema = {}
+    reference = source.get("$ref")
+    if isinstance(reference, str):
+        # Draft-07 ignores the siblings of a ``$ref``, but keeps its definitions.
+        context.reference(out, reference)
+        if "definitions" in source:
+            out["$defs"] = context.schema_map(source["definitions"], "definitions", "$defs")
+        return out
+    reject_keyword_collisions(source, DRAFT_07_TO_2020_COLLISIONS, "Draft 2020-12", "Draft-07")
+    for key, value in source.items():
+        if convert_subschema_keyword(
+            out, key, value, context, single_keywords=JSON_SCHEMA_SINGLE_KEYWORDS
+        ):
+            continue
+        match key:
+            case "$schema":
+                out[key] = (
+                    META_SCHEMA_URI_DRAFT_2020_12
+                    if is_meta_schema_uri(value, META_SCHEMA_URI_DRAFT_07)
+                    else value
+                )
+            case "$id":
+                _convert_id(out, value)
+            case "definitions":
+                out["$defs"] = context.schema_map(value, key, "$defs")
+            case "dependencies":
+                _convert_dependencies(out, value, context)
+            case "items" | "additionalItems":
+                pass
+            case _:
+                out[key] = value
+    _convert_items(source, out, context)
+    return out
+
+
+def _convert_items(source: JsonSchema, out: JsonSchema, context: Context) -> None:
+    if "items" not in source:
+        return
+    items = source["items"]
+    if is_array(items):
+        out["prefixItems"] = context.schema_array(items, "items", "prefixItems")
+        if "additionalItems" in source:
+            out["items"] = context.schema(source["additionalItems"], "additionalItems", "items")
+    else:
+        out["items"] = context.schema(items, "items")
+
+
+def _convert_dependencies(out: JsonSchema, value: object, context: Context) -> None:
+    if not is_object(value):
+        out["dependencies"] = value
+        return
+    dependent_required: JsonSchema = {}
+    dependent_schemas: JsonSchema = {}
+    for dependency, dependency_value in as_object(value).items():
+        if is_array(dependency_value):
+            dependent_required[dependency] = dependency_value
+        else:
+            dependent_schemas[dependency] = context.schema_at(
+                dependency_value, ["dependencies", dependency], ["dependentSchemas", dependency]
+            )
+    if dependent_required:
+        out["dependentRequired"] = dependent_required
+    if dependent_schemas:
+        out["dependentSchemas"] = dependent_schemas
+
+
+def _convert_id(out: JsonSchema, value: object) -> None:
+    """A Draft-07 ``$id`` with a plain-name fragment is an ``$anchor``."""
+    if not isinstance(value, str) or "#" not in value:
+        out["$id"] = value
+        return
+    identifier, _, anchor = value.partition("#")
+    if not anchor:
+        if identifier:
+            out["$id"] = identifier
+        return
+    if not ANCHOR_REGEXP.fullmatch(anchor):
+        raise unsupported("$id", "Draft 2020-12", f'fragment "#{anchor}" is not a valid $anchor')
+    if identifier:
+        out["$id"] = identifier
+    out["$anchor"] = anchor
+
+
+_DRAFT_07_TARGET_COLLISIONS = ("additionalItems", "definitions", "dependencies")
+_NO_EQUIVALENT = frozenset(
+    {"$dynamicRef", "$dynamicAnchor", "$vocabulary", "unevaluatedProperties", "unevaluatedItems"}
+)
+
+_HANDLED_LATER = frozenset(
+    {
+        "$ref",
+        "$id",
+        "$anchor",
+        "dependentRequired",
+        "dependentSchemas",
+        "minContains",
+        "maxContains",
+        "prefixItems",
+        "items",
+    }
+)
+
+
+def to_draft_07(source: JsonSchema, context: Context) -> JsonSchema:
+    """The Draft-07 adapter for ``Converter``."""
+    reject_keyword_collisions(source, _DRAFT_07_TARGET_COLLISIONS, "Draft-07", "Draft 2020-12")
+    out: JsonSchema = {}
+    for key, value in source.items():
+        if convert_subschema_keyword(
+            out, key, value, context, single_keywords=JSON_SCHEMA_SINGLE_KEYWORDS
+        ):
+            continue
+        if key in _NO_EQUIVALENT:
+            raise unsupported(key, "Draft-07", "the target dialect has no equivalent")
+        if key in _HANDLED_LATER:
+            continue
+        match key:
+            case "$schema":
+                convert_meta_schema_keyword(
+                    out, value, context, META_SCHEMA_URI_DRAFT_07, "Draft-07"
+                )
+            case "$defs":
+                out["definitions"] = context.schema_map(value, key, "definitions")
+            case "required" if is_array(value) and len(as_array(value)) == 0:
+                pass
+            case _:
+                out[key] = value
+    convert_tuple(out, source.get("prefixItems", MISSING), source.get("items", MISSING), context)
+    if contains_cardinality(source, out, "Draft-07") and "minContains" in source:
+        out["minContains"] = source["minContains"]
+    convert_dependencies(source, out, context, "draft-07")
+    convert_legacy_id(source, out, "$id", "Draft-07")
+    convert_reference(out, source.get("$ref", MISSING), context)
+    return out

pyfect/json_schema/_keywords.py

@@ -0,0 +1,202 @@
+"""Keyword conversions shared by the dialect adapters."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Set
+from typing import Literal, cast
+
+from pyfect.json_schema._converter import Context
+from pyfect.json_schema._model import (
+    META_SCHEMA_URI_DRAFT_2020_12,
+    JsonSchema,
+    as_array,
+    as_object,
+    is_array,
+    is_meta_schema_uri,
+    is_number,
+    is_object,
+    unsupported,
+)
+
+SCHEMA_MAP_KEYWORDS = frozenset({"properties", "patternProperties"})
+SCHEMA_ARRAY_KEYWORDS = frozenset({"allOf", "anyOf", "oneOf"})
+JSON_SCHEMA_SINGLE_KEYWORDS = frozenset(
+    {
+        "not",
+        "additionalProperties",
+        "propertyNames",
+        "contains",
+        "if",
+        "then",
+        "else",
+        "contentSchema",
+    }
+)
+
+ANCHOR_REGEXP = re.compile(r"[A-Za-z_][-A-Za-z0-9._]*")
+LEGACY_ID_FRAGMENT_REGEXP = re.compile(r"[A-Za-z][-A-Za-z0-9._:]*")
+
+MISSING: object = object()
+"""A keyword the schema does not have (JavaScript's ``undefined``)."""
+
+
+def convert_subschema_keyword(
+    out: JsonSchema,
+    key: str,
+    value: object,
+    context: Context,
+    *,
+    single_keywords: Set[str],
+    map_keywords: Set[str] = SCHEMA_MAP_KEYWORDS,
+) -> bool:
+    """Convert ``key`` into ``out`` when it holds subschemas; ``False``
+    when it does not."""
+    if key in map_keywords:
+        out[key] = context.schema_map(value, key)
+    elif key in SCHEMA_ARRAY_KEYWORDS:
+        out[key] = context.schema_array(value, key)
+    elif key in single_keywords:
+        out[key] = context.schema(value, key)
+    else:
+        return False
+    return True
+
+
+def append_all_of(out: JsonSchema, schema: JsonSchema) -> None:
+    all_of = out.get("allOf")
+    if isinstance(all_of, list):
+        cast("list[object]", all_of).append(schema)
+    else:
+        out["allOf"] = [schema]
+
+
+def all_of_length(out: JsonSchema) -> int:
+    all_of = out.get("allOf")
+    return len(as_array(all_of)) if is_array(all_of) else 0
+
+
+def convert_meta_schema_keyword(
+    out: JsonSchema, value: object, context: Context, target_uri: str, target_dialect: str
+) -> None:
+    if context.is_document_root:
+        out["$schema"] = (
+            target_uri if is_meta_schema_uri(value, META_SCHEMA_URI_DRAFT_2020_12) else value
+        )
+    elif not is_meta_schema_uri(value, META_SCHEMA_URI_DRAFT_2020_12):
+        raise unsupported(
+            "$schema", target_dialect, "an embedded resource cannot declare a different dialect"
+        )
+
+
+def convert_tuple(out: JsonSchema, prefix_items: object, items: object, context: Context) -> None:
+    """Draft 2020-12's ``prefixItems`` / ``items`` as the legacy ``items`` /
+    ``additionalItems``."""
+    if prefix_items is MISSING:
+        if items is not MISSING:
+            out["items"] = context.schema(items, "items")
+        return
+    out["items"] = context.schema_array(prefix_items, "prefixItems", "items")
+    if items is not MISSING:
+        out["additionalItems"] = context.schema(items, "items", "additionalItems")
+
+
+def convert_reference(out: JsonSchema, reference: object, context: Context) -> None:
+    """A legacy dialect ignores ``$ref`` siblings, so a ``$ref`` next to other
+    keywords moves into ``allOf``."""
+    if reference is MISSING:
+        return
+    if isinstance(reference, str) and len(out) > 0:
+        reference_schema: JsonSchema = {}
+        context.reference(reference_schema, reference)
+        append_all_of(out, reference_schema)
+    else:
+        context.reference(out, reference)
+
+
+def convert_dependencies(
+    source: JsonSchema,
+    out: JsonSchema,
+    context: Context,
+    target_dialect: Literal["draft-04", "draft-07"],
+) -> None:
+    """``dependentRequired`` and ``dependentSchemas`` as ``dependencies``."""
+    required_map = source.get("dependentRequired")
+    schemas_map = source.get("dependentSchemas")
+    dependent_required: Mapping[str, object] | None = (
+        as_object(required_map) if is_object(required_map) else None
+    )
+    dependent_schemas: Mapping[str, object] | None = (
+        as_object(schemas_map) if is_object(schemas_map) else None
+    )
+    if dependent_required is None and dependent_schemas is None:
+        return
+    required_by: Mapping[str, object] = dependent_required or {}
+    schemas_by: Mapping[str, object] = dependent_schemas or {}
+    dependencies: JsonSchema = {}
+    keys: dict[str, None] = dict.fromkeys([*required_by, *schemas_by])
+    for key in keys:
+        required = required_by.get(key, MISSING)
+        dependency = schemas_by.get(key, MISSING)
+        omit_required = (
+            target_dialect == "draft-04" and is_array(required) and len(as_array(required)) == 0
+        )
+        if dependency is MISSING:
+            if not omit_required:
+                dependencies[key] = required
+        elif required is MISSING or omit_required:
+            dependencies[key] = context.schema_at(
+                dependency, ["dependentSchemas", key], ["dependencies", key]
+            )
+        else:
+            dependencies[key] = {
+                "allOf": [
+                    context.schema_at(
+                        dependency, ["dependentSchemas", key], ["dependencies", key, "allOf", "0"]
+                    ),
+                    {"required": required},
+                ]
+            }
+    if dependencies:
+        out["dependencies"] = dependencies
+
+
+def convert_legacy_id(
+    source: JsonSchema, out: JsonSchema, target_key: Literal["$id", "id"], dialect: str
+) -> None:
+    """``$id`` and ``$anchor`` as one legacy id (``#anchor`` for an anchor)."""
+    identifier = source.get("$id", MISSING)
+    anchor = source.get("$anchor", MISSING)
+    if anchor is MISSING:
+        if identifier is not MISSING:
+            out[target_key] = identifier
+        return
+    if not isinstance(anchor, str) or not ANCHOR_REGEXP.fullmatch(anchor):
+        raise unsupported("$anchor", dialect, "the anchor is not valid")
+    if not LEGACY_ID_FRAGMENT_REGEXP.fullmatch(anchor):
+        raise unsupported(
+            "$anchor",
+            dialect,
+            "the anchor cannot be represented as a plain-name fragment identifier",
+        )
+    if identifier is not MISSING:
+        raise unsupported("$anchor", dialect, "it cannot be combined with the schema $id")
+    out[target_key] = f"#{anchor}"
+
+
+def contains_cardinality(source: JsonSchema, out: JsonSchema, dialect: str) -> bool:
+    """Copy ``minContains`` / ``maxContains`` when there is no ``contains``
+    (they are inert then); with ``contains``, only the default cardinality
+    can be kept. ``True`` when ``contains`` is there."""
+    if "contains" not in source:
+        for key in ("minContains", "maxContains"):
+            if key in source:
+                out[key] = source[key]
+        return False
+    min_contains = source.get("minContains", MISSING)
+    default_min = min_contains is MISSING or (is_number(min_contains) and min_contains == 1)
+    if not default_min or "maxContains" in source:
+        raise unsupported(
+            "minContains/maxContains", dialect, "contains cardinality cannot be represented"
+        )
+    return True

pyfect/json_schema/_model.py

@@ -0,0 +1,201 @@
+"""The JSON Schema document types, meta-schema URIs and the walkers shared by
+the dialect converters."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Literal, TypeIs, cast
+
+from pyfect.json_pointer import parse_uri_fragment
+
+type JsonSchema = dict[str, object]
+"""One JSON Schema node: any keyword to any value."""
+
+type Definitions = dict[str, JsonSchema]
+"""Named schemas, referenced as ``#/$defs/<name>`` (Draft 2020-12),
+``#/definitions/<name>`` (Draft-04 and Draft-07) or
+``#/components/schemas/<name>`` (OpenAPI)."""
+
+type Dialect = Literal["draft-04", "draft-07", "draft-2020-12", "openapi-3.1", "openapi-3.0"]
+
+type Type = Literal["string", "number", "boolean", "array", "object", "null", "integer"]
+"""The JSON Schema ``type`` names."""
+
+
+@dataclass(frozen=True, slots=True)
+class Document[D: Dialect]:
+    """A root schema (without its definitions) and the definitions it
+    references, in one dialect."""
+
+    dialect: D
+    schema: JsonSchema
+    definitions: Definitions
+
+
+@dataclass(frozen=True, slots=True)
+class MultiDocument[D: Dialect]:
+    """Several root schemas sharing one set of definitions."""
+
+    dialect: D
+    schemas: tuple[JsonSchema, ...]
+    definitions: Definitions
+
+
+META_SCHEMA_URI_DRAFT_04 = "http://json-schema.org/draft-04/schema#"
+META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema#"
+META_SCHEMA_URI_DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+META_SCHEMA_URI_OPEN_API_3_1 = "https://spec.openapis.org/oas/3.1/dialect/base"
+
+VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP = re.compile(r"^[a-zA-Z0-9.\-_]+\Z")
+"""The keys OpenAPI allows under ``components.schemas``."""
+
+
+def is_object(value: object) -> bool:
+    """A JSON object (Effect's ``Predicate.isObject``)."""
+    return isinstance(value, Mapping)
+
+
+def as_object(value: object) -> Mapping[str, object]:
+    return cast("Mapping[str, object]", value)
+
+
+def is_array(value: object) -> bool:
+    return isinstance(value, list | tuple)
+
+
+def as_array(value: object) -> Sequence[object]:
+    return cast("Sequence[object]", value)
+
+
+def is_number(value: object) -> TypeIs[int | float]:
+    return isinstance(value, int | float) and not isinstance(value, bool)
+
+
+def is_meta_schema_uri(value: object, uri: str) -> bool:
+    """``value`` is ``uri``, with or without its trailing empty fragment."""
+    return value in (uri, uri[:-1] if uri.endswith("#") else f"{uri}#")
+
+
+def creates_resource(identifier: object) -> bool:
+    """An ``$id`` that starts a new schema resource (not a bare fragment)."""
+    return isinstance(identifier, str) and len(identifier) > 0 and identifier[0] != "#"
+
+
+def unsupported(keyword: str, dialect: str, details: str) -> ValueError:
+    return ValueError(f'Cannot convert JSON Schema keyword "{keyword}" to {dialect}: {details}')
+
+
+def reject_keyword_collisions(
+    source: Mapping[str, object], keywords: Sequence[str], target: str, origin: str
+) -> None:
+    """Raise for the first keyword of ``keywords`` in ``source``: inert in
+    the source dialect, it would gain a meaning in the target."""
+    for keyword in keywords:
+        if keyword in source:
+            raise unsupported(
+                keyword,
+                target,
+                f"it is not active in {origin} but would become active in the target",
+            )
+
+
+type SubschemaKind = Literal["schema", "map", "array"]
+
+_SUBSCHEMA_KINDS: dict[str, SubschemaKind] = {
+    "$defs": "map",
+    "properties": "map",
+    "patternProperties": "map",
+    "dependentSchemas": "map",
+    "allOf": "array",
+    "anyOf": "array",
+    "oneOf": "array",
+    "prefixItems": "array",
+    "not": "schema",
+    "additionalProperties": "schema",
+    "propertyNames": "schema",
+    "unevaluatedProperties": "schema",
+    "items": "schema",
+    "contains": "schema",
+    "unevaluatedItems": "schema",
+    "if": "schema",
+    "then": "schema",
+    "else": "schema",
+    "contentSchema": "schema",
+}
+
+
+def subschema_kind(keyword: str) -> SubschemaKind | None:
+    """How a Draft 2020-12 keyword holds subschemas, if it does."""
+    return _SUBSCHEMA_KINDS.get(keyword)
+
+
+def map_object(
+    value: Mapping[str, object], f: Callable[[object, str], object]
+) -> dict[str, object]:
+    return {key: f(item, key) for key, item in value.items()}
+
+
+def transform_schema(node: object, transform: Callable[[JsonSchema, bool], None]) -> object:
+    """A copy of a Draft 2020-12 schema with ``transform(schema,
+    in_embedded_resource)`` run on every schema node, children first."""
+
+    def walk(node: object, inherited: bool, is_root: bool = False) -> object:
+        if not is_object(node):
+            return node
+        source = as_object(node)
+        in_embedded = inherited or (not is_root and creates_resource(source.get("$id")))
+        out: JsonSchema = {}
+        for key, value in source.items():
+            match subschema_kind(key):
+                case "map":
+                    out[key] = (
+                        map_object(as_object(value), lambda item, _: walk(item, in_embedded))
+                        if is_object(value)
+                        else value
+                    )
+                case "array":
+                    out[key] = (
+                        [walk(item, in_embedded) for item in as_array(value)]
+                        if is_array(value)
+                        else value
+                    )
+                case "schema":
+                    out[key] = walk(value, in_embedded)
+                case None:
+                    out[key] = value
+        transform(out, in_embedded)
+        return out
+
+    return walk(node, False, True)
+
+
+def rewrite_schema_ref(schema: JsonSchema, rewrite: Callable[[str, str], str]) -> None:
+    """Rewrite ``schema``'s ``$ref`` and ``$dynamicRef`` in place;
+    ``rewrite`` gets the reference and the keyword."""
+    for keyword in ("$ref", "$dynamicRef"):
+        reference = schema.get(keyword)
+        if isinstance(reference, str):
+            schema[keyword] = rewrite(reference, keyword)
+
+
+def rewrite_refs(schema: Mapping[str, object], rewrite: Callable[[str], str]) -> JsonSchema:
+    """A copy of ``schema`` with every ``$ref`` and ``$dynamicRef`` replaced
+    by ``rewrite(ref)``."""
+    return cast(
+        "JsonSchema",
+        transform_schema(schema, lambda node, _: rewrite_schema_ref(node, lambda r, _: rewrite(r))),
+    )
+
+
+def sanitize_open_api_components_schemas_key(key: str) -> str:
+    """``key`` with every character OpenAPI forbids in a
+    ``components.schemas`` key replaced by ``_`` (``"_"`` for ``""``)."""
+    return re.sub(r"[^a-zA-Z0-9._-]", "_", key) if key else "_"
+
+
+def get_reference_key(ref: str) -> str | None:
+    """The definition name of a ``#/$defs/<name>`` reference, else ``None``."""
+    path = parse_uri_fragment(ref) if ref.startswith("#") else None
+    return path[1] if path is not None and len(path) == 2 and path[0] == "$defs" else None