URIPathVersion

URI path versioning configuration and metadata for a REST API

API DesignBackward CompatibilitySoftware DevelopmentVersion ControlSemantic VersioningAPI LifecycleDeprecation

Properties

Name	Type	Description
basePath	string	Base path without version prefix
versionPrefix	string	Version prefix used in path (e.g., v, version)
currentVersion	integer	Current major API version number
supportedVersions	array	List of currently supported major version numbers
deprecatedVersions	array	List of deprecated major version numbers
paths	array	Version-specific path configurations

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/versioning-protocols/refs/heads/main/json-schema/versioning-protocols-uri-path-versioning-schema.json",
  "title": "URIPathVersion",
  "description": "URI path versioning configuration and metadata for a REST API",
  "type": "object",
  "properties": {
    "basePath": {
      "type": "string",
      "description": "Base path without version prefix",
      "example": "/api"
    },
    "versionPrefix": {
      "type": "string",
      "description": "Version prefix used in path (e.g., v, version)",
      "example": "v"
    },
    "currentVersion": {
      "type": "integer",
      "minimum": 1,
      "description": "Current major API version number",
      "example": 2
    },
    "supportedVersions": {
      "type": "array",
      "items": { "type": "integer" },
      "description": "List of currently supported major version numbers",
      "example": [1, 2]
    },
    "deprecatedVersions": {
      "type": "array",
      "items": { "type": "integer" },
      "description": "List of deprecated major version numbers",
      "example": [1]
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "version": { "type": "integer" },
          "path": { "type": "string" },
          "deprecated": { "type": "boolean" },
          "sunsetDate": { "type": "string", "format": "date" }
        }
      },
      "description": "Version-specific path configurations",
      "example": [
        { "version": 2, "path": "/api/v2", "deprecated": false },
        { "version": 1, "path": "/api/v1", "deprecated": true, "sunsetDate": "2027-01-01" }
      ]
    }
  },
  "required": ["currentVersion"]
}