Skip to main content

​
YAML Description Period Manager

One script. Five modes. All problems solved.

​
Quick Start

# Check what needs fixing (no changes made)
python3 yaml_period_manager.py check <file.yaml>

# Add missing periods to descriptions
python3 yaml_period_manager.py fix <file.yaml>

# Remove incorrect periods (if YAML errors occur)
python3 yaml_period_manager.py clean <file.yaml>

# Fix list items (backticks and periods)
python3 yaml_period_manager.py restore <file.yaml>

# Remove extra blank lines after descriptions
python3 yaml_period_manager.py blanks <file.yaml>

​
Examples

# Check current state
python3 yaml_period_manager.py check openapi/payments/v2025-01-01.yaml

# Fix descriptions
python3 yaml_period_manager.py fix openapi/payments/v2025-01-01.yaml

# Clean up errors
python3 yaml_period_manager.py clean openapi/payments/v2025-01-01.yaml

# Fix list items
python3 yaml_period_manager.py restore openapi/vrs/vrsv2.yaml

# Remove blank lines
python3 yaml_period_manager.py blanks openapi/vrs/vrsv2.yaml

​
Modes Explained

ModePurposeMakes Changes?
checkShow what needs fixingNo - read only
fixAdd missing periods to descriptionsYes
cleanRemove incorrect periodsYes
restoreFix list items (backticks & periods)Yes
blanksRemove extra blank linesYes

​
Typical Workflow

# 1. Check the file first
python3 yaml_period_manager.py check openapi/payments/v2025-01-01.yaml

# 2. Fix descriptions if needed
python3 yaml_period_manager.py fix openapi/payments/v2025-01-01.yaml

# 3. If YAML errors occur, clean up
python3 yaml_period_manager.py clean openapi/payments/v2025-01-01.yaml

# 4. Fix list items if needed
python3 yaml_period_manager.py restore openapi/vrs/vrsv2.yaml

# 5. Remove extra blank lines
python3 yaml_period_manager.py blanks openapi/vrs/vrsv2.yaml

# 6. Validate
mint dev

​
What It Does

​
fix mode adds periods to:

# Before
description: This field stores the ID

# After
description: This field stores the ID.

​
clean mode removes incorrect periods from:

# Before (ERROR - breaks YAML)
example: "2024-09-26".
$ref: "#/components/schemas/Item".

# After
example: "2024-09-26"
$ref: "#/components/schemas/Item"

​
restore mode fixes list items:

# Before (incorrect periods)
- `VALID`.
- `INVALID`.

# After
- `VALID`
- `INVALID`

# Before (missing backticks)
- `WHATSAPP
- `EMAIL

# After
- `WHATSAPP`
- `EMAIL`

​
blanks mode removes extra lines:

# Before
description: Some text.

next_field: value

# After
description: Some text.
next_field: value

​
Safety Features

  • ✅ Built-in verification prevents corrupting files
  • ✅ check mode shows what will change (without changing)
  • ✅ Only modifies description fields (never $ref, example, type, etc.)
  • ✅ Handles single-line and multi-line descriptions
  • ✅ Works with quoted and unquoted text
  • ✅ Preserves code formatting (backticks)

​
Batch Processing

# Process multiple files
for file in openapi/**/*.yaml; do
    echo "Processing $file"
    python3 yaml_period_manager.py fix "$file"
done

​
Why This Script?

This script was created to solve a common problem:
  1. Many YAML description fields are missing periods
  2. Bulk find/replace accidentally modifies non-description fields
  3. YAML breaks with periods in $ref, example, type, etc.
  4. Manual fixes are time-consuming and error-prone
This script solves all of these issues safely and automatically.

​
Requirements

  • Python 3.6+
  • No external dependencies

​
Output Example

File: openapi/payments/v2025-01-01.yaml
Mode: FIX - Adding missing periods to descriptions
======================================================================

1. Fixing single-line descriptions...
   ✓ Fixed 150 single-line descriptions

2. Fixing multi-line descriptions...
   ✓ Fixed 83 multi-line descriptions

3. Verifying changes...
   ✓ No issues - changes are safe

✓ SUCCESS: Fixed 233 descriptions