schematalog-core 0.1.0__tar.gz

schematalog_core-0.1.0/.gitignore

@@ -0,0 +1,234 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+BUILD_NUMBER/
+develop-eggs/
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*-coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+test-reports/
+
+# Various testing files
+.mutmut-cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# lock files
+#   According to pypa/pipenv#598, it is recommended to include the lock file in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+Pipfile.lock
+poetry.lock
+requirements.txt
+requirements.in
+pdm.lock
+# uv.lock
+
+# other tools
+.pdm-python
+.pdm-build
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# PyCharm stuff
+.idea
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Editor workspace files
+.vscode
+
+.testmondata
+
+# macOS
+.DS_Store
+
+# Docker stuff for local dev
+docker-compose.override.yml
+
+.skip-hooks
+
+tmp/
+.ruff_cache
+
+# run configurations
+.run/
+/.run/
+
+# kube manifest
+helm/baked_manifest.yaml
+
+# local storage
+_storage
+storage_
+database.json
+
+# localstack files
+volume/
+
+# HTML rendering files
+schematalog/presentation/webapp/static/pico/
+
+# frontend toolchain
+# Path-independent: a `frontend/` prefix stopped matching when the frontend moved
+# into its package, and 1816 files went into the index before anyone noticed.
+**/node_modules/
+# Vite build output (regenerated by `just build-fe`; built fresh in the Docker image)
+packages/schematalog-app/schematalog/app/presentation/webapp/static/dist/
+
+# depscan report
+reports/
+
+# complexipy
+.complexipy_cache/
+
+profile.stats
+
+# logfire
+.logfire/
+
+# AI files
+CLAUDE.md
+.claude/
+# Point-in-time analysis written for the 2026-08-14 strategy conversation, at commit
+# e511be0. Describes the pre-pivot world in the present tense, so it is kept local
+# rather than published; what outlived it lives in DECISIONS.md and ROADMAP.md.
+DIRECTION-ANALYSIS.md
+
+

