django-structured-metaobjects 1.0.0__py2.py3-none-any.whl

django_structured_metaobjects-1.0.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: django-structured-metaobjects
+Version: 1.0.0
+Summary: User-defined typed JSON objects for Django, powered by django-structured-json-field
+Author-email: Lotrèk <gabriele.baldi.01@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/bnznamco/django-structured-metaobjects
+Keywords: django,pydantic,django pydantic,json schema,meta models,dynamic models
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: django-structured-json-field>=1.5.1
+Requires-Dist: djangorestframework<4.0.0,>=3.14.0
+Requires-Dist: pydantic>=2.12
+Dynamic: license-file
+
+[![Test](https://github.com/bnznamco/django-structured-metaobjects/actions/workflows/ci.yml/badge.svg)](https://github.com/bnznamco/django-structured-metaobjects/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/django-structured-metaobjects.svg)](https://pypi.org/project/django-structured-metaobjects/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+# django-structured-metaobjects
+
+User-defined, typed JSON objects for Django — built on top of
+[`django-structured-json-field`](https://github.com/bnznamco/django-structured-field).
+
+Editors define **meta types** in the admin (a list of typed field
+definitions). Each `MetaInstance` then picks one of those types and the
+admin form / REST API automatically adapts to the schema declared by the
+chosen type.
+
+## Features
+
+- Field kinds: primitives, `ref` (single FK), `queryset` (list of FKs),
+  `group` (nested object), `list` (repeating group), with optional
+  `translated=True` per-field.
+- Runtime Pydantic compiler with per-MetaType caching, invalidated on save.
+- Admin form rebuilds the `data` widget for the selected meta type.
+- DRF `MetaTypeViewSet` / `MetaInstanceViewSet` with `schema/` action.
+- Typed access on `instance.obj.<field>` returning the parsed Pydantic
+  model — FK / queryset fields lazily resolve to real Django objects
+  with structured-json-field's caching.
+
+## Install
+
+```bash
+pip install django-structured-metaobjects
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "structured",
+    "structured_metaobjects",
+]
+```
+
+Wire the REST endpoints into your router:
+
+```python
+from rest_framework import routers
+from structured_metaobjects.views import MetaTypeViewSet, MetaInstanceViewSet
+
+router = routers.DefaultRouter()
+router.register(r"meta-types", MetaTypeViewSet, "meta-types")
+router.register(r"meta-instances", MetaInstanceViewSet, "meta-instances")
+```
+
+## Field kinds
+
+| kind       | Python type built by the compiler          | Notes                                  |
+|------------|--------------------------------------------|----------------------------------------|
+| `string`   | `str`                                      |                                        |
+| `text`     | `str`                                      | Multi-line.                            |
+| `integer`  | `int`                                      |                                        |
+| `number`   | `float`                                    |                                        |
+| `boolean`  | `bool`                                     |                                        |
+| `date`     | `datetime.date`                            |                                        |
+| `datetime` | `datetime.datetime`                        |                                        |
+| `ref`      | `<TargetModel>`                            | Requires `target_model="app.Model"`.   |
+| `queryset` | `List[<TargetModel>]`                      | Requires `target_model="app.Model"`.   |
+| `group`    | nested Pydantic model from `children`      |                                        |
+| `list`     | `List[<group model>]` from `children`      |                                        |
+
+Setting `translated=True` wraps the field in `Dict[str, T]` so the value
+is a per-language map.
+
+## Typed access
+
+```python
+instance = MetaInstance.objects.get(pk=1)
+obj = instance.obj                # cached Pydantic instance
+obj.title                         # typed string
+obj.related_page                  # real Django model instance (lazy/cached)
+obj.gallery                       # list of real Django model instances
+```

django_structured_metaobjects-1.0.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+django_structured_metaobjects-1.0.0.dist-info/licenses/LICENSE,sha256=qzxvcwVOx03-Kys8GRn_AtC5ZXv1HzJzliG9LkhVgqE,1081
+structured_metaobjects/__init__.py,sha256=5bRrmvCAWgEXUP3L0cpjMPpQOzmIGV5OMavydl0nDlw,366
+structured_metaobjects/admin.py,sha256=w_YBYEQxg_YcYx_FSmd-8B_mi4JJQOaZPyg-GMh0gBc,508
+structured_metaobjects/apps.py,sha256=Tgvm2-LHJN_ywyr96GWqAYmzdzrrFAc54EB5E0jyzws,254
+structured_metaobjects/compiler.py,sha256=ABdDSNxhoKPirI1tOcKhNHtx07n7YuuX1kVpQbwcS4g,5261
+structured_metaobjects/forms.py,sha256=GZYXeOzVj97IeGyuWVe3nUJRz-tqvivga6HVhO6J9ns,1304
+structured_metaobjects/models.py,sha256=Q_KayvIWKKnUDmt5i1r6RVzCI2W5Rmv-MDTsd752eIc,3729
+structured_metaobjects/schema_builder.py,sha256=vtQgzIYZyoFCHFd09znqUSZIhQ5TnwbaaXjd97OHLpQ,6108
+structured_metaobjects/serializers.py,sha256=9_81rDABUKwYVhu5paPuP5Ve7SxS81x5h8-yv9I4SJM,1210
+structured_metaobjects/urls.py,sha256=7psHWKIdcHCCKVHIVfzG3tytDiRobsexjYhMC4Je_uY,355
+structured_metaobjects/views.py,sha256=G1OurMs9JIsX4yk50drciYz5s5xWRWvUvxphwqn-Y8A,1331
+structured_metaobjects/migrations/0001_initial.py,sha256=fPypcHYYvi35SkHOYZlY-vDQ1ho5f9N1NUrY8nbOJFQ,2353
+structured_metaobjects/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+structured_metaobjects/static/structured_metaobjects/admin/meta_instance.js,sha256=5dIlPtUvYMLaiyVhjoAxUl4ImNInLzZateWfF4oMTXg,780
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_admin.py,sha256=UTNq77PWv1jh31QuHwlWQzwnvn_hDPhrfnkrNUewQTA,857
+tests/test_compiler.py,sha256=LN-oXTw5Jfc-1J2xt51xI90p0cze7gAMxIwkwMUtq8s,16830
+tests/test_forms.py,sha256=5XYUxIaI5rV8FJxmbWw6a9Dn4iEB34vxrt3q5EmDb1I,1126
+tests/test_models.py,sha256=2XhmmCF55yuadRfleHMLmo5BdIsWblteh5IUbe9nojg,7188
+tests/test_schema_builder.py,sha256=pXV8-pvGf2sKdOP2kkEEedL4pMKavtBh_3DnTujRwPo,2626
+tests/test_serializers.py,sha256=wALzWGlgLVzTzI4R32OplQXMwWSlowN9HeWheIHvPfc,2280
+tests/test_views.py,sha256=rrUZJ_VjHbRg1mXRiWorKd_29rsd10T6TZcz2CPXBz4,3851
+tests/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/app/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/app/app/asgi.py,sha256=Khb37ClvAOJtS2aYrRXQymK4aHNPeNuLQGXWAgBV88c,172
+tests/app/app/settings.py,sha256=Wy6Nc6JEmfGrA6V0RPUGVriIPHRufVGVhiWENmCVLwc,2184
+tests/app/app/urls.py,sha256=iZ_z3gQeHdHeSl1hdEy_h_jc_EGzPmGfEFSXzbPc_bY,433
+tests/app/app/wsgi.py,sha256=XcI10xhFKshbQm3aGOCRuo4JF5ylfdskewI_qQAKU4I,172
+tests/app/test_module/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/app/test_module/admin.py,sha256=FNZL7j2juUh1WyR_WKS8ASy49p75jOyG8bEtiO5qiVU,155
+tests/app/test_module/apps.py,sha256=uNVLDfJrenNGg8_uRHnKOH_72WxftHw_pHP1a9EBuIk,222
+tests/app/test_module/models.py,sha256=WD7uLVfPYiLa6LhadXCwWth3fxRUyX_GOR4U81HDxSM,271
+tests/app/test_module/serializers.py,sha256=Xms82D2NMp-2ovXxi-5oUil9I3X04RRIa_T5Z-GPGcQ,182
+tests/app/test_module/views.py,sha256=Yeumwat3XeS96T4cmqX9yMAJ6hCII8uX4c9MOVyoN9I,218
+tests/app/test_module/migrations/0001_initial.py,sha256=DWEkIhNn9Mhy1ay2q0LwaLd0DMYBXUaaH9Cmt94JByU,572
+tests/app/test_module/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_structured_metaobjects-1.0.0.dist-info/METADATA,sha256=zfFpkgKRMkIhdwdbpWxvjFYUdxlLO_UsKeo79gfJTxo,4986
+django_structured_metaobjects-1.0.0.dist-info/WHEEL,sha256=TdQ5LtNwLuxTCjgxN51AgdU5w-KkB9ttmLbzjTH02pg,109
+django_structured_metaobjects-1.0.0.dist-info/top_level.txt,sha256=222iEaFc3Gp3fX_NYXkQTX01ixlL5ejqWhb2EamK49Y,29
+django_structured_metaobjects-1.0.0.dist-info/RECORD,,

django_structured_metaobjects-1.0.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

django_structured_metaobjects-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Gabriele Baldi 2026
+
+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.

django_structured_metaobjects-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+structured_metaobjects
+tests

structured_metaobjects/__init__.py

@@ -0,0 +1,14 @@
+from .schema_builder import MetaFieldKind, MetaTypeFieldDef
+from .compiler import build_pydantic_model, clear_cache, get_json_schema
+
+__version__ = "1.0.0"
+
+default_app_config = "structured_metaobjects.apps.StructuredMetaobjectsConfig"
+
+__all__ = [
+    "MetaFieldKind",
+    "MetaTypeFieldDef",
+    "build_pydantic_model",
+    "clear_cache",
+    "get_json_schema",
+]

structured_metaobjects/admin.py

@@ -0,0 +1,20 @@
+from django.contrib import admin
+
+from .forms import MetaInstanceForm
+from .models import MetaInstance, MetaType
+
+
+@admin.register(MetaType)
+class MetaTypeAdmin(admin.ModelAdmin):
+    list_display = ("name",)
+
+
+@admin.register(MetaInstance)
+class MetaInstanceAdmin(admin.ModelAdmin):
+    form = MetaInstanceForm
+    list_display = ("__str__", "meta_type", "updated_at")
+    list_filter = ("meta_type",)
+    search_fields = ()
+
+    class Media:
+        js = ("structured_metaobjects/admin/meta_instance.js",)

structured_metaobjects/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class StructuredMetaobjectsConfig(AppConfig):
+    name = "structured_metaobjects"
+    label = "structured_metaobjects"
+    verbose_name = "Structured Meta Objects"
+    default_auto_field = "django.db.models.AutoField"

structured_metaobjects/compiler.py

@@ -0,0 +1,161 @@
+"""
+Runtime Pydantic model compiler for MetaType definitions.
+
+A MetaType stores a list of MetaTypeFieldDef rows. At runtime we walk
+that list and build a ``structured.pydantic.BaseModel`` subclass that
+mirrors the declared shape. The resulting class can be:
+
+- handed to ``structured.widget.fields.StructuredJSONFormField`` so the
+  admin renders the JSON-schema editor for it,
+- used to validate / serialize ``MetaInstance.data``,
+- introspected (``model_json_schema()``) by the REST API for frontends.
+
+Compiled models are cached per ``(meta_type_id, compiled_at)`` so saves
+on the MetaType invalidate the cache automatically.
+"""
+
+from datetime import date, datetime
+from typing import Dict, List, Optional, Tuple, Type
+
+from django.apps import apps
+from pydantic import Field, create_model
+from structured.pydantic.fields import ForeignKey, QuerySet
+from structured.pydantic.models import BaseModel
+
+from .schema_builder import MetaFieldKind, MetaTypeFieldDef
+
+
+_cache: Dict[Tuple[int, str], Type[BaseModel]] = {}
+
+
+def clear_cache(meta_type_id: Optional[int] = None) -> None:
+    if meta_type_id is None:
+        _cache.clear()
+        return
+    for key in [k for k in _cache if k[0] == meta_type_id]:
+        _cache.pop(key, None)
+
+
+_PRIMITIVE_TYPES = {
+    MetaFieldKind.string: str,
+    MetaFieldKind.html: str,
+    MetaFieldKind.number: float,
+    MetaFieldKind.boolean: bool,
+    MetaFieldKind.date: date,
+    MetaFieldKind.datetime: datetime,
+    MetaFieldKind.select: str,
+}
+
+
+def _resolve_ref_model(target_model):
+    if not target_model or "." not in target_model:
+        raise ValueError(
+            f"MetaType ref/queryset field requires target_model as 'app.Model', "
+            f"got {target_model!r}"
+        )
+    app_label, model_name = target_model.split(".", 1)
+    return apps.get_model(app_label, model_name)
+
+
+def _field_type(field_def: MetaTypeFieldDef, model_name_hint: str):
+    kind = field_def.kind
+    if kind == MetaFieldKind.number and field_def.integer:
+        return int
+    if kind in _PRIMITIVE_TYPES:
+        return _PRIMITIVE_TYPES[kind]
+    if kind == MetaFieldKind.ref:
+        return ForeignKey[_resolve_ref_model(field_def.target_model)]
+    if kind == MetaFieldKind.queryset:
+        return QuerySet[_resolve_ref_model(field_def.target_model)]
+    if kind == MetaFieldKind.group:
+        return _build_group_model(
+            field_def.children, f"{model_name_hint}__{field_def.name}"
+        )
+    if kind == MetaFieldKind.list:
+        item_model = _build_group_model(
+            field_def.children, f"{model_name_hint}__{field_def.name}_item"
+        )
+        return List[item_model]
+    raise ValueError(f"Unknown MetaType field kind: {kind!r}")
+
+
+def _json_schema_extra(fdef: MetaTypeFieldDef) -> dict:
+    """Build JSON Schema extra properties from the field definition."""
+    extra = {}
+    kind = fdef.kind
+
+    # Format hints
+    if kind == MetaFieldKind.string and fdef.multiline:
+        extra["format"] = "textarea"
+    if kind == MetaFieldKind.html:
+        extra["format"] = "html"
+
+    # Select choices
+    if kind == MetaFieldKind.select and fdef.choices:
+        extra["oneOf"] = [
+            {"const": c.value, "title": c.label} for c in fdef.choices
+        ]
+
+    # String constraints
+    if kind == MetaFieldKind.string:
+        if fdef.max_length is not None:
+            extra["maxLength"] = fdef.max_length
+        if fdef.min_length is not None:
+            extra["minLength"] = fdef.min_length
+
+    # Placeholder
+    if kind in (MetaFieldKind.string, MetaFieldKind.html) and fdef.placeholder:
+        extra["placeholder"] = fdef.placeholder
+
+    # Number constraints
+    if kind == MetaFieldKind.number:
+        if fdef.minimum is not None:
+            extra["minimum"] = fdef.minimum
+        if fdef.maximum is not None:
+            extra["maximum"] = fdef.maximum
+
+    return extra
+
+
+def _build_group_model(
+    fields: List[MetaTypeFieldDef], model_name: str
+) -> Type[BaseModel]:
+    field_specs: dict = {}
+    for fdef in fields:
+        if isinstance(fdef, dict):
+            fdef = MetaTypeFieldDef.model_validate(fdef)
+        py_type = _field_type(fdef, model_name)
+        if fdef.translated:
+            py_type = Dict[str, py_type]
+        json_extra = _json_schema_extra(fdef)
+        if fdef.required:
+            default = Field(..., json_schema_extra=json_extra or None)
+        else:
+            py_type = Optional[py_type]
+            default = Field(default=None, json_schema_extra=json_extra or None)
+        field_specs[fdef.name] = (py_type, default)
+
+    return create_model(  # type: ignore[call-overload]
+        model_name,
+        __base__=BaseModel,
+        **field_specs,
+    )
+
+
+def build_pydantic_model(meta_type) -> Type[BaseModel]:
+    """
+    Build (or fetch from cache) the runtime Pydantic model for a MetaType.
+    """
+    cache_key = (meta_type.pk, str(meta_type.compiled_at or ""))
+    cached = _cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    fields = list(meta_type.schema or [])
+    model_cls = _build_group_model(fields, f"MetaType_{meta_type.pk}")
+    _cache[cache_key] = model_cls
+    return model_cls
+
+
+def get_json_schema(meta_type) -> dict:
+    return build_pydantic_model(meta_type).model_json_schema()

structured_metaobjects/forms.py

@@ -0,0 +1,36 @@
+from django import forms
+from structured.widget.fields import StructuredJSONFormField
+
+from .models import MetaInstance, MetaType
+
+
+class MetaInstanceForm(forms.ModelForm):
+    """
+    Rebuild the ``data`` form field as a ``StructuredJSONFormField`` whose
+    schema is the runtime Pydantic model compiled from the chosen
+    ``MetaType``. The selected meta type is taken from the bound instance
+    or — when adding — from ``initial`` / submitted data.
+    """
+
+    class Meta:
+        model = MetaInstance
+        fields = "__all__"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        meta_type = None
+        if self.instance and self.instance.pk:
+            meta_type = self.instance.meta_type
+        else:
+            initial_mt = self.initial.get("meta_type") or self.data.get("meta_type")
+            if initial_mt:
+                meta_type = MetaType.objects.filter(pk=initial_mt).first()
+        if meta_type is not None:
+            schema_cls = meta_type.get_pydantic_model()
+            self.fields["data"] = StructuredJSONFormField(
+                schema=schema_cls, required=False
+            )
+        else:
+            self.fields["data"].help_text = (
+                "Select a meta type and save to start editing the data."
+            )

structured_metaobjects/migrations/0001_initial.py

@@ -0,0 +1,73 @@
+import django.db.models.deletion
+import structured.fields
+from django.db import migrations, models
+
+import structured_metaobjects.schema_builder
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="MetaType",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("name", models.CharField(max_length=200)),
+                (
+                    "schema",
+                    structured.fields.StructuredJSONField(
+                        default=list,
+                        schema=structured_metaobjects.schema_builder.MetaTypeFieldDef,
+                    ),
+                ),
+                ("compiled_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "verbose_name": "meta type",
+                "verbose_name_plural": "meta types",
+                "ordering": ("name",),
+            },
+        ),
+        migrations.CreateModel(
+            name="MetaInstance",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("data", models.JSONField(blank=True, default=dict)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "meta_type",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="instances",
+                        to="structured_metaobjects.metatype",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "meta instance",
+                "verbose_name_plural": "meta instances",
+                "ordering": ("-updated_at",),
+            },
+        ),
+    ]

structured_metaobjects/models.py

@@ -0,0 +1,103 @@
+from django.core.exceptions import ValidationError
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+from structured.fields import StructuredJSONField
+
+from . import compiler as meta_compiler
+from .schema_builder import MetaTypeFieldDef
+
+
+class MetaType(models.Model):
+    """
+    A user-defined "type" describing the shape of a ``MetaInstance``.
+
+    The ``schema`` field is a list of ``MetaTypeFieldDef`` rows declared
+    by an editor in the admin (string, ref, group, list, ...). When the
+    MetaType is saved, the runtime Pydantic compiler cache is invalidated
+    so any MetaInstance form/serializer using it picks up the new shape.
+    """
+
+    name = models.CharField(max_length=200)
+    schema = StructuredJSONField(default=list, schema=MetaTypeFieldDef)
+    compiled_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        app_label = "structured_metaobjects"
+        verbose_name = _("meta type")
+        verbose_name_plural = _("meta types")
+        ordering = ("name",)
+
+    def __str__(self) -> str:
+        return self.name
+
+    def save(self, *args, **kwargs):
+        super().save(*args, **kwargs)
+        meta_compiler.clear_cache(self.pk)
+
+    def get_pydantic_model(self):
+        return meta_compiler.build_pydantic_model(self)
+
+    def get_json_schema(self) -> dict:
+        return meta_compiler.get_json_schema(self)
+
+
+class MetaInstance(models.Model):
+    """
+    Concrete entry whose shape is dictated by its referenced ``MetaType``.
+
+    ``data`` is stored as a plain ``JSONField`` because ``StructuredJSONField``
+    needs its schema at class load time. We validate ``data`` against the
+    runtime Pydantic model built from ``meta_type`` in :meth:`clean` (and
+    at the serializer level for the API).
+    """
+
+    meta_type = models.ForeignKey(
+        MetaType, on_delete=models.PROTECT, related_name="instances"
+    )
+    data = models.JSONField(default=dict, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        app_label = "structured_metaobjects"
+        verbose_name = _("meta instance")
+        verbose_name_plural = _("meta instances")
+        ordering = ("-updated_at",)
+
+    def __str__(self) -> str:
+        return f"{self.meta_type} #{self.pk}"
+
+    @property
+    def obj(self):
+        """
+        Return ``data`` parsed into the runtime Pydantic model derived from
+        ``meta_type``. Field access on the returned object benefits from
+        ``django-structured-json-field`` semantics — typed attributes plus
+        cached lazy DB lookups for ``ref``/``queryset`` fields — without
+        forcing a static schema on the underlying ``JSONField``.
+
+        The parsed object is cached on the instance and invalidated whenever
+        the raw ``data`` dict is reassigned.
+        """
+        if self.meta_type_id is None:
+            return None
+        cached = getattr(self, "_obj_cache", None)
+        if cached is not None and cached[0] is self.data:
+            return cached[1]
+        model_cls = self.meta_type.get_pydantic_model()
+        raw = self.data or {}
+        model_cls._cache_engine.build_cache(raw)
+        parsed = model_cls.model_validate(raw)
+        self._obj_cache = (self.data, parsed)
+        return parsed
+
+    def clean(self):
+        super().clean()
+        if self.meta_type_id is None:
+            return
+        model_cls = self.meta_type.get_pydantic_model()
+        try:
+            validated = model_cls.model_validate(self.data or {})
+        except Exception as exc:  # pydantic ValidationError
+            raise ValidationError({"data": str(exc)})
+        self.data = validated.model_dump(mode="json")