add description to all schemas

karenetheridge · karenetheridge · commit 8ab4f9700469 · 2021-12-01T20:10:45.000-08: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,5 @@
 {
+    "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": {
diff --git a/schemas/v3.1/dialect/base.schema.yaml b/schemas/v3.1/dialect/base.schema.yaml
@@ -1,4 +1,5 @@
 ---
+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
diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json
@@ -1,4 +1,5 @@
 {
+    "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": {
diff --git a/schemas/v3.1/meta/base.schema.yaml b/schemas/v3.1/meta/base.schema.yaml
@@ -1,4 +1,5 @@
 ---
+description: A JSON Schema Vocabulary used in the OpenAPI Schema Dialect
 $defs:
   discriminator:
     $ref: '#/$defs/extensible'
diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json
@@ -1,4 +1,5 @@
 {
+  "description": "A dialect to use for schemas within OpenAPI documents",
   "$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: A dialect to use for schemas within OpenAPI documents
 $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, 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, 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": "A JSON Schema dialect describing schemas found in OpenAPI documents",`
`2`	`3`	`"$id": "https://spec.openapis.org/oas/3.1/dialect/base",`
`3`	`4`	`"$schema": "https://json-schema.org/draft/2020-12/schema",`
`4`	`5`	`"$vocabulary": {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`---`
	`2`	`+description: A JSON Schema dialect describing schemas found in OpenAPI documents`
`2`	`3`	`$dynamicAnchor: meta`
`3`	`4`	`$id: https://spec.openapis.org/oas/3.1/dialect/base`
`4`	`5`	`$schema: https://json-schema.org/draft/2020-12/schema`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "description": "A JSON Schema Vocabulary used in the OpenAPI Schema Dialect",`
`2`	`3`	`"$id": "https://spec.openapis.org/oas/3.1/meta/base",`
`3`	`4`	`"$schema": "https://json-schema.org/draft/2020-12/schema",`
`4`	`5`	`"$vocabulary": {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`---`
	`2`	`+description: A JSON Schema Vocabulary used in the OpenAPI Schema Dialect`
`2`	`3`	`$defs:`
`3`	`4`	`discriminator:`
`4`	`5`	`$ref: '#/$defs/extensible'`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "description": "A dialect to use for schemas within OpenAPI documents",`
`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: A dialect to use for schemas within OpenAPI documents`
`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`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+description: The description of OpenAPI v3.1.x documents, as defined by https://spec.openapis.org/oas/v3.1.0`
`1`	`2`	`$id: 'https://spec.openapis.org/oas/3.1/schema/2021-09-28'`
`2`	`3`	`$schema: 'https://json-schema.org/draft/2020-12/schema'`
`3`	`4`