add description to all schemas (#2802)

karenetheridge · web-flow · commit 80c781e479f8 · 2022-02-24T09:39:32.000-07:00
in v3.1 the number of schemas increased considerably, which can be a bit confusing.
diff --git a/schemas/v3.0/schema.json b/schemas/v3.0/schema.json
@@ -1,7 +1,7 @@
 {
   "id": "https://spec.openapis.org/oas/3.0/schema/2021-09-28",
   "$schema": "http://json-schema.org/draft-04/schema#",
-  "description": "Validation schema for OpenAPI Specification 3.0.X.",
+  "description": "The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3",
   "type": "object",
   "required": [
     "openapi",
diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml
@@ -1,6 +1,6 @@
 id: https://spec.openapis.org/oas/3.0/schema/2021-09-28
 $schema: http://json-schema.org/draft-04/schema#
-description: Validation schema for OpenAPI Specification 3.0.X.
+description: The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3
 type: object
 required:
   - openapi
diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json
@@ -1,4 +1,6 @@
 {
+    "title": "OpenAPI 3.1 Schema Object Dialect",
+    "description": "A JSON Schema dialect describing schemas found in OpenAPI documents",
     "$id": "https://spec.openapis.org/oas/3.1/dialect/base",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$vocabulary": {
@@ -13,7 +15,6 @@
     },
     "$dynamicAnchor": "meta",
 
-    "title": "OpenAPI 3.1 Schema Object Dialect",
     "allOf": [
         { "$ref": "https://json-schema.org/draft/2020-12/schema" },
         { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" }
diff --git a/schemas/v3.1/dialect/base.schema.yaml b/schemas/v3.1/dialect/base.schema.yaml
@@ -1,4 +1,6 @@
 ---
+title: OpenAPI 3.1 Schema Object Dialect
+description: A JSON Schema dialect describing schemas found in OpenAPI documents
 $dynamicAnchor: meta
 $id: https://spec.openapis.org/oas/3.1/dialect/base
 $schema: https://json-schema.org/draft/2020-12/schema
@@ -14,4 +16,3 @@ $vocabulary:
 allOf:
 - $ref: https://json-schema.org/draft/2020-12/schema
 - $ref: https://spec.openapis.org/oas/3.1/meta/base
-title: OpenAPI 3.1 Schema Object Dialect
diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json
@@ -1,11 +1,12 @@
 {
+    "title": "OAS Base vocabulary",
+    "description": "A JSON Schema Vocabulary used in the OpenAPI Schema Dialect",
     "$id": "https://spec.openapis.org/oas/3.1/meta/base",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$vocabulary": {
         "https://spec.openapis.org/oas/3.1/vocab/base": true
     },
     "$dynamicAnchor": "meta",
-    "title": "OAS Base vocabulary",
 
     "type": ["object", "boolean"],
     "properties": {
diff --git a/schemas/v3.1/meta/base.schema.yaml b/schemas/v3.1/meta/base.schema.yaml
@@ -1,4 +1,6 @@
 ---
+title: OAS Base vocabulary
+description: A JSON Schema Vocabulary used in the OpenAPI Schema Dialect
 $defs:
   discriminator:
     $ref: '#/$defs/extensible'
@@ -57,7 +59,6 @@ properties:
     $ref: '#/$defs/external-docs'
   xml:
     $ref: '#/$defs/xml'
-title: OAS Base vocabulary
 type:
 - object
 - boolean
diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json
@@ -1,4 +1,5 @@
 {
+  "description": "The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0",
   "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-09-28",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-09-28",
diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml
@@ -1,3 +1,4 @@
+description: The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0
 $id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-09-28'
 $schema: 'https://json-schema.org/draft/2020-12/schema'
 
diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json
@@ -1,4 +1,5 @@
 {
+  "description": "The description of OpenAPI v3.1.x documents without schema validation, as defined by https://spec.openapis.org/oas/v3.1.0",
   "$id": "https://spec.openapis.org/oas/3.1/schema/2021-09-28",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml
@@ -1,3 +1,4 @@
+description: The description of OpenAPI v3.1.x documents without schema validation, as defined by https://spec.openapis.org/oas/v3.1.0
 $id: 'https://spec.openapis.org/oas/3.1/schema/2021-09-28'
 $schema: 'https://json-schema.org/draft/2020-12/schema'
 

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"id": "https://spec.openapis.org/oas/3.0/schema/2021-09-28",`
`3`	`3`	`"$schema": "http://json-schema.org/draft-04/schema#",`
`4`		`- "description": "Validation schema for OpenAPI Specification 3.0.X.",`
	`4`	`+ "description": "The description of OpenAPI v3.0.x documents, as defined by https://spec.openapis.org/oas/v3.0.3",`
`5`	`5`	`"type": "object",`
`6`	`6`	`"required": [`
`7`	`7`	`"openapi",`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "description": "The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0",`
`2`	`3`	`"$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-09-28",`
`3`	`4`	`"$schema": "https://json-schema.org/draft/2020-12/schema",`
`4`	`5`	`"$ref": "https://spec.openapis.org/oas/3.1/schema/2021-09-28",`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+description: The description of OpenAPI v3.1.x documents using the OpenAPI JSON Schema dialect, as defined by https://spec.openapis.org/oas/v3.1.0`
`1`	`2`	`$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-09-28'`
`2`	`3`	`$schema: 'https://json-schema.org/draft/2020-12/schema'`
`3`	`4`