OASIS v2.0 - User Guide

Interface Reference

Global Navigation

Tabs: switch between the four main modes: OAS to Excel, Excel to OAS, Validation, and View.
Menu Bar:
- File: Context-aware "Smart Select" that opens the relevant folder chooser based on your active tab.
- View: Access to all application tabs (Import, Generation, Validation, View) and Application Logs (detached window).
- Edit: Open the Preferences dialog.

Tab 1: OAS to Excel (Import)

Used for migrating legacy specs to the OASIS format.

Source File/Folder: Select a single `.yaml/.json` file or a folder of specs.
Output Folder: Where the generated `.xlsx` templates will be saved.
Import Button: Starts the reverse-engineering process. It generates an $index.xlsx (global metadata) and individual endpoint files.

Import & Roundtrip Log Reference

The internal log area in this tab provides detailed feedback during operations.

1. Import Process

Tracks file generation:

Step 1: Index creation ($index.xlsx).
Step 2: Endpoint file creation.
Validation: Reports success count or permission errors.

2. Roundtrip Check (Audit)

The Roundtrip Check compiles your newly created Excel templates back into a temporary OAS file and compares it against your original source to ensure "Lossless Migration".

1. Standard (Structure Only):

Compacts validation into a clean summary table.

2. Forensic (Line Diff Enabled):

Expands to show detailed line-by-line comparison and per-component breakdown.

Structure Summary: Compares high-level object counts. Match (✓) = 100% Structural Fidelity.
Line Diff (Forensic Audit): If enabled, compares the exact YAML line count.

Understanding Differences:

Perfect Match (✓ / 0 Delta): No differences found.
Physiological Delta (Variable): Common and usually benign. The acceptable range depends on the component's size and description verbosity. For example, a large schema with many text fields might show a delta of ±15-20 lines purely due to how YAML wraps text.
Structural Mismatch (Significant Delta): If a delta is disproportionately large relative to the component size, it may indicate a dropped construct (e.g., an unsupported keyword). Use the line count to target these specific discrepancies.

Tab 2: Excel to OAS (Generation)

The main engine for compiling your work.

Template Folder: The directory containing your $index.xlsx and endpoint `.xlsx` files.
OAS Output Folder: Where the final specs will be generated.
Version Toggles:
- OAS 3.1 / OAS 3.0: Multi-select. Choose one or both versions. If both are selected, the tool generates two separate specification files simultaneously.
- OAS SWIFT: Generates additional OAS outputs specifically customized for SWIFT integration. These files include the metadata x-info-customization: SWIFT in the Info section, alongside your standard 3.0/3.1 files.
Font Size: Logic slider (8-24px) to adjust the readability of the real-time log console.

Generation Log Reference

The console provides real-time feedback on the generation process, including confirmation of specific version outputs (3.0, 3.1, SWIFT).

Advanced: Custom Filename Patterns

You can customize the naming convention of the generated files by defining a filename pattern in the General Description sheet of your $index.xlsx.

Supported placeholders (enclosed in angle brackets):

<current_date>: The current date (Format: YYYYMMDD).
<oas_version>: Returns "3.0" or "3.1".
<customization>: Returns "_SWIFT" (if SWIFT OAS is generated) or an empty string.
<api_version>: Taken from the info version field (e.g., "5.0.8").
<release>: Taken from the release field (e.g., "v20260418").

Example Output:

Tab 3: Validation

Post-generation quality assurance.

Hover to play animation

1. Controls & Configuration

OAS Folder: The directory containing your generated specification files.
Select File: Dropdown list of all OAS files found in the folder (sorted by modification time).
Refresh Button (↻): Reloads the file list. Use this if you have generated new files or modified the folder contents externally.
Ignore 'Bad Request' Examples:
When checked, the validator skips errors in examples named Bad Request.
Context: These examples are intentionally malformed to support the API Developer Portal Playground (simulating 400 responses). Enabling this option prevents them from being flagged as semantic errors.

2. Semantic Pie Chart

An interactive visual breakdown of validation results.

Colors: Shades of Red (Errors), Shades of Amber (Warnings).
Interactivity:
- Hover: Hovering over a slice displays a tooltip with the exact count and the rule's description.
- Click: Clicking a slice opens the Spectral Rule Documentation (shown in overlay) for that specific error type.

3. Issues List

A detailed, clickable card list of all findings.

Issues Card: Displays Severity, Error Code, Path, and Message.
"Line [N]" Button: Jumps directly to the View Tab, loads the file, scrolls to the exact line, and highlights it for inspection.
"Template Sheet" Button: (If available) Opens the source Excel file directly to the relevant sheet, allowing you to fix the error at the source immediately.

4. Spectral Log

A collapsible section at the bottom showing the raw JSON output from the Spectral linter process. Useful for debugging configuration issues or "Spectral not found" errors.

Tab 4: View (YAML & Docs)

Technical inspection and final preview.

Hover to play animation

1. YAML Editor

Syntax Highlighting: Read-only editor optimized for large OAS files.
Toolbar:
- Customize appearance (Theme/Font) instantly.
- Locate in Docs: Scroll the HTML documentation to the endpoint corresponding to your current cursor position (based on the nearest operationId).
Shortcuts:
- Text Find (Ctrl+F): Search text within the code editor.

2. Documentation Viewer (Redocly)

Renders your API as a professional HTML page using Redocly.

Commands

Dock/Undock: Toggles the docking mechanism. Attaches the viewer to the right of the main window for easy comparison, or detaches it into a floating window.
Find in YAML: Syncs the view. Click a section in the docs to locate the corresponding definition in the YAML editor.
Save to HTML: Exports the current documentation as a standalone .html file.

Docking Behavior

By default, the viewer is Docked to the right. You can disable this permanently in Preferences, or temporarily by clicking the Undock button.

Extension	Description	Usage
`x-sandbox-*`	Playground Metadata. Family of extensions used by the API Developer Portal to generate simulated responses in the API Playground.	Defined in Excel via indented blocks.
`x-info-*`	General Metadata. Family of extensions containing release tracking info, creation date, and versioning details.	Auto-generated by OASIS during compilation.
`x-comment`	Analyst Comments. Propagates descriptions or notes from Excel references that override the standard definition.	Auto-generated when a Reference in Excel has a custom Description.