dev: sync with main

.github/templates/agenda.md

@@ -1,4 +1,4 @@
-## Weekly meetings happen on Thursdays at 9am - 10am Pacific
+## Weekly meetings happen on Thursdays at 9am - 10am Pacific Standard Time / Pacific Daylight Time (UTC-0800, UTC-0700)
 
 This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. 
 
@@ -31,8 +31,7 @@ Intros and governance meta-topics (5 mins) | TDC | |
 Reports from Special Interest Groups (5 mins) | SIG members | |
 Any other business (add comments below to suggest topics) | TDC | |
 [Approved spec PRs](https://github.com/OAI/OpenAPI-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | @OAI/tsc | |
-[Active Projects](https://github.com/OAI/OpenAPI-Specification/projects?query=is%3Aopen) | @OAI/openapi-maintainers | |
-[New issues needing attention](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | @OAI/triage  | |
+[Spec Publishing PRs](https://github.com/OAI/spec.openapis.org/pulls) | @OAI/tsc | |
 Identify next week's meeting host (2 mins) | All | Comment on next week's agenda |
 
 /cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion.

AI.md

@@ -46,16 +46,16 @@ Do not use AI to summarise discussion content and then reply to the summary. The
 
 ## Enforcement
 
-Maintainers reserve the right to close any pull request, issue, or discussion thread that appears to represent low-effort or AI-generated content, without providing detailed justification.
+Maintainers reserve the right to close any pull request, issue, or discussion thread that appears to represent low-effort or undisclosed AI-generated content, without providing detailed justification.
 Repeated violations may result in a block from OpenAPI Initiative repositories.
 
-Reviewer time and expertise are the scarcest resources this project has, and so this policy is there to protect them and ensure the long-term healthy and viability of the project.
+Reviewer time and expertise are the scarcest resources this project has, and so this policy is there to protect them and ensure the long-term health and viability of the project.
 You are always welcome to reach out to us via GitHub or Slack to discuss any of these points or their application.
 
 ## Acknowledgements
 
 This policy builds on and acknowledges the work of:
 
-- [Mastodon AI Contribution Policy](https://github.com/mastodon/mastodon/blob/main/AI_POLICY.md)
+- [Mastodon AI Contribution Policy](https://github.com/mastodon/.github/blob/main/AI_POLICY.md)
 - [W3C: Use of Large Language Models in Standards Work](https://www.w3.org/TR/llms-standards/)
 - [FastAPI / tiangolo contributing guidelines](https://tiangolo.com/open-source/contributing/#automated-code-and-ai), in particular the framing of low-effort AI submissions as a denial-of-service attack on human effort

CONTRIBUTING.md

@@ -209,7 +209,7 @@ Before creating a pull request or marking a draft pull request as ready for revi
    | `yarn validate-markdown` | markdownlint + link check only — fast loop while editing |
    | `yarn format-markdown` | auto-fix markdownlint violations |
    | `yarn build-src` | full check: validation, HTML build, schema publish |
-   | `yarn test` | runs the JSON Schema and build tooling test suites |
+   | `yarn test` | runs the repository's JSON Schema and Markdown rendering fixture tests |
 
 5. After `yarn build-src`, open output file `deploy-preview/oas.html` with a browser and check your changes
 

proposals/2026-08-01-Docs-Links.md

@@ -0,0 +1,121 @@
+# Link to multiple external docs resources
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[2026-08-01-Docs-Links](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{2026-08-01-Docs-Links.md})|
+|Authors|[Lorna Mitchell](https://github.com/lornajane)|
+|Review Manager |TBD |
+|Status |Proposal|
+|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/{YYYY-MM-DD-Short-Name}/implementations.md)|
+|Issues |[#1034](https://github.com/OAI/OpenAPI-Specification/issues/1034) [#2409](https://github.com/OAI/OpenAPI-Specification/issues/2409)|
+|Previous Revisions ||
+
+## Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+
+## Introduction
+
+Describe more and different external resources by allowing more links with more metadata than is currently supported by `externalDocs`.
+
+## Motivation
+
+The existing `externalDocs` allows a single name/url combination to be referenced from each place that the field is supported:
+
+- description root
+- tags
+- operations
+- schemas
+
+The existing `externalDocs` field doesn't say what sort of docs it is, and doesn't allow more than one. By supporting multiple links, we could allow an API description to provide API docs and a changelog and the list of error codes and a link to some other information.
+
+I see a lot of links in description fields, or additions such as `x-documentation` extensions, to compensate for the limitations in `externalDocs`. This should be supported in the API description format, and **is our second most upvoted issue**.
+
+## Proposed solution
+
+I propose a two-part solution: 
+
+* add a new field `externalLinks` that supports an array of External Docuemntation objects, everywhere that `externalDocs` is currently supported, and deprecate the `externalDocs` field
+* improve/extend the External Documentation object to include optional `summary` and `kind` fields alongside the existing `url` (required) and `description` (optional, supports CommonMark) fields
+
+By keeping the documentation objects that we aready have and switching to an array of the instead of a single one, the upgrade path is very easy for anyone wanting to adopt the new field.
+A mechanism for multiple links gives the opportunity to link to multiple different resources in support on an API, operation, tag or schema.
+One array is a better place to look than a series of inconsistently named items; after externalDocs, you might see x-documentation or other extensions used for each additional reference.
+Naming it without "docs" makes it more obvious that this field can also be used to link to another type of resource if that is useful for the API.
+
+Agents can be provided more (potentially smaller) resources for context, and these can be scoped specifically to each operation, for example.
+
+### Example
+
+This example shows an `externalLinks` entry at the root of an OpenAPI description, with links to API docs and authentication information.
+
+```yaml
+openapi: 3.2.0
+title: Very Interesting Test API
+externalLinks:
+  - url: https://example.com/api-docs
+    summary: API Documentation
+    kind: api-docs
+  - url: https://example.com/docs/authenticating-your-api-client
+    summary: Authentication Overview
+    description: Details on authentication and how to register for application keys
+    kind: auth
+```
+
+## Detailed design
+
+The sections below describe the anticipated edits to the specification document (based on OpenAPI 3.2).
+
+<hr>
+
+In **OpenAPI Object -> Fixed Fields** and similarly in `tags`, `schemas`, and `operations`:
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="oas-external-docs"></a>externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. <br><br>**Deprecated:** The `externalDocs` field has been deprecated in favor of the `externalLinks` keyword that supports an array of objects. |
+| <a name="oas-external-links"></a>externalLinks | [[External Documentation Object](#external-documentation-object)] | An array of additional resources such as documentation. |
+
+<hr>
+
+In **External Documentation Object**:
+
+Allows referencing an external resource for external documentation or additional context.
+
+#### Fixed Fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| <a name="external-doc-summary"></a>summary | `string` | A short summary of the linked resource, used for display purposes. |
+| <a name="external-doc-description"></a>description | `string` | A description of the linked resource. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
+| <a name="external-doc-url"></a>url | `string` | **REQUIRED**. The URI for the linked resource. This MUST be in the form of a URI. |
+| <a name="external-doc--kind"></a>kind | `string` | A machine-readable string to categorize what sort of resource is linked. Any string value can be used; a [registry of the most commonly used values](https://spec.openapis.org/registry/tag-kind/) is available. |
+
+This object MAY be extended with [Specification Extensions](#specification-extensions).
+
+#### External Documentation Object Example
+
+```yaml
+name: API reference
+description: Interactive API documentation
+url: https://example.com/api-docs
+kind: api-docs
+```
+
+<hr>
+
+## Backwards compatibility
+
+Since we can't just make the current `externalDocs` field into an array without breaking things, I've recommended a similar-but-looser naming of `externalLinks` to contain an array of the existing External Documentation objects. These items have `url` as the only required field, and are not restricted to documentation only.
+
+Although the existing field is marked deprecated, tooling can continue to support it, and the similar structure makes migrating to the new approach painless.
+
+## Alternatives considered
+
+Considered:
+ - naming it `docLinks` which is a bit catchier and not so similar to be confusing (but maybe so different that the relationship isn't obvious).
+ - using `name` rather than `summary` but since it's an optional field and it's going alongside description, summary is more in keeping with our existing patterns.
+ - only permitting this new field at the top level; but I think it could make sense in any context so we should not be restrictive.
+

spec.config.json

@@ -39,6 +39,17 @@
     "schema.yaml",
     "schema-base.yaml"
   ],
+  "tests": {
+    "md2html": {
+      "fixtures": "tests/md2html/fixtures",
+      "config": "spec.config.json",
+      "otherVersions": [
+        "path/31.0.0.md",
+        "path/30.0.1.md",
+        "path/30.0.0.md"
+      ]
+    }
+  },
   "release": {
     "sourcePath": "src/oas.md",
     "releaseHistoryNote": "$releaseType of the OpenAPI Specification $version",

tests/md2html/md2html.test.mjs

@@ -1,49 +1,3 @@
-import { readdirSync, readFileSync } from "node:fs";
-import { execFile } from "node:child_process";
-import { resolve } from "node:path";
-import { describe, test, expect } from "@oai/build-infra/test";
-import assert from "node:assert";
+import { registerMd2htmlFixtureTests } from "@oai/build-infra/test/md2html";
 
-const folder = "./tests/md2html/fixtures/";
-describe("md2html", async () => {
-  readdirSync(folder, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && /\.md$/.test(entry.name))
-    .forEach((entry) => {
-      test(entry.name, async () => {
-        const expected = readFileSync(
-          folder + entry.name.replace(".md", ".html"),
-          "utf8",
-        ); 
-        const output = await md2html(
-          [
-            "--spec-config",
-            "spec.config.json",
-            "--maintainers",
-            entry.name.replace(".md", ".maintainers"),
-            entry.name,
-            "path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md",
-          ],
-          folder,
-        );
-        expect(output.stdout).to.equal(expected);
-      });
-    });
-});
-
-function md2html(args, cwd) {
-  return new Promise((res) => {
-    execFile(
-      "node",
-      [`${resolve("./node_modules/@oai/build-infra/src/md2html/md2html.js")}`, ...args],
-      { cwd },
-      (error, stdout, stderr) => {
-        res({
-          code: error?.code || 0,
-          error,
-          stdout,
-          stderr,
-        });
-      },
-    );
-  });
-}
+registerMd2htmlFixtureTests();