Curl to JSON Schema

A Node.js library that converts curl commands to JSON schemas.

Features

• 🔧 Parse curl commands and extract HTTP details
• 📋 Generate JSON schemas from parsed curl data
• 🔄 Merge schemas from multiple curl commands
• 📊 Accumulate schemas from multiple curl commands with .toSchema()
• 🎯 Smart type inference and format detection
• 💻 CLI tool for batch processing curl commands from files
• 📚 Comprehensive test suite using Node.js built-in test runner

Installation

npm install curl-to-json-schema

CLI Usage

After installation, you can use the CLI tool to generate schemas from files containing curl commands:

# Generate schema from a file
curl-to-json-schema curls.txt

# Save to a file
curl-to-json-schema curls.txt -o schema.json

# Extend an existing schema
curl-to-json-schema new-curls.txt -s existing-schema.json -o merged-schema.json

# Compact output
curl-to-json-schema curls.txt --compact

# Show help
curl-to-json-schema --help

Input file format:

Create a text file with one curl command per line. Empty lines and lines starting with # are ignored:

# API endpoints for user management
curl https://api.example.com/users
curl -X POST -H "Content-Type: application/json" -d '{"name":"John"}' https://api.example.com/users
curl -X PUT -d '{"name":"Jane","age":25}' https://api.example.com/users/123

# Product endpoints
curl https://api.example.com/products

Quick Start

import { CurlToJsonSchema } from 'curl-to-json-schema'

const converter = new CurlToJsonSchema()

// Convert a curl command to JSON schema
const schema = converter.convert(`
  curl -X POST \\
    -H "Content-Type: application/json" \\
    -H "Authorization: Bearer token123" \\
    -d '{"name":"John","email":"john@example.com"}' \\
    https://api.example.com/users
`)

console.log(schema)
// {
//   "$schema": "http://json-schema.org/draft-07/schema#",
//   "type": "object",
//   "properties": {
//     "method": { "type": "string", "enum": ["POST"] },
//     "url": { "type": "string", "format": "uri", "const": "https://api.example.com/users" },
//     "headers": { ... },
//     "body": {
//       "type": "object",
//       "properties": {
//         "name": { "type": "string" },
//         "email": { "type": "string", "format": "email" }
//       }
//     }
//   }
// }

API Reference

CurlToJsonSchema

Main class for converting curl commands to JSON schemas.

Constructor

const converter = new CurlToJsonSchema(options)

Options:

• schema: An existing JSON schema to start with. All subsequent convert() calls will merge with this initial schema.

Example with existing schema:

const existingSchema = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  type: 'object',
  properties: {
    method: { type: 'string', enum: ['GET'] },
    url: { type: 'string', format: 'uri' }
  },
  required: ['method', 'url']
}

const converter = new CurlToJsonSchema({ schema: existingSchema })

// New curl commands will be merged with the existing schema
converter.convert('curl -X POST -d \'{"name":"Alice"}\' https://api.example.com/users')

const schema = converter.toSchema()
// schema now includes both GET and POST methods

Methods

convert(curlCommand)

Converts a single curl command to a JSON schema.

const schema = converter.convert('curl -X GET https://api.example.com/users')

convertMultiple(curlCommands)

Converts multiple curl commands and merges them into a single schema.

const schema = converter.convertMultiple([
  'curl https://api.example.com/users',
  'curl -X POST -d \'{"name":"John"}\' https://api.example.com/users'
])

toSchema()

Returns the accumulated JSON schema from all previously converted curl commands.

const converter = new CurlToJsonSchema()

// Convert multiple commands
converter.convert('curl https://api.example.com/products')
converter.convert('curl -X POST -d \'{"name":"Product A"}\' https://api.example.com/products')
converter.convert('curl -X PUT -d \'{"name":"Product B","inStock":true}\' https://api.example.com/products/123')

// Get the merged schema
const schema = converter.toSchema()
// Returns merged schema with methods: ['GET', 'POST', 'PUT']

Supported Curl Features

HTTP Methods

• GET, POST, PUT, PATCH, DELETE
• Auto-detection of POST when data is provided

Headers

curl -H "Content-Type: application/json" -H "Authorization: Bearer token"

Authentication

curl -u username:password  # Basic auth
curl -H "Authorization: Bearer token"  # Bearer token

Request Data

curl -d '{"key":"value"}'  # JSON data
curl -d "key=value&foo=bar"  # Form data
curl --data-raw '{"json":"data"}'  # Raw data

Query Parameters

curl "https://api.com/search?q=test&limit=10"

Special Headers

curl -A "Custom-Agent"  # User-Agent
curl -e "https://referrer.com"  # Referer
curl -b "session=abc123"  # Cookie

Schema Generation Features

Smart Type Inference

• Automatically detects data types (string, number, integer, boolean, array, object)
• Recognizes common formats:
  • Email addresses
  • URLs
  • UUIDs
  • Date and datetime strings

Required Fields Detection

• Marks authentication headers as required
• Identifies critical headers (Content-Type, Authorization, API keys)
• Preserves required structure from request body

Schema Merging

When processing multiple curl commands, the library intelligently merges schemas:

• Combines allowed values for enums
• Merges object properties
• Handles conflicting types with oneOf
• Maintains required fields across all variations

Schema Accumulation

The toSchema() method allows progressive schema building:

• Accumulates schemas from all convert() and convertMultiple() calls
• Automatically merges properties and methods from all curl commands
• Ideal for building comprehensive API schemas from multiple examples
• Returns empty schema when no commands have been processed

Examples

Run the example script to see various usage patterns:

node example.js

Example Output

// Simple GET request
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "method": { "type": "string", "enum": ["GET"] },
    "url": { "type": "string", "format": "uri", "const": "https://api.example.com/users" }
  },
  "required": ["method", "url"]
}

// POST with JSON body
{
  "properties": {
    "method": { "enum": ["POST"] },
    "body": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "age": { "type": "integer" }
      }
    }
  }
}

Development

Running Tests

npm test           # Run all tests
npm run test:watch # Run tests in watch mode

Linting

npm run lint       # Check code style
npm run lint:fix   # Fix linting issues

Project Structure

├── lib/
│   ├── curlParser.js      # Curl command parsing
│   └── schemaGenerator.js # JSON schema generation
├── test/
│   ├── curlParser.test.js
│   ├── schemaGenerator.test.js
│   └── integration.test.js
├── index.js               # Main entry point
├── example.js             # Usage examples
└── package.json

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request