| name | oscal-text-converter |
| description | Convert OSCAL documents between formats (JSON, YAML, XML) and to human-readable formats like Markdown or plain text. Use for document transformation, reporting, and making OSCAL data accessible to non-technical stakeholders. |
OSCAL Text Converter Skill
Convert OSCAL documents between machine formats and to human-readable text for documentation, reporting, and accessibility.
When to Use This Skill
Use this skill when you need to:
- Convert between OSCAL formats (JSON ↔ YAML ↔ XML)
- Generate human-readable documentation from OSCAL
- Create Markdown reports from OSCAL data
- Export controls to spreadsheet-friendly formats
- Produce plain-text summaries
✅ Data Source Principle
This skill transforms and formats documents you provide. All content in the output comes from your source OSCAL document — no compliance data is added from training knowledge.
Supported Conversions
Format Conversions
| From | To | Notes |
|---|
| JSON | YAML | Preferred for readability |
| JSON | XML | For legacy systems |
| YAML | JSON | For processing |
| YAML | XML | Less common |
| XML | JSON | Recommended |
| XML | YAML | Less common |
Text Conversions
| From | To | Use Case |
|---|
| OSCAL | Markdown | Documentation |
| OSCAL | Plain Text | Quick review |
| OSCAL | CSV | Spreadsheets |
| OSCAL | HTML | Web publishing |
Format Conversion Process
JSON to YAML
- Parse JSON document
- Preserve all data structures
- Output as YAML with proper indentation
- Maintain OSCAL element ordering
JSON to XML
- Parse JSON document
- Map to OSCAL XML schema
- Add XML namespaces
- Preserve all attributes
XML to JSON
- Parse XML document
- Handle XML-specific elements (attributes, namespaces)
- Map to OSCAL JSON structure
- Validate output
Human-Readable Conversions
Catalog to Markdown
# NIST SP 800-53 Rev 5
**Version:** 5.1.0
**Last Modified:** 2023-12-01
**OSCAL Version:** 1.2.0
## Control Families
### Access Control (AC)
#### AC-1: Policy and Procedures
**Control Statement:**
a. Develop, document, and disseminate to [Assignment: organization-defined
personnel or roles]:
1. An access control policy that:
- Addresses purpose, scope, roles, responsibilities, management
commitment, coordination among organizational entities, and compliance
- Is consistent with applicable laws, executive orders, directives,
regulations, policies, standards, and guidelines
**Discussion:**
Access control policy and procedures address the controls in the AC family...
**Related Controls:** PM-9, PS-8, SI-12
---
#### AC-2: Account Management
**Control Statement:**
a. Define and document the types of accounts allowed...
SSP to Plain Text
SYSTEM SECURITY PLAN SUMMARY
============================
System Name: Cloud Application Platform
System ID: cloud-app-001
Authorization Status: Authorized
Authorization Date: 2024-01-15
SYSTEM DESCRIPTION
------------------
The Cloud Application Platform provides...
SECURITY CATEGORIZATION
-----------------------
Confidentiality: Moderate
Integrity: Moderate
Availability: Low
Overall: Moderate
CONTROL IMPLEMENTATION SUMMARY
------------------------------
Total Controls Required: 325
Implemented: 287 (88%)
Partially Implemented: 25 (8%)
Planned: 10 (3%)
Not Applicable: 3 (1%)
TOP GAPS
--------
1. SI-4 - Security Monitoring (Planned)
2. CA-7 - Continuous Monitoring (Partial)
3. CP-9 - System Backup (Partial)
Controls to CSV
Control ID,Title,Family,Status,Responsible Party,Implementation Summary
AC-1,Policy and Procedures,Access Control,Implemented,ISSO,Access control policy documented
AC-2,Account Management,Access Control,Implemented,IAM Admin,Azure AD manages accounts
AC-3,Access Enforcement,Access Control,Implemented,System Admin,RBAC enforced via policies
AC-4,Information Flow,Access Control,Partial,Network Admin,Firewall rules in place - DLP pending
Conversion Templates
Executive Summary Template
# Executive Summary: [System Name]
## Authorization Status
**Status:** [Authorized/In Progress]
**Date:** [Date]
**Authorizing Official:** [Name]
## Compliance Overview
- **Framework:** [NIST 800-53 / FedRAMP / etc.]
- **Baseline:** [Low/Moderate/High]
- **Compliance Rate:** [X]%
## Key Metrics
| Metric | Value |
|--------|-------|
| Total Controls | [N] |
| Implemented | [N] |
| Open POA&M Items | [N] |
| Critical Risks | [N] |
## Recommendations
1. [Recommendation 1]
2. [Recommendation 2]
Control Implementation Template
## [Control ID]: [Control Title]
**Implementation Status:** [Status]
**Responsible Role:** [Role]
### Requirement
[Control statement text]
### How We Implement This
[Implementation narrative]
### Evidence
- [Evidence item 1]
- [Evidence item 2]
### Related Controls
[List of related controls]
Extraction Options
Control Information
Extract and format:
- Control ID and title
- Statement text
- Guidance/discussion
- Parameters
- Enhancements
- Related controls
Implementation Details
Extract and format:
- Implementation status
- Implementation narrative
- Responsible parties
- Evidence references
- Parameter settings
System Information
Extract and format:
- System characteristics
- Authorization boundary
- Network diagrams (references)
- User types
- Data flows
Output Formatting Options
Markdown Options
- Headers (ATX style: #, ##, ###)
- Tables (pipe tables)
- Code blocks (for technical content)
- Lists (bulleted and numbered)
- Links and references
Plain Text Options
- ASCII borders and dividers
- Fixed-width formatting
- Indentation for hierarchy
- Simple bullet points
CSV Options
- Column headers
- Quoted strings
- Escaped commas
- Proper encoding (UTF-8)
Example Usage
When asked "Convert this OSCAL catalog to readable Markdown":
- Parse the OSCAL catalog
- Extract metadata (title, version)
- Iterate through groups (families)
- For each control:
- Format ID and title as header
- Extract and format statement
- Include guidance if present
- List enhancements
- Add table of contents
- Output complete Markdown document
When asked "Export controls to CSV for spreadsheet":
- Parse the OSCAL document
- Determine relevant fields
- Create header row
- For each control, extract:
- ID, title, family
- Status (if SSP)
- Description/summary
- Format as CSV with proper escaping
- Output for download/copy
