refactor: resource and extensions schemas must be defined in __schema__

Author: azmeuk

doc/changelog.rst

@@ -4,9 +4,19 @@ Changelog
 [0.x.x] - Unreleased
 --------------------
 
-Changed
+Added
 ^^^^^
-- Introduce a Path object to handle paths. :issue:`111`
+- Resources define their schema URN with a ``__schema__`` classvar instead of a ``schemas`` default value. :issue:`110`
+- Validation that the base schema is present in ``schemas`` during SCIM context validation.
+- Validation that extension schemas are known during SCIM context validation.
+
+Changed
+^^^^^^^
+- Introduce a :class:`~scim2_models.Path` object to handle paths. :issue:`111`
+
+Deprecated
+^^^^^^^^^^
+- Defining ``schemas`` with a default value is deprecated. Use ``__schema__ = URN("...")`` instead.
 
 [0.5.2] - 2026-01-22
 --------------------

doc/tutorial.rst

@@ -305,8 +305,8 @@ Use :class:`~scim2_models.ComplexAttribute` as base class for complex attributes
 
 .. code-block:: python
 
-    >>> from typing import Annotated, Optional, List
-    >>> from scim2_models import Resource, Returned, Mutability, ComplexAttribute
+    >>> from typing import Annotated, Optional
+    >>> from scim2_models import Resource, Returned, Mutability, ComplexAttribute, URN
     >>> from enum import Enum
 
     >>> class PetType(ComplexAttribute):
@@ -317,7 +317,7 @@ Use :class:`~scim2_models.ComplexAttribute` as base class for complex attributes
     ...     """The pet color."""
 
     >>> class Pet(Resource):
-    ...     schemas: List[str] = ["example:schemas:Pet"]
+    ...     __schema__ = URN("urn:example:schemas:Pet")
     ...
     ...     name: Annotated[Optional[str], Mutability.immutable, Returned.always]
     ...     """The name of the pet."""
@@ -351,18 +351,20 @@ This is useful for server implementations, so custom models or models provided b
 
 .. code-block:: python
 
+    >>> from scim2_models import Resource, URN
+
     >>> class MyCustomResource(Resource):
     ...     """My awesome custom schema."""
     ...
