Merge pull request #4226 from handrews/spec-title

gh-pages: Generalize registry site to publications

Author: ralfhandl

_config.yml

@@ -1,8 +1,8 @@
 # theme: just-the-docs
 remote_theme: just-the-docs/just-the-docs
 color_scheme: oai
-title: OpenAPI Initiative Registry
-description: Extensible data value repository
+title: OpenAPI Initiative Publications
+description: Specifications, registries, and schemas
 show_downloads: true
 excerpt_separator: ""
 collections_dir: /registries
@@ -59,10 +59,12 @@ plugins:
   - jekyll-remote-theme
   - jekyll-sitemap
 aux_links:
-  "Latest OpenAPI Specification":
+  "Latest OpenAPI Spec":
     - "https://spec.openapis.org/oas/latest.html"
-  "Latest Arazzo Specification":
+  "Latest Arazzo Spec":
     - "https://spec.openapis.org/arazzo/latest.html"
+  "Latest Overlay Spec":
+    - "https://spec.openapis.org/overlay/latest.html"
 footer_content: "\xA9 2024 OpenAPI Initiative.
  <br />This work is licensed under the <a rel=\"license\" href=\"https://www.apache.org/licenses/LICENSE-2.0\"\
   >Apache 2.0 License</a>. This site is\

index.md

@@ -4,27 +4,47 @@ description: HTML Spec. and extensible registry
 layout: default
 ---
 
-# OpenAPI Initiative Registry
+# OpenAPI Initiative Publications
 
-This site contains the OpenAPI Initiative Registry and content for the HTML versions of specifications managed by the OpenAPI Initiative such as the OpenAPI Specification and the Arazzo Specification.
+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.
 
-## Registry
+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.
 
-* Proceed to [Registry](./registry/index.html)
+## Specifications
 
-## Arazzo Specification
-
-### Versions
+### Arazzo Specification
 
 {% include specification-version-list.md specification="arazzo" %}
 
-## OpenAPI Specification
-
-### Versions
+### OpenAPI Specification
 
 {% include specification-version-list.md specification="oas" %}
 
-### Non-Normative JSON Schemas
+### Overlay Specification
+
+{% include specification-version-list.md specification="overlay" %}
+
+## Registries
+
+The [Registry Page](./registry/index.html) includes documentation as well as API and RSS access for all registries
+
+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._
+
+### Arazzo Schemas
+
+_TBD_
+
+### OpenAPI Specification Schemas
+
+Note that the OAS 3.1 `schema/YYYY-MM-DD` schema does _not_ validate the Schema Object, as it makes no assumptions about the JSON Schema dialect in use.  The OAS 3.1 `schema-base/YYYY-MM-DD` schema _does_ validate the Schema Object, and requires 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.
 
 {% assign schema_files = site.static_files | where: "extname", "" | sort: "path" | reverse %}
 {% assign last_version = "" %}
@@ -50,8 +70,6 @@ This site contains the OpenAPI Initiative Registry and content for the HTML vers
 {%- endif -%}
 {%- endfor %}
 
-## Overlay Specification
+### Overlay Specification Schemas
 
-### Versions
-
-{% include specification-version-list.md specification="overlay" %}
+_TBD_