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

Mode	Purpose	Makes Changes?
`check`	Show what needs fixing	No - read only
`fix`	Add missing periods to descriptions	Yes
`clean`	Remove incorrect periods	Yes
`restore`	Fix list items (backticks & periods)	Yes
`blanks`	Remove extra blank lines	Yes

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:

Many YAML description fields are missing periods
Bulk find/replace accidentally modifies non-description fields
YAML breaks with periods in $ref, example, type, etc.
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

Secure ID

README YAML PERIOD

YAML Description Period Manager

Quick Start

Examples

Modes Explained

Typical Workflow

What It Does

`fix` mode adds periods to:

`clean` mode removes incorrect periods from:

`restore` mode fixes list items:

`blanks` mode removes extra lines:

Safety Features

Batch Processing

Why This Script?

Requirements

Output Example

​YAML Description Period Manager

​Quick Start

​Examples

​Modes Explained

​Typical Workflow

​What It Does

​fix mode adds periods to:

​clean mode removes incorrect periods from:

​restore mode fixes list items:

​blanks mode removes extra lines:

​Safety Features

​Batch Processing

​Why This Script?

​Requirements

​Output Example

YAML Description Period Manager

Quick Start

Examples

Modes Explained

Typical Workflow

What It Does

`fix` mode adds periods to:

`clean` mode removes incorrect periods from:

`restore` mode fixes list items:

`blanks` mode removes extra lines:

Safety Features

Batch Processing

Why This Script?

Requirements

Output Example