# COBOL Copybook to JSON Schema Converter
[](https://pypi.org/project/cobol-copybook-to-json/)
[](https://pepy.tech/projects/cobol-copybook-to-json)
[](https://pypi.org/project/cobol-copybook-to-json/)
[](https://opensource.org/licenses/MIT)
A Python utility that converts COBOL copybooks to JSON schema format. This tool is particularly useful for mainframe modernization projects and data integration scenarios where you need to understand and work with COBOL data structures in modern applications.
## Features
- **Comprehensive COBOL Support**: Handles various COBOL data structures including:
- Group items and elementary items
- OCCURS clauses (arrays)
- REDEFINES clauses
- Different USAGE types (COMP, COMP-3, etc.)
- PICTURE clauses with various data types
- Signed and unsigned numeric fields
- **Dual Usage**: Can be used both as a command-line tool and as a Python library
- **Debug Support**: Built-in debugging capabilities for troubleshooting
- **Error Handling**: Comprehensive error handling with detailed messages
## Installation
```bash
pip install cobol-copybook-to-json
```
## Usage
### Command Line Tool
```bash
# Convert a COBOL copybook to JSON schema
cobol-to-json -c input_copybook.cpy -j output_schema.json
# Enable debug mode
cobol-to-json -c input_copybook.cpy -j output_schema.json -d
```
### Python Library
```python
from cobol_copybook_to_json import convert_copybook_to_json
# Read your COBOL copybook
with open('your_copybook.cpy', 'r') as f:
copybook_content = f.read()
# Convert to JSON schema
result = convert_copybook_to_json(
copybook_content=copybook_content,
copybook_name="your_copybook.cpy",
debug=False
)
if result["status"] == "success":
print("JSON Schema:")
print(result["json_string"])
print(f"Record size: {result['record_size']} bytes")
print(f"Field count: {result['field_count']}")
else:
print(f"Error: {result['message']}")
```
## Example
### Input COBOL Copybook
```cobol
*
* Sample Employee Record COBOL Layout
*
01 EMP-RECORD.
05 EMP-ID PIC 9(5).
05 EMP-ID-X REDEFINES EMP-ID PIC X(5).
05 EMP-NAME PIC X(25).
05 EMP-DOB PIC X(10).
05 EMP-ADDRESS OCCURS 3 TIMES.
10 EMP-ADDR-LINE PIC X(25).
05 EMP-YOE-CUR PIC S9(4) COMP.
05 EMP-YOE-TOTAL PIC 9(4)V99 COMP-3.
05 EMP-SALARY PIC S9(4)V99.
05 EMP-SALARY-DIFF PIC S9999V99 COMP-3.
05 EMP-DEPENDENTS-NUM PIC S9(2).
05 FILLER PIC X(17).
```
### Output JSON Schema
```json
{
"metadata": {
"version": "1.0",
"generatedAt": "2025-06-12T16:21:33.277217",
"sourceFile": "EMP.cpy"
},
"record": {
"type": "object",
"name": "EMP-RECORD",
"recordType": "fixed",
"maxLength": 150,
"properties": {
"EMP-ID": {
"type": "number",
"picture": "9(5)",
"precision": 5,
"scale": 0,
"offset": 0,
"maxLength": 5
},
"EMP-ID-X": {
"type": "string",
"picture": "X(5)",
"redefines": "EMP-ID",
"offset": 0,
"maxLength": 5
},
"EMP-NAME": {
"type": "string",
"picture": "X(25)",
"offset": 5,
"maxLength": 25
},
"EMP-DOB": {
"type": "string",
"picture": "X(10)",
"offset": 30,
"maxLength": 10
},
"EMP-ADDRESS": {
"type": "object",
"occurs": {
"min": 3,
"max": 3
},
"offset": 40,
"maxLength": 75,
"properties": {
"EMP-ADDR-LINE": {
"type": "string",
"picture": "X(25)",
"offset": 40,
"maxLength": 25
}
}
},
"EMP-YOE-CUR": {
"type": "number",
"picture": "S9(4)",
"precision": 4,
"scale": 0,
"usage": "COMP",
"signed": true,
"offset": 115,
"maxLength": 2
},
"EMP-YOE-TOTAL": {
"type": "number",
"picture": "9(4)V99",
"precision": 6,
"scale": 2,
"usage": "COMP-3",
"offset": 117,
"maxLength": 4
},
"EMP-SALARY": {
"type": "number",
"picture": "S9(4)V99",
"precision": 6,
"scale": 2,
"signed": true,
"offset": 121,
"maxLength": 6
},
"EMP-SALARY-DIFF": {
"type": "number",
"picture": "S9999V99",
"precision": 6,
"scale": 2,
"usage": "COMP-3",
"signed": true,
"offset": 127,
"maxLength": 4
},
"EMP-DEPENDENTS-NUM": {
"type": "number",
"picture": "S9(2)",
"precision": 2,
"scale": 0,
"signed": true,
"offset": 131,
"maxLength": 2
},
"FILLER-X-1001": {
"type": "string",
"picture": "X(17)",
"offset": 133,
"maxLength": 17
}
}
}
}
```
The tool generates a comprehensive JSON schema that includes:
- **Field names and types** with proper data type mapping
- **Data lengths and precision** for numeric fields
- **Array structures** for OCCURS clauses (EMP-ADDRESS occurs 3 times)
- **REDEFINES handling** (EMP-ID-X redefines EMP-ID)
- **USAGE types** (COMP, COMP-3) with appropriate storage calculations
- **Signed field indicators** for fields with sign
- **Field offsets** showing exact byte positions in the record
- **Metadata** including generation timestamp and source file
## API Reference
### convert_copybook_to_json(copybook_content, copybook_name="copybook.cpy", debug=False)
**Parameters:**
- `copybook_content` (str or list): COBOL copybook content as string or list of strings
- `copybook_name` (str, optional): Name for the copybook (default: "copybook.cpy")
- `debug` (bool, optional): Enable debug output (default: False)
**Returns:**
Dictionary with the following keys:
- `status`: "success" or "error"
- `json_string`: Generated JSON schema (if successful)
- `record_size`: Total record size in bytes
- `field_count`: Number of fields processed
- `message`: Error message (if failed)
- `traceback`: Detailed error information (if debug enabled)
## Requirements
- Python 3.7 or higher
- No external dependencies
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Citation
If you use this software in your research or project, please cite it as:
```bibtex
@software{selvam_cobol_copybook_to_json_2024,
author = {Selvam, Arunkumar},
title = {COBOL Copybook to JSON Schema Converter},
url = {https://github.com/arunkumars-mf/cobol-copybook-to-json},
version = {1.1.1},
year = {2024}
}
```
**APA Style:**
Selvam, A. (2024). COBOL Copybook to JSON Schema Converter (Version 1.1.1) [Computer software]. https://github.com/arunkumars-mf/cobol-copybook-to-json
**IEEE Style:**
A. Selvam (IEEE Member), "COBOL Copybook to JSON Schema Converter," Version 1.1.1, 2024. [Online]. Available: https://github.com/arunkumars-mf/cobol-copybook-to-json
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Use Cases
- **Mainframe Modernization**: Convert legacy COBOL data structures for modern applications
- **Data Integration**: Understand COBOL data formats for ETL processes
- **API Development**: Generate schemas for APIs that interface with mainframe systems
- **Documentation**: Create readable documentation of COBOL data structures
Raw data
{
"_id": null,
"home_page": "https://github.com/arunkumars-mf/cobol-copybook-to-json",
"name": "cobol-copybook-to-json",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "cobol, copybook, json, schema, converter, mainframe",
"author": "Arunkumar Selvam",
"author_email": "Arunkumar Selvam <aruninfy123@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/b3/8631a20314b84e6bf556581c67f57d398630c8e5b1cbc154f95714ec7a87/cobol_copybook_to_json-1.1.1.tar.gz",
"platform": null,
"description": "# COBOL Copybook to JSON Schema Converter\n\n[](https://pypi.org/project/cobol-copybook-to-json/)\n[](https://pepy.tech/projects/cobol-copybook-to-json)\n[](https://pypi.org/project/cobol-copybook-to-json/)\n[](https://opensource.org/licenses/MIT)\n\nA Python utility that converts COBOL copybooks to JSON schema format. This tool is particularly useful for mainframe modernization projects and data integration scenarios where you need to understand and work with COBOL data structures in modern applications.\n\n## Features\n\n- **Comprehensive COBOL Support**: Handles various COBOL data structures including:\n - Group items and elementary items\n - OCCURS clauses (arrays)\n - REDEFINES clauses\n - Different USAGE types (COMP, COMP-3, etc.)\n - PICTURE clauses with various data types\n - Signed and unsigned numeric fields\n\n- **Dual Usage**: Can be used both as a command-line tool and as a Python library\n- **Debug Support**: Built-in debugging capabilities for troubleshooting\n- **Error Handling**: Comprehensive error handling with detailed messages\n\n## Installation\n\n```bash\npip install cobol-copybook-to-json\n```\n\n## Usage\n\n### Command Line Tool\n\n```bash\n# Convert a COBOL copybook to JSON schema\ncobol-to-json -c input_copybook.cpy -j output_schema.json\n\n# Enable debug mode\ncobol-to-json -c input_copybook.cpy -j output_schema.json -d\n```\n\n### Python Library\n\n```python\nfrom cobol_copybook_to_json import convert_copybook_to_json\n\n# Read your COBOL copybook\nwith open('your_copybook.cpy', 'r') as f:\n copybook_content = f.read()\n\n# Convert to JSON schema\nresult = convert_copybook_to_json(\n copybook_content=copybook_content,\n copybook_name=\"your_copybook.cpy\",\n debug=False\n)\n\nif result[\"status\"] == \"success\":\n print(\"JSON Schema:\")\n print(result[\"json_string\"])\n print(f\"Record size: {result['record_size']} bytes\")\n print(f\"Field count: {result['field_count']}\")\nelse:\n print(f\"Error: {result['message']}\")\n```\n\n## Example\n\n### Input COBOL Copybook\n```cobol\n * \n * Sample Employee Record COBOL Layout\n * \n 01 EMP-RECORD.\n 05 EMP-ID PIC 9(5).\n 05 EMP-ID-X REDEFINES EMP-ID PIC X(5).\n 05 EMP-NAME PIC X(25).\n 05 EMP-DOB PIC X(10).\n 05 EMP-ADDRESS OCCURS 3 TIMES.\n 10 EMP-ADDR-LINE PIC X(25).\n 05 EMP-YOE-CUR PIC S9(4) COMP.\n 05 EMP-YOE-TOTAL PIC 9(4)V99 COMP-3.\n 05 EMP-SALARY PIC S9(4)V99.\n 05 EMP-SALARY-DIFF PIC S9999V99 COMP-3. \n 05 EMP-DEPENDENTS-NUM PIC S9(2).\n 05 FILLER PIC X(17).\n```\n\n### Output JSON Schema\n```json\n{\n \"metadata\": {\n \"version\": \"1.0\",\n \"generatedAt\": \"2025-06-12T16:21:33.277217\",\n \"sourceFile\": \"EMP.cpy\"\n },\n \"record\": {\n \"type\": \"object\",\n \"name\": \"EMP-RECORD\",\n \"recordType\": \"fixed\",\n \"maxLength\": 150,\n \"properties\": {\n \"EMP-ID\": {\n \"type\": \"number\",\n \"picture\": \"9(5)\",\n \"precision\": 5,\n \"scale\": 0,\n \"offset\": 0,\n \"maxLength\": 5\n },\n \"EMP-ID-X\": {\n \"type\": \"string\",\n \"picture\": \"X(5)\",\n \"redefines\": \"EMP-ID\",\n \"offset\": 0,\n \"maxLength\": 5\n },\n \"EMP-NAME\": {\n \"type\": \"string\",\n \"picture\": \"X(25)\",\n \"offset\": 5,\n \"maxLength\": 25\n },\n \"EMP-DOB\": {\n \"type\": \"string\",\n \"picture\": \"X(10)\",\n \"offset\": 30,\n \"maxLength\": 10\n },\n \"EMP-ADDRESS\": {\n \"type\": \"object\",\n \"occurs\": {\n \"min\": 3,\n \"max\": 3\n },\n \"offset\": 40,\n \"maxLength\": 75,\n \"properties\": {\n \"EMP-ADDR-LINE\": {\n \"type\": \"string\",\n \"picture\": \"X(25)\",\n \"offset\": 40,\n \"maxLength\": 25\n }\n }\n },\n \"EMP-YOE-CUR\": {\n \"type\": \"number\",\n \"picture\": \"S9(4)\",\n \"precision\": 4,\n \"scale\": 0,\n \"usage\": \"COMP\",\n \"signed\": true,\n \"offset\": 115,\n \"maxLength\": 2\n },\n \"EMP-YOE-TOTAL\": {\n \"type\": \"number\",\n \"picture\": \"9(4)V99\",\n \"precision\": 6,\n \"scale\": 2,\n \"usage\": \"COMP-3\",\n \"offset\": 117,\n \"maxLength\": 4\n },\n \"EMP-SALARY\": {\n \"type\": \"number\",\n \"picture\": \"S9(4)V99\",\n \"precision\": 6,\n \"scale\": 2,\n \"signed\": true,\n \"offset\": 121,\n \"maxLength\": 6\n },\n \"EMP-SALARY-DIFF\": {\n \"type\": \"number\",\n \"picture\": \"S9999V99\",\n \"precision\": 6,\n \"scale\": 2,\n \"usage\": \"COMP-3\",\n \"signed\": true,\n \"offset\": 127,\n \"maxLength\": 4\n },\n \"EMP-DEPENDENTS-NUM\": {\n \"type\": \"number\",\n \"picture\": \"S9(2)\",\n \"precision\": 2,\n \"scale\": 0,\n \"signed\": true,\n \"offset\": 131,\n \"maxLength\": 2\n },\n \"FILLER-X-1001\": {\n \"type\": \"string\",\n \"picture\": \"X(17)\",\n \"offset\": 133,\n \"maxLength\": 17\n }\n }\n }\n}\n```\n\nThe tool generates a comprehensive JSON schema that includes:\n- **Field names and types** with proper data type mapping\n- **Data lengths and precision** for numeric fields\n- **Array structures** for OCCURS clauses (EMP-ADDRESS occurs 3 times)\n- **REDEFINES handling** (EMP-ID-X redefines EMP-ID)\n- **USAGE types** (COMP, COMP-3) with appropriate storage calculations\n- **Signed field indicators** for fields with sign\n- **Field offsets** showing exact byte positions in the record\n- **Metadata** including generation timestamp and source file\n\n## API Reference\n\n### convert_copybook_to_json(copybook_content, copybook_name=\"copybook.cpy\", debug=False)\n\n**Parameters:**\n- `copybook_content` (str or list): COBOL copybook content as string or list of strings\n- `copybook_name` (str, optional): Name for the copybook (default: \"copybook.cpy\")\n- `debug` (bool, optional): Enable debug output (default: False)\n\n**Returns:**\nDictionary with the following keys:\n- `status`: \"success\" or \"error\"\n- `json_string`: Generated JSON schema (if successful)\n- `record_size`: Total record size in bytes\n- `field_count`: Number of fields processed\n- `message`: Error message (if failed)\n- `traceback`: Detailed error information (if debug enabled)\n\n## Requirements\n\n- Python 3.7 or higher\n- No external dependencies\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Citation\n\nIf you use this software in your research or project, please cite it as:\n\n```bibtex\n@software{selvam_cobol_copybook_to_json_2024,\n author = {Selvam, Arunkumar},\n title = {COBOL Copybook to JSON Schema Converter},\n url = {https://github.com/arunkumars-mf/cobol-copybook-to-json},\n version = {1.1.1},\n year = {2024}\n}\n```\n\n**APA Style:**\nSelvam, A. (2024). COBOL Copybook to JSON Schema Converter (Version 1.1.1) [Computer software]. https://github.com/arunkumars-mf/cobol-copybook-to-json\n\n**IEEE Style:**\nA. Selvam (IEEE Member), \"COBOL Copybook to JSON Schema Converter,\" Version 1.1.1, 2024. [Online]. Available: https://github.com/arunkumars-mf/cobol-copybook-to-json\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Use Cases\n\n- **Mainframe Modernization**: Convert legacy COBOL data structures for modern applications\n- **Data Integration**: Understand COBOL data formats for ETL processes\n- **API Development**: Generate schemas for APIs that interface with mainframe systems\n- **Documentation**: Create readable documentation of COBOL data structures\n",
"bugtrack_url": null,
"license": null,
"summary": "Convert COBOL copybooks to JSON schema format",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/arunkumars-mf/cobol-copybook-to-json/issues",
"Citation": "https://github.com/arunkumars-mf/cobol-copybook-to-json/blob/main/CITATION.cff",
"Homepage": "https://github.com/arunkumars-mf/cobol-copybook-to-json",
"Source": "https://github.com/arunkumars-mf/cobol-copybook-to-json"
},
"split_keywords": [
"cobol",
" copybook",
" json",
" schema",
" converter",
" mainframe"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0c20b36a68efd17b84385cbf866989dabb0476a20498e82ad7fe9170dd87b4bd",
"md5": "333cc043ec55e69c6f2d1bf46f61756a",
"sha256": "bd13f77731f2aee85bf163c1702e4e5f0c5685c9f41fc9758ca59057ad807cad"
},
"downloads": -1,
"filename": "cobol_copybook_to_json-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "333cc043ec55e69c6f2d1bf46f61756a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12402,
"upload_time": "2025-08-30T14:28:48",
"upload_time_iso_8601": "2025-08-30T14:28:48.482817Z",
"url": "https://files.pythonhosted.org/packages/0c/20/b36a68efd17b84385cbf866989dabb0476a20498e82ad7fe9170dd87b4bd/cobol_copybook_to_json-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17b38631a20314b84e6bf556581c67f57d398630c8e5b1cbc154f95714ec7a87",
"md5": "e19882bda8c6ec0cd43a943e7d25515d",
"sha256": "636bf021fdf46b08080c6910874c36b2d085fbed5a2fa05cf211432d7b7921a4"
},
"downloads": -1,
"filename": "cobol_copybook_to_json-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e19882bda8c6ec0cd43a943e7d25515d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15982,
"upload_time": "2025-08-30T14:28:49",
"upload_time_iso_8601": "2025-08-30T14:28:49.282925Z",
"url": "https://files.pythonhosted.org/packages/17/b3/8631a20314b84e6bf556581c67f57d398630c8e5b1cbc154f95714ec7a87/cobol_copybook_to_json-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 14:28:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arunkumars-mf",
"github_project": "cobol-copybook-to-json",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cobol-copybook-to-json"
}
JSON
