Mas Data Model

MAS Data Model

Objective

Build backend data models that are explicit, consistent, and evolution-friendly.

Scope

Apply to model definitions under app/models:

1. API contract models (schema)
2. persisted/runtime config models (config, ConfigBase)
3. task/runtime state models (task)

Model Ownership

1. schema models define external API contracts only.
2. config models define persisted configuration structure and validation behavior.
3. task models define runtime execution state and orchestration-facing status.
4. Do not mix transport, persistence, and runtime concerns in one model class.
5. ConfigBase subclasses define real persisted config templates; every ConfigItem must be declared before super().__init__() to be indexed, settable, and saved.
6. MultipleConfig represents a dictionary-like collection of ConfigBase instances and must be declared with all allowed concrete config classes.

Structure And Types

1. Use nested group models for meaningful domains (Info, Run, Notify, Data).
2. Keep shared semantics aligned with mas-schema-naming.
3. Keep domain-specific fields inside dedicated domain blocks.
4. Keep index items and payload models separated.
5. Prefer concrete types over Any.
6. Use Literal or explicit enums for bounded value sets.
7. Use optional types only when missing value has real business meaning.
8. Avoid stringly-typed booleans/numbers in new model fields.
9. Keep datetime/time fields format-stable and documented.
10. When a field is optional by omission, prefer absence over sentinel values that violate the declared type.

Defaults And Validation

1. Use safe defaults for collection fields (default_factory when mutable).
2. Use None defaults only for truly optional semantics.
3. Avoid hidden execution-policy changes in defaults.
4. Keep validation close to model definition.
5. Keep correction/normalization deterministic.
6. Do not encode high-level business workflow in low-level field validators.
7. Do not duplicate validation already guaranteed by config manager or collection base classes; validate only the invariant still at risk, such as referenced uuid existence.
8. Favor validators that reject or normalize one missing invariant, not "just in case" fallbacks for impossible states.
9. Treat config validators as auto-correction behavior, not just passive checks: RangeValidator, OptionsValidator, BoolValidator, path validators, EncryptValidator, VirtualConfigValidator, and MultipleUIDValidator can rewrite stored values.
10. Use VirtualConfigValidator(function) for computed display/config fields that should be read through normal config access but must not be set or persisted as user input.

Relationships And Sensitive Data

1. Keep IDs typed consistently as strings in API-facing schema unless migration is planned.
2. Keep relation fields explicit (scriptId, userId, queueId).
3. Keep index models lightweight and independent of heavy payload models.
4. Avoid duplicating relationship semantics with synonym fields.
5. Mark and isolate sensitive fields clearly (password, token, key).
6. Avoid exposing sensitive values in response models unless explicitly required.
7. Keep encryption/decryption policy out of schema contracts and in proper model/service layers.