-    ...     schemas: List[str] = ["example:schemas:MyCustomResource"]
+    ...     __schema__ = URN("urn:example:schemas:MyCustomResource")
     ...
     ...     foobar: Optional[str]
     ...
     >>> schema = MyCustomResource.to_schema()
     >>> dump = schema.model_dump()
     >>> assert dump == {
     ...     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
-    ...     "id": "example:schemas:MyCustomResource",
+    ...     "id": "urn:example:schemas:MyCustomResource",
     ...     "name": "MyCustomResource",
     ...     "description": "My awesome custom schema.",
     ...     "attributes": [

scim2_models/base.py

@@ -406,7 +406,9 @@ def _set_complex_attribute_urns(self) -> None:
             main_schema = self._attribute_urn
             separator = "."
         else:
-            main_schema = self.__class__.model_fields["schemas"].default[0]
+            main_schema = getattr(self.__class__, "__schema__", None)
+            if main_schema is None:
+                return
             separator = ":"
 
         for field_name in self.__class__.model_fields:
@@ -540,13 +542,12 @@ def get_attribute_urn(self, field_name: str) -> str:
         """
         from scim2_models.resources.resource import Extension
 
-        main_schema = self.__class__.model_fields["schemas"].default[0]
+        main_schema = getattr(self.__class__, "__schema__", None)
         field = self.__class__.model_fields[field_name]
         alias = field.serialization_alias or field_name
         field_type = self.get_field_root_type(field_name)
-        full_urn = (
-            alias
-            if isclass(field_type) and issubclass(field_type, Extension)
-            else f"{main_schema}:{alias}"
-        )
-        return full_urn
+        if isclass(field_type) and issubclass(field_type, Extension):
+            return alias
+        if main_schema is None:
+            return alias
+        return f"{main_schema}:{alias}"

scim2_models/messages/bulk.py

@@ -5,8 +5,8 @@
 from pydantic import Field
 from pydantic import PlainSerializer
 
-from ..annotations import Required
 from ..attributes import ComplexAttribute
+from ..path import URN
 from ..utils import _int_to_str
 from .message import Message
 
@@ -53,9 +53,7 @@ class BulkRequest(Message):
         The models for Bulk operations are defined, but their behavior is not implemented nor tested yet.
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:BulkRequest")
 
     fail_on_errors: int | None = None
     """An integer specifying the number of errors that the service provider
@@ -76,9 +74,7 @@ class BulkResponse(Message):
         The models for Bulk operations are defined, but their behavior is not implemented nor tested yet.
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:BulkResponse"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:BulkResponse")
 
     operations: list[BulkOperation] | None = Field(
         None, serialization_alias="Operations"

scim2_models/messages/error.py

@@ -2,17 +2,15 @@
 
 from pydantic import PlainSerializer
 
-from ..annotations import Required
+from ..path import URN
 from ..utils import _int_to_str
 from .message import Message
 
 
 class Error(Message):
     """Representation of SCIM API errors."""
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:Error"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:Error")
 
     status: Annotated[int | None, PlainSerializer(_int_to_str)] = None
     """The HTTP status code (see Section 6 of [RFC7231]) expressed as a JSON

scim2_models/messages/list_response.py

@@ -1,4 +1,3 @@
-from typing import Annotated
 from typing import Any
 from typing import Generic
 
@@ -9,17 +8,15 @@
 from pydantic_core import PydanticCustomError
 from typing_extensions import Self
 
-from ..annotations import Required
 from ..context import Context
+from ..path import URN
 from ..resources.resource import AnyResource
 from .message import Message
 from .message import _GenericMessageMetaclass
 
 
 class ListResponse(Message, Generic[AnyResource], metaclass=_GenericMessageMetaclass):
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:ListResponse")
 
     total_results: int | None = None
     """The total number of results returned by the list or query operation."""

scim2_models/messages/message.py

@@ -7,11 +7,11 @@
 
 from pydantic import Discriminator
 from pydantic import Tag
-from pydantic._internal._model_construction import ModelMetaclass
 
 from scim2_models.resources.resource import Resource
 
 from ..base import BaseModel
+from ..scim_object import ScimMetaclass
 from ..scim_object import ScimObject
 from ..utils import UNION_TYPES
 
@@ -56,7 +56,7 @@ def _get_tag(resource_type: type[BaseModel]) -> Tag:
     :param resource_type: SCIM resource type
     :return: Pydantic Tag for discrimination
     """
-    return Tag(resource_type.model_fields["schemas"].default[0])
+    return Tag(getattr(resource_type, "__schema__", None) or "")
 
 
 def _create_tagged_resource_union(resource_union: Any) -> Any:
@@ -75,7 +75,7 @@ def _create_tagged_resource_union(resource_union: Any) -> Any:
 
     # Set up schemas for the discriminator function
     resource_types_schemas = [
-        resource_type.model_fields["schemas"].default[0]
+        getattr(resource_type, "__schema__", None) or ""
         for resource_type in resource_types
     ]
 
@@ -92,7 +92,7 @@ def _create_tagged_resource_union(resource_union: Any) -> Any:
     return Annotated[union, discriminator]
 
 
-class _GenericMessageMetaclass(ModelMetaclass):
+class _GenericMessageMetaclass(ScimMetaclass):
     """Metaclass for SCIM generic types with discriminated unions."""
 
     def __new__(

scim2_models/messages/patch_op.py

@@ -15,6 +15,7 @@
 from ..annotations import Required
 from ..attributes import ComplexAttribute
 from ..context import Context
+from ..path import URN
 from ..path import InvalidPathError
 from ..path import Path
 from ..path import PathNotFoundError
@@ -199,9 +200,7 @@ def __class_getitem__(
 
         return super().__class_getitem__(typevar_values)
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:PatchOp")
 
     operations: Annotated[list[PatchOperation[ResourceT]] | None, Required.true] = (
         Field(None, serialization_alias="Operations", min_length=1)

scim2_models/messages/search_request.py

@@ -1,11 +1,10 @@
 from enum import Enum
-from typing import Annotated
 from typing import Any
 
 from pydantic import field_validator
 from pydantic import model_validator
 
-from ..annotations import Required
+from ..path import URN
 from ..path import Path
 from .message import Message
 
@@ -16,9 +15,7 @@ class SearchRequest(Message):
     https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.3
     """
 
-    schemas: Annotated[list[str], Required.true] = [
-        "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
-    ]
+    __schema__ = URN("urn:ietf:params:scim:api:messages:2.0:SearchRequest")
 
     attributes: list[Path[Any]] | None = None
     """A multi-valued list of strings indicating the names of resource

scim2_models/path.py

@@ -68,7 +68,17 @@ class _Resolution(NamedTuple):
     is_explicit_schema_path: bool = False
 
 
-class URN(UserString):
+class URN(str):
+    """URN string type with validation.
+
+    Inherits from str directly so it can be used anywhere a str is expected,
+    including as argument to str.startswith(), dict keys, etc.
+    """
+
+    def __new__(cls, urn: str) -> "URN":
+        cls.check_syntax(urn)
+        return super().__new__(cls, urn)
+
     @classmethod
     def __get_pydantic_core_schema__(
         cls,
@@ -83,10 +93,6 @@ def __get_pydantic_core_schema__(
             ),
         )
 
-    def __init__(self, urn: str):
-        self.check_syntax(urn)
-        self.data = urn
-
     @classmethod
     def check_syntax(cls, path: str) -> None:
         """Validate URN-based path format.
@@ -330,7 +336,7 @@ def urn(self) -> str | None:
 
         schema = self.schema
         if not schema and issubclass(self.__scim_model__, Resource):
-            schema = self.__scim_model__.model_fields["schemas"].default[0]
+            schema = self.__scim_model__.__schema__
 
         if not self.attr:
             return schema if schema else None
@@ -348,12 +354,12 @@ def _resolve_model(self) -> tuple[type[BaseModel], str | None] | None:
         attr_path = self.attr
 
         if ":" in self and isclass(model) and issubclass(model, Resource | Extension):
-            model_schema = model.model_fields["schemas"].default[0]
+            model_schema = model.__schema__
             path_lower = str(self).lower()
 
-            if path_lower == model_schema.lower():
+            if model_schema and path_lower == model_schema.lower():
                 return model, None
-            elif path_lower.startswith(model_schema.lower()):
+            elif model_schema and path_lower.startswith(model_schema.lower()):
                 attr_path = str(self)[len(model_schema) :].lstrip(":")
             elif issubclass(model, Resource):
                 for (
@@ -414,7 +420,7 @@ def _resolve_instance(
         if ":" not in path_str:
             return _Resolution(resource, path_str)
 
-        model_schema = type(resource).model_fields["schemas"].default[0]
+        model_schema = str(getattr(type(resource), "__schema__", ""))
         path_lower = path_str.lower()
 
         if isinstance(resource, Resource | Extension) and path_lower.startswith(
@@ -708,10 +714,11 @@ def iter_model_paths(
 
                 field_type = target_model.get_field_root_type(field_name)
 
+                urn: str
                 if isclass(field_type) and issubclass(field_type, Extension):
                     if not include_extensions:
                         continue
-                    urn = field_type.model_fields["schemas"].default[0]
+                    urn = field_type.__schema__ or ""
                 elif isclass(target_model) and issubclass(target_model, Extension):
                     urn = target_model().get_attribute_urn(field_name)
                 else: