specifications/json-schema/specification-record-schema.json at main · api-evangelist/specifications · 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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/specifications/refs/heads/main/json-schema/specification-record-schema.json",
  "title": "SpecificationRecord",
  "description": "A normalized record describing a single API specification language — its name, current version, governing body, license, format, and tooling ecosystem.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Stable identifier for the specification.",
      "example": "openapi",
      "pattern": "^[a-z0-9][a-z0-9-]*$"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name of the specification.",
      "example": "OpenAPI Specification"
    },
    "aliases": {
      "type": "array",
      "description": "Alternative or historical names for the specification.",
      "items": { "type": "string" },
      "example": ["Swagger Specification", "OAS"]
    },
    "category": {
      "type": "string",
      "description": "The high-level category of specification.",
      "enum": [
        "HTTP Request/Response",
        "Event-Driven",
        "Service Interface (IDL)",
        "Schema",
        "RPC Protocol",
        "Vendor-Defined"
      ],
      "example": "HTTP Request/Response"
    },
    "currentVersion": {
      "type": "string",
      "description": "Latest stable specification version.",
      "example": "3.1.0"
    },
    "versions": {
      "type": "array",
      "description": "Known versions of the specification.",
      "items": {
        "type": "object",
        "properties": {
          "version": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["active", "deprecated", "draft", "historical"]
          },
          "releaseDate": { "type": "string", "format": "date" },
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["version", "status"]
      }
    },
    "governingBody": {
      "type": "object",
      "description": "Organization or working group responsible for the specification.",
      "properties": {
        "name": {
          "type": "string",
          "example": "OpenAPI Initiative"
        },
        "parent": {
          "type": "string",
          "description": "Umbrella foundation, if any.",
          "example": "Linux Foundation"
        },
        "url": { "type": "string", "format": "uri" },
        "governanceUrl": { "type": "string", "format": "uri" }
      },
      "required": ["name"]
    },
    "license": {
      "type": "object",
      "description": "License under which the specification is published.",
      "properties": {
        "id": {
          "type": "string",
          "description": "SPDX-style license identifier.",
          "example": "Apache-2.0"
        },
        "url": { "type": "string", "format": "uri" }
      },
      "required": ["id"]
    },
    "format": {
      "type": "string",
      "description": "Primary serialization format of the specification source.",
      "enum": ["YAML", "JSON", "Markdown", "XML", "DSL", "Protobuf", "Multiple"],
      "example": "YAML"
    },
    "transports": {
      "type": "array",
      "description": "Transports or protocols the specification targets.",
      "items": {
        "type": "string",
        "enum": [
          "HTTP/1.1",
          "HTTP/2",
          "HTTP/3",
          "WebSocket",
          "Kafka",
          "AMQP",
          "MQTT",
          "NATS",
          "SNS/SQS",
          "TCP",
          "gRPC",
          "XML/SOAP",
          "Multiple",
          "N/A"
        ]
      },
      "example": ["HTTP/1.1", "HTTP/2"]
    },
    "primaryUseCase": {
      "type": "string",
      "description": "The primary use case the specification is designed for.",
      "example": "Describing synchronous HTTP REST APIs and generating SDKs, documentation, and mocks."
    },
    "specificationUrl": {
      "type": "string",
      "format": "uri",
      "description": "Canonical URL of the current specification text."
    },
    "documentationUrl": {
      "type": "string",
      "format": "uri",
      "description": "Primary documentation entrypoint."
    },
    "repositoryUrl": {
      "type": "string",
      "format": "uri",
      "description": "Canonical source repository for the specification."
    },
    "toolingEcosystemUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL to the curated tooling directory for the specification.",
      "example": "https://tools.openapis.org/"
    },
    "tags": {
      "type": "array",
      "description": "Categorization tags (Title Case).",
      "items": { "type": "string" }
    },
    "status": {
      "type": "string",
      "description": "Overall lifecycle status of the specification.",
      "enum": ["active", "maintenance", "legacy", "historical", "emerging"],
      "example": "active"
    },
    "embeddedSchemaLanguage": {
      "type": "string",
      "description": "Schema language embedded inside the spec, if any.",
      "example": "JSON Schema 2020-12"
    },
    "emits": {
      "type": "array",
      "description": "Other specification formats this spec can be compiled/emitted to.",
      "items": { "type": "string" },
      "example": ["OpenAPI 3.0", "JSON Schema", "Protobuf"]
    }
  },
  "required": [
    "id",
    "name",
    "category",
    "currentVersion",
    "governingBody",
    "license",
    "primaryUseCase"
  ]
}