SAM Pydantic Base Classes

These are the base Pydantic models used as the foundations for all Smarter API Manifest (SAM) models.

Pydantic models for Smarter API Manifests.

pydantic model smarter.lib.manifest.models.AbstractSAMBase

Bases: SmarterBasePydanticModel, ABC

Abstract base class for all Smarter API Manifest (SAM) models.

This class serves as the foundational Pydantic model for representing Smarter API manifests. It is intended to be subclassed by concrete manifest classes that define specific resource types within the Smarter API ecosystem.

The AbstractSAMBase class provides a strongly-typed structure for manifest data, ensuring that all manifests adhere to a consistent schema and validation logic. It includes built-in validation for core manifest fields and supports structured access to manifest data.

Subclasses should implement or extend this class to define the specific data and behaviors required for their respective manifest types. This design promotes code reuse, type safety, and robust validation across all Smarter API manifests.

The class also provides methods for validating manifest data and for representing the manifest as a string for debugging or logging purposes.

Note

Do not instantiate this class directly. Instead, create subclasses that define the required fields and any additional validation or methods specific to your manifest type.

Show JSON schema

{
   "title": "AbstractSAMBase",
   "description": "Abstract base class for all Smarter API Manifest (SAM) models.\n\nThis class serves as the foundational Pydantic model for representing Smarter API manifests.\nIt is intended to be subclassed by concrete manifest classes that define specific resource types\nwithin the Smarter API ecosystem.\n\nThe ``AbstractSAMBase`` class provides a strongly-typed structure for manifest data, ensuring\nthat all manifests adhere to a consistent schema and validation logic. It includes built-in\nvalidation for core manifest fields and supports structured access to manifest data.\n\nSubclasses should implement or extend this class to define the specific data and behaviors\nrequired for their respective manifest types. This design promotes code reuse, type safety,\nand robust validation across all Smarter API manifests.\n\nThe class also provides methods for validating manifest data and for representing the manifest\nas a string for debugging or logging purposes.\n\n.. note::\n\n    Do not instantiate this class directly. Instead, create subclasses that define the\n    required fields and any additional validation or methods specific to your manifest type.",
   "type": "object",
   "properties": {
      "apiVersion": {
         "description": "apiVersion[String]: Required. The API version of the AbstractSAMBase.",
         "title": "Apiversion",
         "type": "string"
      },
      "kind": {
         "description": "kind[String]: Required. The kind of resource described by the manifest.",
         "title": "Kind",
         "type": "string"
      },
      "metadata": {
         "$ref": "#/$defs/AbstractSAMMetadataBase",
         "description": "metadata[obj]: Required. The manifest metadata."
      },
      "spec": {
         "$ref": "#/$defs/AbstractSAMSpecBase",
         "description": "spec[obj]: Required. The manifest specification."
      },
      "status": {
         "anyOf": [
            {
               "$ref": "#/$defs/AbstractSAMStatusBase"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "status[obj]: Optional. Read-only. The run-time state of the resource described by the manifest."
      }
   },
   "$defs": {
      "AbstractSAMMetadataBase": {
         "description": "Abstract base class for manifest metadata in the Smarter API.\n\nThis class defines the required structure and validation logic for metadata associated with\nSmarter API manifests. It is designed to be subclassed by concrete manifest metadata classes,\nwhich may extend or customize the metadata fields as needed for specific resource types.\n\nThe ``AbstractSAMMetadataBase`` enforces strong typing and validation for core metadata fields,\nsuch as resource name, description, version, tags, and annotations. It ensures that all metadata\nadheres to expected formats and constraints, promoting consistency and reliability across all\nmanifest definitions.\n\nSubclasses should inherit from this class to implement metadata for their specific manifest\ntypes. This approach encourages code reuse, enforces validation, and provides a unified\ninterface for working with manifest metadata throughout the Smarter API ecosystem.\n\n.. note::\n\n    This class is abstract and should not be instantiated directly. Instead, create subclasses\n    that define any additional fields or validation required for your manifest's metadata.",
         "properties": {
            "name": {
               "description": "The camelCase name of the manifest resource",
               "title": "Name",
               "type": "string"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The description for this resource. Be brief. Keep it under 255 characters.",
               "title": "Description"
            },
            "version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The semantic version of the manifest. Example: 0.1.0",
               "title": "Version"
            },
            "tags": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The tags of the manifest. Used for generic resource categorization and search. Example: ['tag1', 'tag2']",
               "title": "Tags"
            },
            "annotations": {
               "anyOf": [
                  {
                     "items": {
                        "additionalProperties": {
                           "anyOf": [
                              {
                                 "type": "string"
                              },
                              {
                                 "type": "integer"
                              },
                              {
                                 "type": "number"
                              },
                              {
                                 "type": "boolean"
                              },
                              {
                                 "format": "date",
                                 "type": "string"
                              },
                              {
                                 "format": "date-time",
                                 "type": "string"
                              },
                              {
                                 "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                                 "type": "string"
                              },
                              {
                                 "format": "uuid",
                                 "type": "string"
                              },
                              {
                                 "format": "binary",
                                 "type": "string"
                              },
                              {
                                 "items": {},
                                 "type": "array"
                              },
                              {
                                 "additionalProperties": true,
                                 "type": "object"
                              }
                           ]
                        },
                        "type": "object"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The manifest annotations. Used for storing arbitrary metadata as\n            key-value pairs. Example: [{'smarter.sh/test-manifest/project-name': 'Scooby dooby do'}]. The\n            key should be a valid url-friendly string. The value accepts\n            multi-line string values (YAML block scalars) and various scalar types including\n            str, int, float, bool, datetime.date, datetime.datetime, decimal.Decimal, uuid.UUID, bytes, list, dict.\n            ",
               "title": "Annotations"
            }
         },
         "required": [
            "name",
            "description",
            "version"
         ],
         "title": "AbstractSAMMetadataBase",
         "type": "object"
      },
      "AbstractSAMSpecBase": {
         "description": "Pydantic Spec base class. Expected to be subclassed by specific manifest classes.",
         "properties": {},
         "title": "AbstractSAMSpecBase",
         "type": "object"
      },
      "AbstractSAMStatusBase": {
         "description": "Pydantic Status base class. Expected to be subclassed by specific manifest classes.",
         "properties": {
            "recordLocator": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "recordLocator[String]: An optional identifier used to locate the resource record associated with this manifest. Read only.",
               "title": "Recordlocator"
            },
            "created": {
               "description": "The date in which this resource was created. Read only.",
               "format": "date-time",
               "title": "Created",
               "type": "string"
            },
            "modified": {
               "description": "The date in which this resource was most recently changed. Read only.",
               "format": "date-time",
               "title": "Modified",
               "type": "string"
            }
         },
         "required": [
            "created",
            "modified"
         ],
         "title": "AbstractSAMStatusBase",
         "type": "object"
      }
   },
   "required": [
      "apiVersion",
      "kind",
      "metadata",
      "spec"
   ]
}

Config:

• from_attributes: bool = True

• arbitrary_types_allowed: bool = True

• frozen: bool = True

Fields:

• apiVersion (str)

• kind (str)

• metadata (smarter.lib.manifest.models.AbstractSAMMetadataBase)

• spec (smarter.lib.manifest.models.AbstractSAMSpecBase)

• status (smarter.lib.manifest.models.AbstractSAMStatusBase | None)

Validators:

• validate_apiVersion » apiVersion

• validate_metadata » metadata

field apiVersion: str [Required]

apiVersion[String]: Required. The API version of the AbstractSAMBase.

Validated by:

• coerce_none_strings

• validate_apiVersion

field kind: str [Required]

kind[String]: Required. The kind of resource described by the manifest.

Validated by:

• coerce_none_strings

field metadata: AbstractSAMMetadataBase [Required]

metadata[obj]: Required. The manifest metadata.

Validated by:

• coerce_none_strings

• validate_metadata

field spec: AbstractSAMSpecBase [Required]

spec[obj]: Required. The manifest specification.

Validated by:

• coerce_none_strings

field status: Optional[AbstractSAMStatusBase] = None

status[obj]: Optional. Read-only. The run-time state of the resource described by the manifest.

Validated by:

• coerce_none_strings

validator validate_apiVersion  »  apiVersion

Validates the apiVersion field for a manifest.

This method ensures that the apiVersion attribute is present and matches one of the supported API versions defined in SmarterApiVersions. If the value is missing or invalid, a SAMValidationError is raised.

Parameters:

v (str) – The value of the apiVersion field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing or not a supported version.

Returns:

The validated apiVersion string.

Return type:

str

validator validate_metadata  »  metadata

Validates the metadata field for a manifest.

This method ensures that the metadata attribute is an instance of AbstractSAMMetadataBase. If a dictionary is provided, it will be coerced into an AbstractSAMMetadataBase object. This guarantees that the manifest metadata is always properly structured and validated.

Parameters:

v (dict or AbstractSAMMetadataBase) – The value of the metadata field to validate.

Returns:

The validated metadata object.

Return type:

AbstractSAMMetadataBase

pydantic model smarter.lib.manifest.models.AbstractSAMMetadataBase

Bases: SmarterBasePydanticModel, ABC

Abstract base class for manifest metadata in the Smarter API.

This class defines the required structure and validation logic for metadata associated with Smarter API manifests. It is designed to be subclassed by concrete manifest metadata classes, which may extend or customize the metadata fields as needed for specific resource types.

The AbstractSAMMetadataBase enforces strong typing and validation for core metadata fields, such as resource name, description, version, tags, and annotations. It ensures that all metadata adheres to expected formats and constraints, promoting consistency and reliability across all manifest definitions.

Subclasses should inherit from this class to implement metadata for their specific manifest types. This approach encourages code reuse, enforces validation, and provides a unified interface for working with manifest metadata throughout the Smarter API ecosystem.

Note

This class is abstract and should not be instantiated directly. Instead, create subclasses that define any additional fields or validation required for your manifest’s metadata.

Show JSON schema

{
   "title": "AbstractSAMMetadataBase",
   "description": "Abstract base class for manifest metadata in the Smarter API.\n\nThis class defines the required structure and validation logic for metadata associated with\nSmarter API manifests. It is designed to be subclassed by concrete manifest metadata classes,\nwhich may extend or customize the metadata fields as needed for specific resource types.\n\nThe ``AbstractSAMMetadataBase`` enforces strong typing and validation for core metadata fields,\nsuch as resource name, description, version, tags, and annotations. It ensures that all metadata\nadheres to expected formats and constraints, promoting consistency and reliability across all\nmanifest definitions.\n\nSubclasses should inherit from this class to implement metadata for their specific manifest\ntypes. This approach encourages code reuse, enforces validation, and provides a unified\ninterface for working with manifest metadata throughout the Smarter API ecosystem.\n\n.. note::\n\n    This class is abstract and should not be instantiated directly. Instead, create subclasses\n    that define any additional fields or validation required for your manifest's metadata.",
   "type": "object",
   "properties": {
      "name": {
         "description": "The camelCase name of the manifest resource",
         "title": "Name",
         "type": "string"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "description": "The description for this resource. Be brief. Keep it under 255 characters.",
         "title": "Description"
      },
      "version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "description": "The semantic version of the manifest. Example: 0.1.0",
         "title": "Version"
      },
      "tags": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "description": "The tags of the manifest. Used for generic resource categorization and search. Example: ['tag1', 'tag2']",
         "title": "Tags"
      },
      "annotations": {
         "anyOf": [
            {
               "items": {
                  "additionalProperties": {
                     "anyOf": [
                        {
                           "type": "string"
                        },
                        {
                           "type": "integer"
                        },
                        {
                           "type": "number"
                        },
                        {
                           "type": "boolean"
                        },
                        {
                           "format": "date",
                           "type": "string"
                        },
                        {
                           "format": "date-time",
                           "type": "string"
                        },
                        {
                           "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                           "type": "string"
                        },
                        {
                           "format": "uuid",
                           "type": "string"
                        },
                        {
                           "format": "binary",
                           "type": "string"
                        },
                        {
                           "items": {},
                           "type": "array"
                        },
                        {
                           "additionalProperties": true,
                           "type": "object"
                        }
                     ]
                  },
                  "type": "object"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "description": "The manifest annotations. Used for storing arbitrary metadata as\n            key-value pairs. Example: [{'smarter.sh/test-manifest/project-name': 'Scooby dooby do'}]. The\n            key should be a valid url-friendly string. The value accepts\n            multi-line string values (YAML block scalars) and various scalar types including\n            str, int, float, bool, datetime.date, datetime.datetime, decimal.Decimal, uuid.UUID, bytes, list, dict.\n            ",
         "title": "Annotations"
      }
   },
   "required": [
      "name",
      "description",
      "version"
   ]
}

Config:

• from_attributes: bool = True

• arbitrary_types_allowed: bool = True

• frozen: bool = True

Fields:

• annotations (List[dict[str, str | int | float | bool | datetime.date | datetime.datetime | decimal.Decimal | uuid.UUID | bytes | list | dict]] | None)

• description (str | None)

• name (str)

• tags (List[str] | None)

• version (str | None)

Validators:

• coerce_annotations_to_list » annotations

• validate_annotations » annotations

• validate_description » description

• validate_name » name

• validate_tags » tags

• validate_version » version

field annotations: Optional[List[dict[str, Union[str, int, float, bool, date, datetime, Decimal, UUID, bytes, list, dict]]]] [Optional]

The manifest annotations. Used for storing arbitrary metadata as key-value pairs. Example: [{‘smarter.sh/test-manifest/project-name’: ‘Scooby dooby do’}]. The key should be a valid url-friendly string. The value accepts multi-line string values (YAML block scalars) and various scalar types including str, int, float, bool, datetime.date, datetime.datetime, decimal.Decimal, uuid.UUID, bytes, list, dict.

Validated by:

• coerce_annotations_to_list

• coerce_none_strings

• validate_annotations

field description: Optional[str] [Required]

The description for this resource. Be brief. Keep it under 255 characters.

Validated by:

• coerce_none_strings

• validate_description

field name: str [Required]

The camelCase name of the manifest resource

Validated by:

• coerce_none_strings

• validate_name

field tags: Optional[List[str]] [Optional]

The tags of the manifest. Used for generic resource categorization and search. Example: [‘tag1’, ‘tag2’]

Validated by:

• coerce_none_strings

• validate_tags

field version: Optional[str] [Required]

The semantic version of the manifest. Example: 0.1.0

Validated by:

• coerce_none_strings

• validate_version

validator coerce_annotations_to_list  »  annotations

Pre-validator to coerce stringified JSON lists to Python lists for annotations. This ensures that if the input is a string (e.g., ‘[{“key”: “value”}]’), it is parsed as a list before type validation.

validator validate_annotations  »  annotations

Validates the annotations field for a manifest. Accepts a list of dicts, where each dict can be a single key-value pair or a flat dict with multiple key-value pairs. Supports multi-line string values (YAML block scalars). Ensures each annotation key is URL-friendly and each value is a string or scalar (including multi-line strings). Raises SAMValidationError if invalid.

Parameters:

v (Optional[List[dict[str, Any]]]) – The value of the annotations field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If any annotation is invalid.

Returns:

The validated list of annotations.

Return type:

Optional[List[dict[str, Any]]]

validator validate_description  »  description

Validates the description field for a manifest. This method ensures that the description attribute is present. If the value is missing, a SAMValidationError is raised.

Parameters:

v (str) – The value of the description field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing.

Returns:

The validated description string.

Return type:

str

validator validate_name  »  name

Validates the name field for a manifest.

Ensures the value is a string, present, and meets all constraints. Raises if not a string.

Return type:

str

validator validate_tags  »  tags

Validates the tags field for a manifest. This method ensures that each tag in the tags list adheres to URL-friendly character rules. If any tag is invalid, a SAMValidationError is raised.

Parameters:

v (Optional[List[str]]) – The value of the tags field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If any tag is invalid.

Returns:

The validated list of tags.

Return type:

Optional[List[str]]

validator validate_version  »  version

Validates the version field for a manifest. This method ensures that the version attribute is present and follows semantic versioning rules. If the value is missing or invalid, a SAMValidationError is raised

Parameters:

v (str) – The value of the version field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing or invalid.

Returns:

The validated version string.

Return type:

str

pydantic model smarter.lib.manifest.models.AbstractSAMSpecBase

Bases: SmarterBasePydanticModel, ABC

Pydantic Spec base class. Expected to be subclassed by specific manifest classes.

Show JSON schema

{
   "title": "AbstractSAMSpecBase",
   "description": "Pydantic Spec base class. Expected to be subclassed by specific manifest classes.",
   "type": "object",
   "properties": {}
}

Config:

• from_attributes: bool = True

• arbitrary_types_allowed: bool = True

• frozen: bool = True

Validators:

pydantic model smarter.lib.manifest.models.AbstractSAMStatusBase

Bases: SmarterBasePydanticModel, ABC

Pydantic Status base class. Expected to be subclassed by specific manifest classes.

Show JSON schema

{
   "title": "AbstractSAMStatusBase",
   "description": "Pydantic Status base class. Expected to be subclassed by specific manifest classes.",
   "type": "object",
   "properties": {
      "recordLocator": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "recordLocator[String]: An optional identifier used to locate the resource record associated with this manifest. Read only.",
         "title": "Recordlocator"
      },
      "created": {
         "description": "The date in which this resource was created. Read only.",
         "format": "date-time",
         "title": "Created",
         "type": "string"
      },
      "modified": {
         "description": "The date in which this resource was most recently changed. Read only.",
         "format": "date-time",
         "title": "Modified",
         "type": "string"
      }
   },
   "required": [
      "created",
      "modified"
   ]
}

Config:

• from_attributes: bool = True

• arbitrary_types_allowed: bool = True

• frozen: bool = True

Fields:

• created (datetime.datetime)

• modified (datetime.datetime)

• recordLocator (str | None)

Validators:

field created: datetime [Required]

The date in which this resource was created. Read only.

Validated by:

• coerce_none_strings

field modified: datetime [Required]

The date in which this resource was most recently changed. Read only.

Validated by:

• coerce_none_strings

field recordLocator: Optional[str] = None

recordLocator[String]: An optional identifier used to locate the resource record associated with this manifest. Read only.

Validated by:

• coerce_none_strings

pydantic model smarter.lib.manifest.models.SmarterBasePydanticModel

Bases: BaseModel, SmarterHelperMixin

Smarter API Base Pydantic Model.

Show JSON schema

{
   "title": "SmarterBasePydanticModel",
   "description": "Smarter API Base Pydantic Model.",
   "type": "object",
   "properties": {}
}

Config:

• from_attributes: bool = True

• arbitrary_types_allowed: bool = True

• frozen: bool = True

Validators:

• coerce_none_strings » all fields

validator coerce_none_strings  »  all fields

smarter.lib.manifest.models.VALID_ANNOTATION_VALUE_TYPES_SET = (<class 'str'>, <class 'int'>, <class 'float'>, <class 'bool'>, <class 'datetime.date'>, <class 'datetime.datetime'>, <class 'decimal.Decimal'>, <class 'uuid.UUID'>, <class 'bytes'>, <class 'list'>, <class 'dict'>)

Types allowed for annotation values in manifest metadata.

(
    <class 'str'>,
    <class 'int'>,
    <class 'float'>,
    <class 'bool'>,
    <class 'datetime.date'>,
    <class 'datetime.datetime'>,
    <class 'decimal.Decimal'>,
    <class 'uuid.UUID'>,
    <class 'bytes'>,
    <class 'list'>,
    <class 'dict'>,
)