Merge pull request #4939 from ralfhandl/gh-pages-refactor-start-page

gh-pages: Split off spec-specific index pages

Author: handrews

arazzo/index.md

@@ -0,0 +1,19 @@
+---
+title: Arazzo Specification
+description: Arazzo Specification
+layout: default
+---
+
+# Arazzo Specification
+
+## Specification Versions
+
+{% include specification-version-list.md specification="arazzo" %}
+
+## Schema Iterations
+
+_Note that while schemas can catch many errors, they are not guaranteed to catch all specification violations.  In the event of a disagreement between the schemas and the corresponding specification text, the specification text is presumed to be correct._
+
+A minor release (e.g. v1.0) has one or more published schemas, identified with the release 1.0 and a revision date like 2024-12-16.  All schemas for a given minor release apply to all patch releases within that minor release (e.g. 1.0.1, 1.0.0, etc.).  The dates are purely a way to uniquely identify the revision, and are not intended to be correlated with patch release publication dates.  The latest date within a minor release is always the most correct schema for all patch releases, and previous revisions are obsolete.
+
+{% include schema-iteration-list.md specification="arazzo" %}

index.md

@@ -1,29 +1,23 @@
 ---
 title: Home
+nav_order: 1
 description: HTML Spec. and extensible registry
 layout: default
 ---
 
 # OpenAPI Initiative Publications
 
