Scalar · Schema

Scalar OpenAPI Document Reference

Schema representing an OpenAPI document managed in the Scalar Registry, including metadata, registry coordinates, and documentation configuration.

API ClientAPI DocumentationAPI ReferencesCode GenerationDeveloper ToolsOpenAPIRegistrySDKsSwagger

Properties

Name	Type	Description
namespace	string	Scalar Registry namespace (org/project format).
title	string	Human-readable API title.
version	string	API version string.
specUrl	string	URL to the OpenAPI document (YAML or JSON).
openAPIVersion	string	OpenAPI specification version.
visibility	string	Whether the registry entry is publicly accessible.
documentation	object	Scalar documentation configuration.
sdks	array	SDK generation configuration for this API.
spectralRulesets	array	Spectral rulesets applied to validate this document.
tags	array	Classification tags.
createdAt	string
updatedAt	string

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api-evangelist.com/schemas/scalar/openapi-document",
  "title": "Scalar OpenAPI Document Reference",
  "description": "Schema representing an OpenAPI document managed in the Scalar Registry, including metadata, registry coordinates, and documentation configuration.",
  "type": "object",
  "required": ["namespace", "title", "version", "specUrl"],
  "properties": {
    "namespace": {
      "type": "string",
      "description": "Scalar Registry namespace (org/project format).",
      "pattern": "^[a-z0-9-]+/[a-z0-9-]+$",
      "example": "my-org/payments-api"
    },
    "title": {
      "type": "string",
      "description": "Human-readable API title.",
      "example": "Payments API"
    },
    "version": {
      "type": "string",
      "description": "API version string.",
      "example": "2.1.0"
    },
    "specUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL to the OpenAPI document (YAML or JSON)."
    },
    "openAPIVersion": {
      "type": "string",
      "enum": ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0"],
      "description": "OpenAPI specification version.",
      "example": "3.1.0"
    },
    "visibility": {
      "type": "string",
      "enum": ["public", "private"],
      "description": "Whether the registry entry is publicly accessible.",
      "default": "private"
    },
    "documentation": {
      "type": "object",
      "description": "Scalar documentation configuration.",
      "properties": {
        "customDomain": {
          "type": "string",
          "description": "Custom domain for the published docs.",
          "example": "api-docs.example.com"
        },
        "theme": {
          "type": "string",
          "enum": ["default", "alternate", "moon", "purple", "solarized", "bluePlanet", "deepSpace", "saturn", "kepler", "mars", "none"],
          "description": "Scalar API Reference display theme.",
          "default": "default"
        },
        "darkMode": {
          "type": "boolean",
          "description": "Enable dark mode by default.",
          "default": false
        },
        "gitSync": {
          "type": "object",
          "description": "Git synchronization configuration.",
          "properties": {
            "enabled": { "type": "boolean" },
            "repository": {
              "type": "string",
              "description": "GitHub repository in owner/repo format."
            },
            "branch": {
              "type": "string",
              "description": "Branch to sync from.",
              "default": "main"
            },
            "specPath": {
              "type": "string",
              "description": "Path to OpenAPI file in the repository."
            }
          }
        }
      }
    },
    "sdks": {
      "type": "array",
      "description": "SDK generation configuration for this API.",
      "items": {
        "type": "object",
        "required": ["language"],
        "properties": {
          "language": {
            "type": "string",
            "enum": ["typescript", "python", "go", "php", "java", "ruby"],
            "description": "Target programming language."
          },
          "packageName": {
            "type": "string",
            "description": "Package/module name for the generated SDK.",
            "example": "payments-client"
          },
          "githubRepo": {
            "type": "string",
            "description": "GitHub repository for the generated SDK."
          }
        }
      }
    },
    "spectralRulesets": {
      "type": "array",
      "description": "Spectral rulesets applied to validate this document.",
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Classification tags."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}