diff --git a/_config.yml b/_config.yml index 15d4ce98aa..0eeaf2fea2 100644 --- a/_config.yml +++ b/_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.
This work is licensed under the Apache 2.0 License. This site is\ diff --git a/index.md b/index.md index 6ba65e6939..86909241fe 100644 --- a/index.md +++ b/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 %} +* {{ registry.name }}{% 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_