workflow.schema.json

{
  "$defs": {
    "WorkflowAuth": {
      "additionalProperties": false,
      "description": "Authentication information for the document (optional)",
      "properties": {
        "authHeader": {
          "description": "A HTTP Header Name",
          "type": "string"
        },
        "authSecret": {
          "description": "A HTTP Header Value",
          "type": "string"
        }
      },
      "required": [
        "authHeader",
        "authSecret"
      ],
      "type": "object"
    },
    "WorkflowCodeSamples": {
      "additionalProperties": false,
      "description": "Code samples configuration. See https://www.speakeasy.com/guides/openapi/x-codesamples",
      "properties": {
        "blocking": {
          "description": "Defaults to true. If false, code samples failures will not consider the workflow as failed",
          "type": [
            "null",
            "boolean"
          ]
        },
        "disabled": {
          "description": "Optional flag to disable code samples.",
          "type": [
            "null",
            "boolean"
          ]
        },
        "labelOverride": {
          "$ref": "#/$defs/WorkflowCodeSamplesLabelOverride",
          "description": "Optional label override for the code sample. Default is to use the operationId."
        },
        "langOverride": {
          "description": "Optional language override for the code sample. Default behavior is to auto-detect.",
          "type": [
            "null",
            "string"
          ]
        },
        "output": {
          "description": "The output file name",
          "type": "string"
        },
        "registry": {
          "$ref": "#/$defs/WorkflowSourceRegistry",
          "description": "The output registry location."
        },
        "style": {
          "description": "Optional style for the code sample, one of 'standard' or 'readme'. Default is 'standard'.",
          "type": [
            "null",
            "string"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowCodeSamplesLabelOverride": {
      "properties": {
        "fixedValue": {
          "description": "Optional fixed value for the label.",
          "type": [
            "null",
            "string"
          ]
        },
        "omit": {
          "description": "Optional flag to omit the label.",
          "type": [
            "null",
            "boolean"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowDependent": {
      "additionalProperties": false,
      "description": "A dependent configuration for external repositories",
      "properties": {
        "cloneCommand": {
          "description": "Optional command to clone the repository",
          "type": "string"
        },
        "location": {
          "description": "The local path to the repository",
          "type": "string"
        }
      },
      "required": [
        "location"
      ],
      "type": "object"
    },
    "WorkflowDeployment": {
      "additionalProperties": false,
      "description": "Gram deployment configuration for MCP servers. Presence of this block enables deployment.",
      "properties": {
        "project": {
          "description": "Gram project name. Defaults to Gram's authenticated org context.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "WorkflowDocument": {
      "additionalProperties": false,
      "description": "A local or remote document.",
      "properties": {
        "authHeader": {
          "description": "A HTTP Header Name",
          "type": "string"
        },
        "authSecret": {
          "description": "A HTTP Header Value",
          "type": "string"
        },
        "location": {
          "description": "The location to resolve the document at. E.g. a file name, relative location, or a HTTP URL",
          "minLength": 1,
          "type": "string"
        },
        "modelNamespace": {
          "description": "The model namespace/group for component schemas (used when merging multiple documents)",
          "type": "string"
        }
      },
      "required": [
        "location"
      ],
      "type": "object"
    },
    "WorkflowFallbackCodeSamples": {
      "properties": {
        "fallbackCodeSamplesLanguage": {
          "type": "string"
        }
      },
      "required": [
        "fallbackCodeSamplesLanguage"
      ],
      "type": "object"
    },
    "WorkflowFilterOperationsOptions": {
      "properties": {
        "exclude": {
          "description": "Exclude the specified operations (mutually exclusive with include)",
          "type": [
            "null",
            "boolean"
          ]
        },
        "include": {
          "description": "Include the specified operations (mutually exclusive with exclude)",
          "type": [
            "null",
            "boolean"
          ]
        },
        "operations": {
          "description": "Comma-separated list of operations to filter",
          "type": "string"
        }
      },
      "required": [
        "operations"
      ],
      "type": "object"
    },
    "WorkflowJava": {
      "additionalProperties": false,
      "properties": {
        "gpgPassPhrase": {
          "type": "string"
        },
        "gpgSecretKey": {
          "type": "string"
        },
        "ossrhPassword": {
          "type": "string"
        },
        "ossrhUsername": {
          "type": "string"
        },
        "useSonatypeLegacy": {
          "type": "boolean"
        }
      },
      "required": [
        "ossrhUsername",
        "ossrhPassword",
        "gpgSecretKey",
        "gpgPassPhrase",
        "useSonatypeLegacy"
      ],
      "type": "object"
    },
    "WorkflowMockServer": {
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "description": "Defaults to true. If false, the mock API server will not be started.",
          "type": [
            "null",
            "boolean"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowNPM": {
      "additionalProperties": false,
      "properties": {
        "token": {
          "type": "string"
        }
      },
      "required": [
        "token"
      ],
      "type": "object"
    },
    "WorkflowNormalizeOptions": {
      "properties": {
        "prefixItems": {
          "type": [
            "null",
            "boolean"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowNuget": {
      "additionalProperties": false,
      "properties": {
        "apiKey": {
          "type": "string"
        }
      },
      "required": [
        "apiKey"
      ],
      "type": "object"
    },
    "WorkflowOverlay": {
      "oneOf": [
        {
          "$ref": "#/$defs/WorkflowDocument"
        },
        {
          "properties": {
            "fallbackCodeSamplesLanguage": {
              "type": "string"
            }
          },
          "required": [
            "fallbackCodeSamplesLanguage"
          ],
          "type": "object"
        }
      ]
    },
    "WorkflowPackagist": {
      "additionalProperties": false,
      "properties": {
        "token": {
          "type": "string"
        },
        "username": {
          "type": "string"
        }
      },
      "required": [
        "username",
        "token"
      ],
      "type": "object"
    },
    "WorkflowPublishing": {
      "additionalProperties": false,
      "description": "The publishing configuration. See https://www.speakeasy.com/docs/workflow-reference/publishing-reference",
      "properties": {
        "java": {
          "$ref": "#/$defs/WorkflowJava",
          "description": "Maven (Java) publishing configuration."
        },
        "npm": {
          "$ref": "#/$defs/WorkflowNPM",
          "description": "NPM (Typescript) publishing configuration."
        },
        "nuget": {
          "$ref": "#/$defs/WorkflowNuget",
          "description": "NuGet (C#) publishing configuration."
        },
        "packagist": {
          "$ref": "#/$defs/WorkflowPackagist",
          "description": "Packagist (PHP) publishing configuration."
        },
        "pypi": {
          "$ref": "#/$defs/WorkflowPyPi",
          "description": "PyPI (Python)publishing configuration."
        },
        "rubygems": {
          "$ref": "#/$defs/WorkflowRubyGems",
          "description": "Rubygems (Ruby) publishing configuration."
        },
        "terraform": {
          "$ref": "#/$defs/WorkflowTerraform"
        }
      },
      "type": "object"
    },
    "WorkflowPyPi": {
      "additionalProperties": false,
      "properties": {
        "token": {
          "description": "PyPI API token for token-based authentication. Not required if using trusted publishing.",
          "type": "string"
        },
        "useTrustedPublishing": {
          "description": "Use OIDC trusted publishing instead of token-based authentication. See https://docs.pypi.org/trusted-publishers/",
          "type": [
            "null",
            "boolean"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowRubyGems": {
      "additionalProperties": false,
      "properties": {
        "token": {
          "type": "string"
        }
      },
      "required": [
        "token"
      ],
      "type": "object"
    },
    "WorkflowSource": {
      "description": "A source configuration",
      "properties": {
        "inputs": {
          "description": "A list of input documents (OpenAPI Specifications). These will be merged together",
          "items": {
            "$ref": "#/$defs/WorkflowDocument"
          },
          "minItems": 1,
          "type": [
            "array",
            "null"
          ]
        },
        "output": {
          "description": "The output file name (optional)",
          "type": [
            "null",
            "string"
          ]
        },
        "overlays": {
          "description": "A list of overlay files (OpenAPI Overlay Specification)",
          "items": {
            "$ref": "#/$defs/WorkflowOverlay"
          },
          "type": "array"
        },
        "registry": {
          "$ref": "#/$defs/WorkflowSourceRegistry",
          "description": "The openapi registry configuration"
        },
        "ruleset": {
          "description": "The linting ruleset to use (optional)",
          "type": [
            "null",
            "string"
          ]
        },
        "transformations": {
          "description": "A list of transformations to apply to the OpenAPI document",
          "items": {
            "$ref": "#/$defs/WorkflowTransformation"
          },
          "type": "array"
        }
      },
      "required": [
        "inputs"
      ],
      "type": "object"
    },
    "WorkflowSourceRegistry": {
      "description": "The openapi registry configuration",
      "properties": {
        "location": {
          "description": "The registry location to use (for snapshotting/change tracking)",
          "type": "string"
        },
        "tags": {
          "description": "The list of tags to use for the registry",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "location"
      ],
      "type": "object"
    },
    "WorkflowTarget": {
      "additionalProperties": false,
      "properties": {
        "codeSamples": {
          "$ref": "#/$defs/WorkflowCodeSamples"
        },
        "deployment": {
          "$ref": "#/$defs/WorkflowDeployment"
        },
        "output": {
          "type": [
            "null",
            "string"
          ]
        },
        "publish": {
          "$ref": "#/$defs/WorkflowPublishing"
        },
        "source": {
          "type": "string"
        },
        "target": {
          "enum": [
            "csharp",
            "go",
            "java",
            "mcp-typescript",
            "php",
            "python",
            "ruby",
            "swift",
            "terraform",
            "typescript",
            "unity",
            "postman"
          ],
          "type": "string"
        },
        "testing": {
          "$ref": "#/$defs/WorkflowTesting"
        }
      },
      "required": [
        "target",
        "source"
      ],
      "type": "object"
    },
    "WorkflowTerraform": {
      "properties": {
        "gpgPassPhrase": {
          "type": "string"
        },
        "gpgPrivateKey": {
          "type": "string"
        }
      },
      "required": [
        "gpgPrivateKey",
        "gpgPassPhrase"
      ],
      "type": "object"
    },
    "WorkflowTesting": {
      "additionalProperties": false,
      "description": "Target testing configuration. By default, targets are not tested as part of the workflow.",
      "properties": {
        "enabled": {
          "description": "Defaults to false. If true, the target will be tested as part of the workflow.",
          "type": [
            "null",
            "boolean"
          ]
        },
        "mockServer": {
          "$ref": "#/$defs/WorkflowMockServer",
          "description": "Mock API server configuration for testing. By default and if generated, the mock API server is started before testing and used."
        }
      },
      "type": "object"
    },
    "WorkflowTransformation": {
      "additionalProperties": false,
      "maxProperties": 1,
      "minProperties": 1,
      "properties": {
        "cleanup": {
          "description": "Clean up the OpenAPI document",
          "type": [
            "null",
            "boolean"
          ]
        },
        "filterOperations": {
          "$ref": "#/$defs/WorkflowFilterOperationsOptions",
          "description": "Filter operations from the OpenAPI document"
        },
        "format": {
          "type": [
            "null",
            "boolean"
          ]
        },
        "jqSymbolicExecution": {
          "type": [
            "null",
            "boolean"
          ]
        },
        "normalize": {
          "$ref": "#/$defs/WorkflowNormalizeOptions"
        },
        "removeUnused": {
          "description": "Remove unused components from the OpenAPI document",
          "type": [
            "null",
            "boolean"
          ]
        }
      },
      "type": "object"
    },
    "WorkflowVersion": {
      "oneOf": [
        {
          "const": "latest",
          "description": "The latest version of the speakeasy CLI"
        },
        {
          "const": "pinned",
          "description": "The installed version of the speakeasy CLI"
        },
        {
          "description": "A semver version of the speakeasy CLI, corresponding to https://github.com/speakeasy-api/speakeasy/releases",
          "pattern": "^\\d+\\.\\d+\\.\\d+$",
          "type": "string"
        }
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "dependents": {
      "additionalProperties": {
        "$ref": "#/$defs/WorkflowDependent"
      },
      "description": "A map of dependent names to dependent configurations, used to define external repositories and their locations",
      "type": "object"
    },
    "sources": {
      "additionalProperties": {
        "$ref": "#/$defs/WorkflowSource"
      },
      "description": "A map of source names to source configurations, where the output is an OpenAPI document",
      "type": [
        "object",
        "null"
      ]
    },
    "speakeasyVersion": {
      "$ref": "#/$defs/WorkflowVersion",
      "description": "The version of the speakeasy CLI"
    },
    "targets": {
      "additionalProperties": {
        "$ref": "#/$defs/WorkflowTarget"
      },
      "description": "A map of target names to target configurations, where the output is a speakeasy generation target",
      "type": [
        "object",
        "null"
      ]
    },
    "workflowVersion": {
      "const": "1.0.0",
      "description": "The version of the workflow schema",
      "type": "string"
    }
  },
  "required": [
    "workflowVersion"
  ],
  "title": "Speakeasy Workflow Schema",
  "type": "object"
}