{"openapi":"3.0.1","info":{"title":"Legacix COBOL Parsing API","description":"Parses COBOL source code and returns its structure as JSON, for other services to consume.\n\n## Source format — read this first\n\nCOBOL reserves leading columns of every line, so **source lines must begin with at least one space** before the actual code. This is a property of the language, not of this API.\n\n| Format | Reserved columns |\n|---|---|\n| `TANDEM` (default) | Column 1 is the indicator area; code starts at column 2. |\n| `FIXED` | Columns 1-6 sequence number, 7 indicator, 8-72 code. |\n| `VARIABLE` | Same as `FIXED`, without the 72-column limit. |\n\nSending `IDENTIFICATION DIVISION.` with no leading space makes the preprocessor consume the first characters as the indicator area, yielding a confusing syntax error. Send `\" IDENTIFICATION DIVISION.\"` instead.\n\n## Choosing an endpoint\n\n- **`/preprocess`** — expand `COPY`/`REPLACE`/`CBL`/`PROCESS` only; does not require valid grammar.\n- **`/validate`** — check syntax. Invalid COBOL returns `200` with `valid: false`, never an error status.\n- **`/ast`** — the raw parse tree, for callers doing their own tree walking.\n- **`/asg/*`** — semantic analysis as structured JSON. Use `/asg/program-unit` for everything at once, or the narrower endpoints to avoid transferring the rest.\n\n## Errors\n\nEvery failure returns the same body shape (`timestamp`, `status`, `error`, `message`, `path`).\n`400` means the request or the COBOL is at fault; `500` means this service failed.\n","contact":{"name":"Nuvello Tecnologia","url":"https://github.com/Nuvello-Tecnologia/legacy-modernization-legacix-parsing"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"version":"1.0.0"},"servers":[{"url":"https://www.parser.resources.nuvello.com.br","description":"Generated server url"}],"tags":[{"name":"AST","description":"Abstract Syntax Tree generation"},{"name":"Validation","description":"Syntax validation of COBOL source code"},{"name":"Preprocessor","description":"Expands COPY, REPLACE, CBL and PROCESS statements"},{"name":"ASG","description":"Abstract Semantic Graph — divisions, data items, paragraphs and calls"}],"paths":{"/api/v1/validate":{"post":{"tags":["Validation"],"summary":"Validate COBOL source code","description":"Attempts to parse the given COBOL source code and reports whether it is syntactically valid. Unlike the other parsing endpoints, this never returns an error response for invalid COBOL — syntax errors are reported in the body, so callers can check syntax without handling errors. A 400 here means the request itself was malformed, not the COBOL.","operationId":"validate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"400":{"description":"The request body failed validation (e.g. blank cobolCode)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Validation ran; check the 'valid' field for the verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/preprocess":{"post":{"tags":["Preprocessor"],"summary":"Preprocess COBOL source code","description":"Runs the preprocessor over the given COBOL source, expanding COPY/REPLACE/CBL/PROCESS statements and normalizing the line format, without parsing it. The source does not need to be grammatically valid COBOL — only its column layout must match the requested format.","operationId":"preprocess","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"200":{"description":"Source successfully preprocessed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreprocessResponse"}}}},"500":{"description":"The service failed unexpectedly","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"400":{"description":"The source does not match the requested column layout, or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/ast":{"post":{"tags":["AST"],"summary":"Parse COBOL source into an Abstract Syntax Tree","description":"Parses the given COBOL source code and returns its parse tree as a LISP-style string, with rule names resolved — the same shape ANTLR's toStringTree produces. Use this when you want to walk the syntax tree yourself; for pre-analyzed structure, use the ASG endpoints instead.","operationId":"parseAst","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Source parsed; the parse tree is returned as a string","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AstResponse"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/asg/program-unit":{"post":{"tags":["ASG"],"summary":"Parse COBOL source into a structured program unit","description":"Parses the source and performs semantic analysis, returning the Identification and Data Divisions plus the Procedure Division's paragraphs and CALL statements in a single response. Use the narrower endpoints below to transfer only the part you need.","operationId":"parseProgramUnit","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Source analyzed; divisions whose COBOL sections are absent come back null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramUnitDto"}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/asg/paragraphs":{"post":{"tags":["ASG"],"summary":"List paragraphs","description":"Returns every paragraph of the Procedure Division, including those nested inside sections — each one reporting the section it belongs to (null when declared at the division level) and how many statements it contains.","operationId":"parseParagraphs","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Paragraphs found, in declaration order; empty when the program declares none","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ParagraphDto"}}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/asg/identification-division":{"post":{"tags":["ASG"],"summary":"Extract the Identification Division","description":"Returns the PROGRAM-ID along with the AUTHOR, DATE-WRITTEN and DATE-COMPILED paragraphs. Fields the program does not declare come back null.","operationId":"parseIdentificationDivision","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Identification Division of the program, or null if the program declares none","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentificationDivisionDto"}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/asg/data-division":{"post":{"tags":["ASG"],"summary":"Extract the Data Division","description":"Returns the data items of the Working-Storage, Linkage, File and Local-Storage sections. Items are nested by COBOL level number, so an 01 group carries its 05 members as children. File Section records are nested under their FD entry. Sections the program does not declare come back as empty arrays.","operationId":"parseDataDivision","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"Data Division of the program, or null if the program declares none","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataDivisionDto"}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/asg/calls":{"post":{"tags":["ASG"],"summary":"List CALL statements","description":"Returns every CALL statement of the Procedure Division together with the paragraph it appears in — useful for mapping dependencies between programs. The called name is reported as written in the source, so a literal target keeps its quotes while a variable target is the identifier.","operationId":"parseCalls","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}},"required":true},"responses":{"500":{"description":"The service failed unexpectedly while parsing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"200":{"description":"CALL statements found; empty when the program calls nothing","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CallDto"}}}}},"400":{"description":"The COBOL source is invalid (grammar or column layout), or the request body failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Content-Type is missing or is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"schemas":{"ParseRequest":{"required":["cobolCode"],"type":"object","properties":{"cobolCode":{"type":"string","description":"Raw COBOL source code"},"compilationUnitName":{"type":"string","description":"Logical name given to the compilation unit","example":"HELLOWORLD","default":"COMPILATION-UNIT"},"format":{"type":"string","description":"Line/column layout of the source code. Every format reserves column 1 (TANDEM) or columns 1-7 (FIXED, VARIABLE) for sequence/indicator areas, so source lines must start with at least one leading space before the actual COBOL code (e.g. \" IDENTIFICATION DIVISION.\"). FIXED expects the traditional 80-column layout (columns 8-72 for code); VARIABLE is the same but without the 72-column limit; TANDEM only reserves column 1.","default":"TANDEM","enum":["FIXED","TANDEM","VARIABLE"]},"ignoreSyntaxErrors":{"type":"boolean","description":"When true, syntax errors are ignored instead of failing the request","default":false}},"description":"A COBOL compilation unit submitted as plain source code"},"ApiError":{"type":"object","properties":{"timestamp":{"type":"string","description":"When the error occurred","format":"date-time"},"status":{"type":"integer","description":"HTTP status code","format":"int32"},"error":{"type":"string","description":"Short error category"},"message":{"type":"string","description":"Human-readable error details"},"path":{"type":"string","description":"Request path that triggered the error"}},"description":"Standard error payload returned by the API"},"ValidationResponse":{"type":"object","properties":{"valid":{"type":"boolean","description":"True when the source code was parsed without syntax errors"},"errorMessage":{"type":"string","description":"Syntax error message, present only when valid is false"}},"description":"Result of validating COBOL source code for syntax errors"},"PreprocessResponse":{"type":"object","properties":{"preprocessedCode":{"type":"string","description":"Source code after preprocessing"}},"description":"Result of expanding COPY/REPLACE/CBL/PROCESS statements in COBOL source"},"AstResponse":{"type":"object","properties":{"compilationUnitName":{"type":"string","description":"Name of the parsed compilation unit"},"ast":{"type":"string","description":"LISP-style string representation of the parse tree"}},"description":"Abstract Syntax Tree produced by parsing COBOL source"},"CallDto":{"type":"object","properties":{"calledProgramName":{"type":"string","description":"Name or identifier of the called program"},"fromParagraph":{"type":"string","description":"Name of the paragraph containing the CALL statement"}},"description":"A CALL statement found in the Procedure Division"},"DataDivisionDto":{"type":"object","properties":{"workingStorage":{"type":"array","description":"Data items declared in the Working-Storage Section","items":{"$ref":"#/components/schemas/DataItemDto"}},"linkage":{"type":"array","description":"Data items declared in the Linkage Section","items":{"$ref":"#/components/schemas/DataItemDto"}},"fileSection":{"type":"array","description":"Data items declared in the File Section","items":{"$ref":"#/components/schemas/DataItemDto"}},"localStorage":{"type":"array","description":"Data items declared in the Local-Storage Section","items":{"$ref":"#/components/schemas/DataItemDto"}}},"description":"Structured view of a program's Data Division"},"DataItemDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the data item, or FILLER"},"levelNumber":{"type":"integer","description":"COBOL level number, e.g. 01, 05, 88","format":"int32"},"picture":{"type":"string","description":"PICTURE clause, when present"},"value":{"type":"string","description":"VALUE clause, when present"},"children":{"type":"array","description":"Nested data items declared under this one","items":{"$ref":"#/components/schemas/DataItemDto"}}},"description":"A single data description entry (variable) declared in the Data Division"},"IdentificationDivisionDto":{"type":"object","properties":{"programId":{"type":"string","description":"PROGRAM-ID value"},"author":{"type":"string","description":"AUTHOR paragraph text, when present"},"dateWritten":{"type":"string","description":"DATE-WRITTEN paragraph text, when present"},"dateCompiled":{"type":"string","description":"DATE-COMPILED paragraph text, when present"}},"description":"Structured view of a program's Identification Division"},"ParagraphDto":{"type":"object","properties":{"name":{"type":"string","description":"Paragraph name"},"sectionName":{"type":"string","description":"Name of the section this paragraph belongs to, when any"},"statementCount":{"type":"integer","description":"Number of statements contained in the paragraph","format":"int32"}},"description":"A paragraph declared in the Procedure Division"},"ProgramUnitDto":{"type":"object","properties":{"identificationDivision":{"$ref":"#/components/schemas/IdentificationDivisionDto"},"dataDivision":{"$ref":"#/components/schemas/DataDivisionDto"},"paragraphs":{"type":"array","description":"Paragraphs declared in the Procedure Division","items":{"$ref":"#/components/schemas/ParagraphDto"}},"calls":{"type":"array","description":"CALL statements found in the Procedure Division","items":{"$ref":"#/components/schemas/CallDto"}}},"description":"Structured (ASG) view of a single COBOL program unit"}}}}