Common pitfalls

Scalar values for list properties

Some properties accept multiple values and require YAML list syntax, even when providing a single value.

Affected properties

Property	Entity	Type
requiredClass	Item	list[CharacterClass]
linkPassivityId	Item	list[string]
linkPassivityCategoryId	Item	list[string]
linkMasterpiecePassivityId	Item	list[string]
linkMasterpiecePassivityCategoryId	Item	list[string]
masterpieceBasicStatRevise	Item	list[string]
gambleItemType	Item	list[string]
requiredUserStatus	Item	list[string]
useEquipmentType	Equipment	list[string]
useGambleItemGrade	Equipment	list[string]

Incorrect vs correct syntax

# Incorrect: scalar value for a list property
items:
  create:
    - id: 99000001
      requiredClass: ARCHER
      linkPassivityCategoryId: 30

# Correct: list syntax, even for single values
items:
  create:
    - id: 99000001
      requiredClass: ["ARCHER"]
      linkPassivityCategoryId: ["30"]

Since v1.x, scalar values are automatically coerced to single-element lists, so both syntaxes work. List syntax is recommended for clarity and consistency.

Missing spec header

Every spec file requires a spec header with a version:

# Missing header — will fail validation
items:
  create:
    - id: 1
      name: sword

# Correct
spec:
  version: "1.0"

items:
  create:
    - id: 1
      name: sword

See Syntax for the full spec structure.

Variable reference syntax

Variable references require the $ prefix. Without it, the value is treated as a literal string:

variables:
  DEFAULT_LEVEL: 60

items:
  create:
    - id: 1
      level: DEFAULT_LEVEL   # Literal string "DEFAULT_LEVEL", not 60
      rank: $DEFAULT_LEVEL   # Resolves to 60

See Variables for substitution rules.

Definition vs variable scope

Definitions are imported automatically when a module is imported. Variables require explicit opt-in via use.variables:

imports:
  - from: shared
    use:
      variables:
        - BASE_HP        # Explicit opt-in required for variables

# Definitions from 'shared' are available without opt-in
items:
  create:
    - $extends: sharedBase
      id: 1
      hp: $BASE_HP

Without the use.variables block, $BASE_HP triggers E520 (unknown variable reference), even if the source module exports it.

See Import system for full import syntax.

Filter syntax vs property value syntax

Filter syntax in updateWhere differs from property value syntax in create or update. For flags-type properties like requiredClass:

items:
  # Filter: scalar value checks if the flag is included
  updateWhere:
    - filter:
        requiredClass: warrior     # Matches items where requiredClass includes warrior
      changes:
        sellPrice: 100

  # Property value: list syntax sets the actual value
  create:
    - id: 99000001
      requiredClass: ["WARRIOR"]   # Sets requiredClass to WARRIOR

See Filters for filter syntax details.

Related

• Syntax — spec structure and data types
• Variables — variable declaration and substitution
• Import system — packages, exports, and module resolution
• Filters — filter syntax for updateWhere
• Error codes — complete error code reference