schematalog_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Berislav Lopac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schematalog_core-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: schematalog-core
+Version: 0.1.0
+Summary: The Schematalog domain contract and its conformance suite.
+Project-URL: Homepage, https://schematalog.com
+Project-URL: Documentation, https://schematalog.com
+Project-URL: Source, https://github.com/berislavlopac/schematalog
+Author-email: Berislav Lopac <berislav@lopac.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: ~=3.14.0
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: sanitary>=0.2.1
+Requires-Dist: unclogger>=0.2.2
+Provides-Extra: testing
+Requires-Dist: pytest>=8.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# schematalog-core
+
+The domain contract for [Schematalog](https://schematalog.com), a registry and catalog
+for JSON Schema specifications — and the conformance suite that goes with it.
+
+**This is what a storage backend codes against.** It deliberately does not depend on the
+registry application, so implementing a backend does not oblige you to install a web
+framework.
+
+```shell
+pip install schematalog-core[testing]
+```
+
+## Writing a storage backend
+
+A backend implements five methods — `add`, `get`, `set_metadata`, `list_versions` and
+`list_names`. Three more (`get_latest`, `list_latest`, `list_predecessors`) are derived
+for you by `SchemaRepository`, including the rule for which version counts as *latest*,
+so you inherit that rather than reimplementing it. Override them only if your store can
+answer them better.
+
+The contract is written as tests. Subclass it, supply one fixture yielding an empty
+repository, and it tells you whether your backend is correct:
+
+```python
+import pytest
+from schematalog.testing import SchemaRepositoryConformance
+
+class TestMyBackend(SchemaRepositoryConformance):
+    @pytest.fixture
+    def repository(self):
+        return MyRepository(...)
+```
+
+Registration is a `schematalog.storage` entry point naming the URL scheme you answer to;
+nothing in the registry needs changing. See
+[`schematalog-s3`](https://pypi.org/project/schematalog-s3/) for a complete worked
+example.
+
+## What it contains
+
+- `schematalog.domain` — `Schema`, `SchemaRepository`, the value objects and errors.
+- `schematalog.testing` — the conformance suite and a sample schema to test with.
+- `schematalog.common` — layer-neutral helpers, including a dependency-free JSON Schema
+  ↔ Avro converter.

schematalog_core-0.1.0/README.md

@@ -0,0 +1,45 @@
+# schematalog-core
+
+The domain contract for [Schematalog](https://schematalog.com), a registry and catalog
+for JSON Schema specifications — and the conformance suite that goes with it.
+
+**This is what a storage backend codes against.** It deliberately does not depend on the
+registry application, so implementing a backend does not oblige you to install a web
+framework.
+
+```shell
+pip install schematalog-core[testing]
+```
+
+## Writing a storage backend
+
+A backend implements five methods — `add`, `get`, `set_metadata`, `list_versions` and
+`list_names`. Three more (`get_latest`, `list_latest`, `list_predecessors`) are derived
+for you by `SchemaRepository`, including the rule for which version counts as *latest*,
+so you inherit that rather than reimplementing it. Override them only if your store can
+answer them better.
+
+The contract is written as tests. Subclass it, supply one fixture yielding an empty
+repository, and it tells you whether your backend is correct:
+
+```python
+import pytest
+from schematalog.testing import SchemaRepositoryConformance
+
+class TestMyBackend(SchemaRepositoryConformance):
+    @pytest.fixture
+    def repository(self):
+        return MyRepository(...)
+```
+
+Registration is a `schematalog.storage` entry point naming the URL scheme you answer to;
+nothing in the registry needs changing. See
+[`schematalog-s3`](https://pypi.org/project/schematalog-s3/) for a complete worked
+example.
+
+## What it contains
+
+- `schematalog.domain` — `Schema`, `SchemaRepository`, the value objects and errors.
+- `schematalog.testing` — the conformance suite and a sample schema to test with.
+- `schematalog.common` — layer-neutral helpers, including a dependency-free JSON Schema
+  ↔ Avro converter.

schematalog_core-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "schematalog-core"
+dynamic = ["version"]
+description = "The Schematalog domain contract and its conformance suite."
+authors = [{ name = "Berislav Lopac", email = "berislav@lopac.net" }]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing",
+]
+requires-python = "~=3.14.0"
+# Deliberately small. This is what a storage backend codes against, so anything added
+# here is added to every backend author's environment - which is why the SQLAlchemy
+# column types live with the backend that uses them rather than here.
+dependencies = [
+    "jsonschema>=4.23.0",
+    "pydantic>=2.9.0",
+    "sanitary>=0.2.1",
+    "unclogger>=0.2.2",
+]
+
+[project.optional-dependencies]
+# The conformance suite is importable test code; pytest is needed only by those running it.
+testing = ["pytest>=8.0"]
+
+[tool.deptry]
+known_first_party = ["schematalog"]
+
+[project.urls]
+Homepage = "https://schematalog.com"
+Documentation = "https://schematalog.com"
+Source = "https://github.com/berislavlopac/schematalog"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "schematalog/domain/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["schematalog"]
+# The sample schema is data the published test support reads at runtime, not a fixture
+# left behind in the source tree.
+artifacts = ["schematalog/testing/example_schema.json"]

schematalog_core-0.1.0/schematalog/common/__init__.py

@@ -0,0 +1 @@
+"""Layer-neutral utilities shared across the application (no dependency on other layers)."""

schematalog_core-0.1.0/schematalog/common/avroform/__init__.py

@@ -0,0 +1,15 @@
+"""Convert between JSON Schema and Apache Avro schemas.
+
+A small, dependency-free converter covering the common subset of JSON Schema:
+objects/records, primitives, arrays, enums, nullable fields (unions), nested
+records, string formats that map to Avro logical types, and internal ``$ref``
+pointers (``#/$defs/...``, inlined before conversion). Constructs with no clean Avro
+equivalent (``oneOf``/``anyOf``/``allOf``, external or recursive ``$ref``) raise
+:class:`AvroConversionError` rather than emitting an invalid schema.
+"""
+
+from .exceptions import AvroConversionError
+from .to_avro import to_avro
+from .to_json_schema import to_json_schema
+
+__all__ = ["AvroConversionError", "to_avro", "to_json_schema"]

schematalog_core-0.1.0/schematalog/common/avroform/exceptions.py

@@ -0,0 +1,2 @@
+class AvroConversionError(Exception):
+    """Raised when a schema cannot be converted between JSON Schema and Avro."""

schematalog_core-0.1.0/schematalog/common/avroform/to_avro.py

@@ -0,0 +1,208 @@
+"""JSON Schema -> Avro schema."""
+
+import re
+from typing import Any
+
+from .exceptions import AvroConversionError
+
+AvroType = str | dict[str, Any] | list[Any]
+
+# JSON Schema primitive `type` -> Avro primitive type.
+_PRIMITIVES = {
+    "boolean": "boolean",
+    "integer": "long",
+    "number": "double",
+    "null": "null",
+}
+
+# JSON Schema string `format` -> (Avro base type, Avro logicalType).
+_STRING_FORMATS = {
+    "date": ("int", "date"),
+    "time": ("int", "time-millis"),
+    "date-time": ("long", "timestamp-millis"),
+    "uuid": ("string", "uuid"),
+}
+
+# JSON Schema keywords we cannot faithfully express in Avro. (`$ref` is handled
+# separately: internal pointers are inlined before conversion, see `_resolve_refs`.)
+_UNSUPPORTED = ("oneOf", "anyOf", "allOf", "not")
+
+
+def to_avro(
+    json_schema: dict[str, Any], *, name: str = "Record", namespace: str = ""
+) -> AvroType:
+    """Convert a JSON Schema into an Avro schema.
+
+    Args:
+        json_schema: The JSON Schema to convert.
+        name: Name for the root Avro record/enum (a schema ``title`` overrides it).
+        namespace: Optional Avro namespace for named types.
+
+    Returns:
+        The Avro schema as a JSON-compatible structure.
+
+    Raises:
+        AvroConversionError: If the schema uses unsupported constructs.
+    """
+    return _convert(_resolve_refs(json_schema, json_schema, ()), name, namespace, set())
+
+
+def _resolve_refs(schema: Any, root: dict, stack: tuple[str, ...]) -> Any:
+    """Inline internal ``$ref`` pointers (``#/...``) against the document root.
+
+    Avro has no reference mechanism, so a fragment ref is expanded in place before
+    conversion - e.g. ``{"$ref": "#/$defs/country"}`` becomes the ``country`` subschema.
+    External refs (anything not ``#/...``) and cyclic refs cannot be expressed and raise.
+    """
+    if isinstance(schema, list):
+        return [_resolve_refs(item, root, stack) for item in schema]
+    if not isinstance(schema, dict):
+        return schema
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        return _resolve_ref(schema, ref, root, stack)
+    return {key: _resolve_refs(value, root, stack) for key, value in schema.items()}
+
+
+def _resolve_ref(schema: dict, ref: str, root: dict, stack: tuple[str, ...]) -> Any:
+    """Expand a single ``$ref`` node, overlaying any sibling keys onto the target."""
+    if not ref.startswith("#/"):
+        raise AvroConversionError(f"Cannot resolve external $ref: {ref!r}.")
+    if ref in stack:
+        raise AvroConversionError(f"Cannot express recursive $ref in Avro: {ref!r}.")
+    target = _resolve_refs(_deref(ref, root), root, (*stack, ref))
+    # JSON Schema allows keys beside `$ref`; overlay them onto the resolved object.
+    siblings = {key: value for key, value in schema.items() if key != "$ref"}
+    if siblings and isinstance(target, dict):
+        return {**target, **_resolve_refs(siblings, root, stack)}
+    return target
+
+
+def _deref(ref: str, root: dict) -> Any:
+    """Resolve a ``#/a/b`` JSON Pointer against ``root`` (with ~0/~1 unescaping)."""
+    node: Any = root
+    for raw in ref[2:].split("/"):  # drop the leading '#/'
+        token = raw.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or token not in node:
+            raise AvroConversionError(f"Cannot resolve $ref: {ref!r}.")
+        node = node[token]
+    return node
+
+
+def _convert(schema: Any, name: str, namespace: str, seen: set[str]) -> AvroType:
+    if not isinstance(schema, dict):
+        raise AvroConversionError(f"Expected a schema object, got {type(schema).__name__}.")
+    for keyword in _UNSUPPORTED:
+        if keyword in schema:
+            raise AvroConversionError(f"Unsupported JSON Schema keyword: {keyword!r}.")
+
+    if "enum" in schema:
+        return _enum(schema, name, namespace, seen)
+
+    json_type = schema.get("type")
+    if isinstance(json_type, list):
+        return _union(json_type, schema, name, namespace, seen)
+    if json_type == "object":
+        return _object(schema, name, namespace, seen)
+    if json_type == "array":
+        return _array(schema, name, namespace, seen)
+    if json_type == "string":
+        return _string(schema)
+    if json_type in _PRIMITIVES:
+        return _PRIMITIVES[json_type]
+    raise AvroConversionError(f"Unsupported or missing JSON Schema type: {json_type!r}.")
+
+
+def _object(schema: dict, name: str, namespace: str, seen: set[str]) -> AvroType:
+    additional = schema.get("additionalProperties")
+    if not schema.get("properties") and isinstance(additional, dict):
+        return {"type": "map", "values": _convert(additional, name, namespace, seen)}
+
+    record_name = _unique(_pascal(schema.get("title") or name), seen)
+    required = set(schema.get("required", []))
+    fields = []
+    for prop_name, prop_schema in schema.get("properties", {}).items():
+        field_type = _convert(prop_schema, prop_name, namespace, seen)
+        field: dict[str, Any] = {"name": prop_name, "type": field_type}
+        if isinstance(prop_schema, dict) and prop_schema.get("description"):
+            field["doc"] = prop_schema["description"]
+        if prop_name not in required:
+            field["type"] = _nullable(field_type)
+            field["default"] = None
+        fields.append(field)
+
+    record: dict[str, Any] = {"type": "record", "name": record_name, "fields": fields}
+    if namespace:
+        record["namespace"] = namespace
+    if schema.get("description"):
+        record["doc"] = schema["description"]
+    return record
+
+
+def _array(schema: dict, name: str, namespace: str, seen: set[str]) -> AvroType:
+    items = schema.get("items")
+    if not isinstance(items, dict):
+        raise AvroConversionError("Array schema must declare an 'items' object.")
+    return {"type": "array", "items": _convert(items, f"{_pascal(name)}Item", namespace, seen)}
+
+
+def _string(schema: dict) -> AvroType:
+    fmt = schema.get("format")
+    if isinstance(fmt, str) and fmt in _STRING_FORMATS:
+        base, logical = _STRING_FORMATS[fmt]
+        return {"type": base, "logicalType": logical}
+    return "string"
+
+
+def _enum(schema: dict, name: str, namespace: str, seen: set[str]) -> AvroType:
+    symbols = schema["enum"]
+    valid = all(isinstance(s, str) and _is_avro_name(s) for s in symbols)
+    if valid and len(set(symbols)) == len(symbols):
+        enum: dict[str, Any] = {
+            "type": "enum",
+            "name": _unique(_pascal(name), seen),
+            "symbols": list(symbols),
+        }
+        if namespace:
+            enum["namespace"] = namespace
+        return enum
+    # Enums Avro can't represent (non-string or non-identifier values) degrade to string.
+    return "string"
+
+
+def _union(types: list, schema: dict, name: str, namespace: str, seen: set[str]) -> AvroType:
+    base = {key: value for key, value in schema.items() if key not in ("type", "enum")}
+    parts: list[AvroType] = []
+    for json_type in types:
+        member = _convert({**base, "type": json_type}, name, namespace, seen)
+        if member not in parts:
+            parts.append(member)
+    # Avro convention: null first so a `null` default is valid.
+    if "null" in parts:
+        parts = ["null", *(part for part in parts if part != "null")]
+    return parts
+
+
+def _nullable(avro_type: AvroType) -> AvroType:
+    if isinstance(avro_type, list):
+        return avro_type if "null" in avro_type else ["null", *avro_type]
+    return ["null", avro_type]
+
+
+def _pascal(value: str) -> str:
+    parts = re.split(r"[^0-9a-zA-Z]+", value)
+    name = "".join(part[:1].upper() + part[1:] for part in parts if part)
+    return name or "Record"
+
+
+def _unique(name: str, seen: set[str]) -> str:
+    candidate, index = name, 1
+    while candidate in seen:
+        index += 1
+        candidate = f"{name}{index}"
+    seen.add(candidate)
+    return candidate
+
+
+def _is_avro_name(value: str) -> bool:
+    return bool(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", value))