mas-schema-naming

name	mas-schema-naming
description	Define canonical naming for future backend schema domains. Use when creating new specialized schema models or extending Pydantic contracts in app/models/schema.py, standardizing shared Info/Data/Notify/Run semantics, and avoiding new naming drift without forcing retroactive changes on legacy modules.

MAS Schema Naming

Objective

Standardize naming for future specialized backend schema implementations.

This skill constrains new domain work by default. It does not require retroactive renaming of existing legacy modules unless explicitly requested.

Global Constraints

Apply these constraints while using this skill.

1. Make minimal necessary changes first; avoid broad refactors unless explicitly requested.
2. Align with current code style and existing project conventions in the touched module.
3. Avoid over-engineering, over-abstraction, and defensive programming that does not match existing code patterns.
4. Study similar existing implementations deeply before coding and follow established local patterns.

Apply Workflow

1. Determine whether the field is shared semantic or domain-specific semantic.
2. For shared semantic, use the canonical name from this skill.
3. For domain-specific semantic, keep naming local to the domain block.
4. Keep public config-model field style consistent: PascalCase.
5. When touching legacy modules, prefer compatibility-first edits and avoid broad rename-only refactors.

Canonical Structure For New Domains

Use this top-level structure for new script/user schema models.

class XxxConfig(BaseModel):
    Info: XxxConfig_Info | None
    Run: XxxConfig_Run | None
    Emulator: XxxConfig_Emulator | None  # only if emulator semantics exist

class XxxUserConfig(BaseModel):
    Info: XxxUserConfig_Info | None
    Data: XxxUserConfig_Data | None
    Notify: XxxUserConfig_Notify | None
    # optional domain blocks, e.g. Task/Stage/Game

Shared Naming Matrix

Use these names when semantics are the same.

Semantic	Canonical name	Block
Script display name	Name	Info
Script runtime path	Path	Info
Emulator id	Id	Emulator
Emulator index	Index	Emulator
Transition strategy	TaskTransitionMethod	Run
Daily proxy limit	ProxyTimesLimit	Run
Retry limit	RunTimesLimit	Run
Runtime timeout	RunTimeLimit	Run
User display name	Name	User.Info
User id	Id	User.Info
User enabled status	Status	User.Info
Remaining day budget	RemainedDay	User.Info
User note	Notes	User.Info
User tag payload	Tag	User.Info
Last proxy date	LastProxyDate	User.Data
Proxy run count	ProxyTimes	User.Data
Manual-check result	IfPassCheck	User.Data
Notify enabled	Enabled	User.Notify

Boundary For Domain-Specific Names

1. Keep domain-specific semantics inside dedicated domain blocks.
2. Do not force shared naming when semantics differ.
3. Do not add synonym fields for the same semantic in one block.

Drift To Avoid In New Work

1. Same semantic, different names (Path vs RootPath).
2. Same semantic, different block placement (Data vs Info).
3. Same semantic, mixed boolean style in the same block.

Compatibility Rule

When canonicalizing an existing public field:

1. Keep read compatibility for legacy payloads during migration.
2. Prefer writing canonical names in new responses.
3. Remove legacy names only after consumer migration is complete.

PR Checklist

1. New specialized schema models follow this canonical matrix for shared semantics.
2. Domain-specific fields stay in domain-specific blocks.
3. No new synonym names are introduced for existing shared semantics.
4. Legacy modules are not renamed in bulk unless explicitly in scope.