-This site contains the authoritative HTML renderings of the OpenAPI Initiative's [specifications](#specifications) and [extension registries](#registries), as well as official (but non-[normative](https://en.wikipedia.org/wiki/Normativity#Standards_documents)) [schemas](#non-normative-json-schemas) for those specifications that provide them.
+This site contains the authoritative HTML renderings of the OpenAPI Initiative's [specifications](#specifications) and [extension registries](#registries).
 
 Please see the [Learn OpenAPI](https://learn.openapis.org) site for additional documentation and [examples](https://learn.openapis.org/examples/), and the [OpenAPI Tooling](https://tools.openapis.org/) site for community-provided lists of tools implementing the specifications.
 
 ## Specifications
 
-### Arazzo Specification
+Each specification page lists all published specification versions and official (but non-[normative](https://en.wikipedia.org/wiki/Normativity#Standards_documents)) schema iterations.
 
-{% include specification-version-list.md specification="arazzo" %}
-
-### OpenAPI Specification
-
-{% include specification-version-list.md specification="oas" %}
-* **[v2.0]({{ site.baseurl }}/oas/v2.0.html)**
-
-### Overlay Specification
-
-{% include specification-version-list.md specification="overlay" %}
+* [Arazzo Specification](./arazzo/)
+* [OpenAPI Specification](./oas/)
+* [Overlay Specification](./overlay/)
 
 ## Registries
 
@@ -32,25 +26,3 @@ The [Registry Page](./registry/index.html) includes documentation as well as API
 Registry shortcuts:
 {% for registry in site.collections %}{% unless registry.hidden %}
 * <a href="registry/{{ registry.slug }}">{{ registry.name }}</a>{% endunless %}{% endfor %}
-
-## Non-Normative JSON Schemas
-
-_Note that while schemas can catch many errors, they are not guaranteed to catch all specification violations.  In the event of a disagreement between the schemas and the corresponding specificaton text, the specification text is presumed to be correct._
-
-A minor release (e.g. OAS 3.1) has one or more published schemas, identified with the release 3.1 and a revision date like 2021-03-02.  All schemas for a given minor release apply to all patch releases within that minor release (e.g. 3.1.0, 3.1.1, 3.1.2, etc.).  The dates are purely a way to uniquely identify the revision, and are not intended to be correlated with patch release publication dates.  The latest date within a minor release is always the most correct schema for all patch releases, and previous versions are obsolete.
-
-### Arazzo Schemas
-
-{% include schema-iteration-list.md specification="arazzo" %}
-
-### OpenAPI Specification Schemas
-
-Note that the OAS 3.1+ `schema/YYYY-MM-DD` schemas do _not_ validate the Schema Object, as they make no assumptions about the JSON Schema dialect in use.  The OAS 3.1+ `schema-base/YYYY-MM-DD` schemas _do_ validate the Schema Object, and require that if `jsonSchemaDialect` or `$schema` are present, that they use the appropriate `dialect/YYYY-MM-DD`.  The name `schema-base` comes from the JSON Schema dialect including the OAS extensions being referred to as the "base dialect" in the specification.
-
-See [issue #4147](https://github.com/OAI/OpenAPI-Specification/issues/4147) for discussion of other possible JSON Schema dialect options, [issue #4152](https://github.com/OAI/OpenAPI-Specification/issues/4152) for programmatic access to the latest schemas, and [issue #4141](https://github.com/OAI/OpenAPI-Specification/issues/4141) for discussions on possibly providing linting schemas that could catch likely problems that do not directly violate the specification.
-
-{% include schema-iteration-list.md specification="oas" %}
-
-### Overlay Specification Schemas
-
-{% include schema-iteration-list.md specification="overlay" %}

oas/index.md

@@ -0,0 +1,23 @@
+---
+title: OpenAPI Specification
+description: OpenAPI Specification
+layout: default
+---
+
+# OpenAPI Specification
+
+## Specification Versions
+
+{% include specification-version-list.md specification="oas" %}
+
+## Schema Iterations
+
+_Note that while schemas can catch many errors, they are not guaranteed to catch all specification violations.  In the event of a disagreement between the schemas and the corresponding specification text, the specification text is presumed to be correct._
+
+A minor release (e.g. v3.1) has one or more published schemas, identified with the release 3.1 and a revision date like 2021-03-02.  All schemas for a given minor release apply to all patch releases within that minor release (e.g. 3.1.0, 3.1.1, 3.1.2, etc.).  The dates are purely a way to uniquely identify the revision, and are not intended to be correlated with patch release publication dates.  The latest date within a minor release is always the most correct schema for all patch releases, and previous revisions are obsolete.
+
+Note that the v3.1+ `schema/YYYY-MM-DD` schemas do _not_ validate the Schema Object, as they make no assumptions about the JSON Schema dialect in use.  The v3.1+ `schema-base/YYYY-MM-DD` schemas _do_ validate the Schema Object, and require that if `jsonSchemaDialect` or `$schema` are present, that they use the appropriate `dialect/YYYY-MM-DD`.  The name `schema-base` comes from the JSON Schema dialect including the OAS extensions being referred to as the "base dialect" in the specification.
+
+See [issue #4147](https://github.com/OAI/OpenAPI-Specification/issues/4147) for discussion of other possible JSON Schema dialect options, [issue #4152](https://github.com/OAI/OpenAPI-Specification/issues/4152) for programmatic access to the latest schemas, and [issue #4141](https://github.com/OAI/OpenAPI-Specification/issues/4141) for discussions on possibly providing linting schemas that could catch likely problems that do not directly violate the specification.
+
+{% include schema-iteration-list.md specification="oas" %}

overlay/index.md

@@ -0,0 +1,19 @@
+---
+title: Overlay Specification
+description: Overlay Specification
+layout: default
+---
+
+# Overlay Specification
+
+## Specification Versions
+
+{% include specification-version-list.md specification="overlay" %}
+
+## Schema Iterations
+
+_Note that while schemas can catch many errors, they are not guaranteed to catch all specification violations.  In the event of a disagreement between the schemas and the corresponding specification text, the specification text is presumed to be correct._
+
+A minor release (e.g. v1.0) has one or more published schemas, identified with the release 1.0 and a revision date like 2024-10-22.  All schemas for a given minor release apply to all patch releases within that minor release (e.g. 1.0.1, 1.0.0, etc.).  The dates are purely a way to uniquely identify the revision, and are not intended to be correlated with patch release publication dates.  The latest date within a minor release is always the most correct schema for all patch releases, and previous revisions are obsolete.
+
+{% include schema-iteration-list.md specification="overlay" %}