versioning/json-structure/versioning-api-version-structure.json at main · api-evangelist/versioning · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/versioning/refs/heads/main/json-structure/versioning-api-version-structure.json",
  "name": "APIVersion",
  "description": "A single released version of an API, including its identifier, release status, supported specification, and lifecycle dates.",
  "type": "object",
  "properties": {
    "api": {
      "type": "string",
      "description": "Identifier of the API this version belongs to.",
      "example": "stripe-payments"
    },
    "version": {
      "type": "string",
      "description": "Version identifier as advertised to consumers.",
      "example": "2024-04-10"
    },
    "scheme": {
      "type": "string",
      "enum": [
        "semver",
        "calver",
        "date",
        "integer",
        "custom"
      ],
      "description": "Versioning scheme used for the version identifier.",
      "example": "date"
    },
    "status": {
      "type": "string",
      "enum": [
        "preview",
        "stable",
        "deprecated",
        "sunset"
      ],
      "description": "Lifecycle status of this version.",
      "example": "stable"
    },
    "released_at": {
      "type": "date",
      "description": "Date the version was released to consumers.",
      "example": "2024-04-10"
    },
    "deprecated_at": {
      "type": "date",
      "description": "Date the version was marked deprecated, if applicable.",
      "example": "2026-04-10"
    },
    "sunset_at": {
      "type": "date",
      "description": "Date the version will be removed from service (Sunset HTTP header value, RFC 8594).",
      "example": "2027-04-10"
    },
    "spec_url": {
      "type": "uri",
      "description": "URL to the machine-readable specification (OpenAPI, AsyncAPI, GraphQL SDL, Protobuf) for this version.",
      "example": "https://stripe.com/docs/api/2024-04-10/openapi.yaml"
    },
    "changelog_url": {
      "type": "uri",
      "description": "URL to the human-readable changelog for this version.",
      "example": "https://stripe.com/docs/upgrades#2024-04-10"
    },
    "compatibility": {
      "type": "string",
      "enum": [
        "backward",
        "forward",
        "full",
        "none"
      ],
      "description": "Compatibility guarantee with the previous version of the API.",
      "example": "backward"
    },
    "version_header": {
      "type": "object",
      "description": "HTTP header used by clients to pin to this version.",
      "properties": {
        "name": {
          "type": "string",
          "example": "Stripe-Version"
        },
        "value": {
          "type": "string",
          "example": "2024-04-10"
        }
      }
    },
    "breaking_changes": {
      "type": "array",
      "description": "List of breaking change identifiers introduced by this version.",
      "items": {
        "type": "string"
      },
      "example": [
        "payment_intent.amount_received-removed"
      ]
    }
  },
  "required": [
    "api",
    "version",
    "scheme",
    "status"
  ]
}