refresh dev from main

.github/workflows/schema-publish.yaml

@@ -10,9 +10,9 @@ name: schema-publish
 on:
   push:
     branches:
-      - main
+      - "v[0-9].[0-9]-dev"
     paths:
-      - "schemas/v[0-9].[0-9]/*.yaml"
+      - "src/schemas/validation/*.yaml"
   workflow_dispatch: {}
 
 jobs:

.linkspector.yml

@@ -3,3 +3,4 @@ dirs:
 useGitIgnore: true
 ignorePatterns:
   - pattern: 'stackoverflow.com' # has bot protection
+  - pattern: 'w3.org' # returns 403 for automated requests

AI.md

@@ -0,0 +1,63 @@
+# OpenAPI Initiative AI Policy
+
+The OpenAPI Initiative is a project that brings together experienced industry experts to collaborate on an open, shared standard that benefits us all.
+It is the result of shared ideas, thoughtful discussion, and careful curation over time.
+As the tools landscape changes, the way we work together on that shared vision should not change.
+
+Well-thought-out and meaningful contributions will always be welcome and considered for their merits, however the advent of AI-generated interactions makes this policy a necessary addition to the project.
+We encourage humans to engage and to gain experience with the project and further the mission, but our volunteer maintainers are not to be put in a position of expending more effort on reviewing contributions than was used to create them because the project is unsustainable in that scenario.
+
+TL;DR we do permit use of AI, with disclosure, but low-effort, inaccurate or overly verbose contributions will be dismissed.
+
+## AI and Standards Development
+
+The nature of this project provides a very particular context and any tool (including AI) should be applied with consideration to the context.
+The tools you use day-to-day can feel helpful, but we expect you to consider how they may best add value to each task within the project.
+
+Standards development means devising and developing standards that do not yet exist, with knowledge of the standards landscape and ongoing work in other standards projects.
+Most AI tools are trained on existing or outdated content, making them less useful for standards development than they might be in other applications, so bear that perspective in mind when working with AI on specification improvements or proposals.
+
+## Permitted Use
+
+AI tools may be used to support contributions to OpenAPI Initiative projects, including use of AI for drafting, editing, checking consistency, or exploring ideas.
+However, you are solely responsible for every part of your submission - the content, its accuracy, and its appropriateness for the project.
+You should expect to be asked followup questions about any detail of your contribution and to have already considered your work as deeply as our maintainers will when they review it.
+Using AI can help you to do a good job but we expect you to use these tools intentionally and considerately for the project and audience.
+
+## Disclosure and Accountability
+
+If AI tools were used in preparing a contribution beyond simple autocomplete or spellcheck, this must be disclosed in the pull request or issue description.
+Add a note with a simple overview of how AI was used to your work and be prepared to answer further questions on that usage.
+
+You must be able to explain and defend every part of your contribution.
+If a reviewer asks why a particular design decision was made, "the AI suggested it" is not an acceptable answer.
+Contributions where the submitter cannot demonstrate understanding of the material will be closed without further discussion or explanation.
+
+## Discussion Conduct
+
+Discussions in OpenAPI Initiative projects are for humans.
+Comments that restate or summarise what has already been said, without advancing the conversation, add burden to volunteers and will be removed.
+A useful comment adds new information, identifies a constraint, asks a precise question, or proposes a concrete resolution.
+We expect you to make good-faith contributions that are concise and to the intended point; overly verbose or general contributions will be hidden or removed.
+
+Do not use AI to generate issue comments, discussion replies, or PR descriptions.
+These are the primary record of design reasoning for the project; they must reflect genuine human thought.
+
+Do not use AI to summarise discussion content and then reply to the summary.
+The individual points raised by the other participants all have value and the nuance is one of the main strengths of discussion between experts.
+
+## Enforcement
+
+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 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/.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

@@ -9,20 +9,29 @@ You will also find notes from past meetings in the Discussion tab.
 
 ## Key information
 
-This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme).
-All participants are expected to read and follow this code.
+This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme) and [AI policy](AI.md).
+All participants are expected to read and follow these policies.
 
 No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder).
-Exceptions may be made when links to external documents have been changed by a 3rd party, in order to keep our documents accurate.
+Exceptions may be made when links to external URLs have been changed by a 3rd party, in order to keep our documents accurate.
 
 Published versions of the specification are in the `versions/` folder.
 The under-development versions of the specification are in the file `src/overlay.md` on the appropriately-versioned branch.
-For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/overlay.md`.
+For example, work on the next patch release for 1.2 is on `v1.2-dev` in the file `src/overlay.md`.
+The next minor release will be developed on `v1.3-dev` once that branch has been created.
 
 The [spec site](https://spec.openapis.org) is the source of truth for the OpenAPI Overlay specification as it contains all the citations and author credits.
 
 The OpenAPI project is almost entirely staffed by volunteers.
-Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world.
+We expect you to contribute here respectfully, politely, and with good intentions.
+When you engage with this project, please:
+
+- review existing content: check the existing specification, documentation, and issues/discussions before starting a new discussion, issue or pull request.
+- respect everyone's time: keep your communication relevant and concise.
+- hold responsibility for your work: you should be able to explain or answer questions about anything you have posted to the project as your own.
+
+We actively close interactions that don't meet these expectations, so please don't be offended as we protect the time and energy of our volunteers.
+If you do think that something was closed in error, you are welcome to reach out to us to follow up.
 
 ## Shared infrastructure
 
@@ -49,103 +58,116 @@ Pull requests must come from a fork; create a fresh branch on your fork based on
 
 ### Branching Strategy
 
-Overview of branches:
+#### Active branches
 
-The `main` branch holds
+The current and planned active specification releases are:
 
-- published versions of the specification, named `versions/X.Y.Z.md`,
-- work-in-progress versions of the specification, named `versions/X.Y.Z-dev.md`,
-- sources for published schema versions in `schemas/vX.Y` folders and their tests in `tests/vX.Y` folders,
-- sources for work-in-progress schema versions in `schemas/vX.Y-dev` folders and their tests in `tests/vX.Y-dev` folders,
-- utility scripts and supporting documentation.
+| Version | Branch | Notes |
+| ------- | ------ | ----- |
+| 1.2.x | `v1.2-dev` | active patch release line |
+| 1.3.0 | `v1.3-dev` | next minor release; branch not yet created |
 
-Other branches are usually short-lived, for example for maintaining utility scripts.
+#### Target the earliest relevant active `*-dev` branch
 
-### Reviewers
+Branch from and submit specification pull requests to the earliest relevant active `vX.Y-dev` branch.
+For example, a correction that applies to 1.2 should target `v1.2-dev`.
+Changes that introduce features for the next minor release should target `v1.3-dev` once that branch has been created; until then, use an issue or discussion to develop the proposal.
 
-All pull requests must be reviewed and approved by one member of the Overlay-Maintainers team. Reviews from other contributors are always welcome.
+The development branch contains the work-in-progress specification in `src/overlay.md` and its schema in `src/schemas/validation`.
 
-Additionally, all pull requests that change specification files in the `versions` folder must be approved by two Overlay-Maintainers team members.
+For repository files that affect all versions, such as Markdown documentation, automation, and scripts, target the `main` branch.
+The `main` branch contains published specifications in `versions/X.Y.Z.md`, published schemas, schema tests, and supporting repository files; it does not contain the active `src` tree.
 
-## Build the HTML versions locally
+### Reviewers
 
-We use ReSpec to render the markdown specification as HTML for publishing and easier reading.
-These instructions explain how you can build the HTML locally.
+All pull requests must be reviewed and approved by one member of the Overlay-Maintainers team. Reviews from other contributors are always welcome.
 
-You will need Node.js 24 and Yarn 4.18 (via Corepack).
+Additionally, all pull requests that change `src/overlay.md` must be approved by two Overlay-Maintainers team members.
 
-Install dependencies:
+## Preview specification HTML locally
 
-```sh
-corepack enable
-yarn install
-```
+We use ReSpec to render the markdown specification as HTML for publishing and easier reading.
+Before creating a pull request or marking a draft pull request as ready for review, validate your changes locally:
 
-Produce stand-alone HTML files for all final specifications in the local `deploy/overlay` folder:
+1. Install Node.js 24 and run `corepack enable` once to make the repository's pinned Yarn version available
+2. Check out this repository, go to the repository root, and switch to the appropriate development branch
+3. Run `yarn install --immutable` and repeat this after merging upstream changes
+4. Run the commands relevant to what you changed:
 
-```sh
-yarn build
-```
+   | Command | What it does |
+   | ------- | ------------ |
+   | `yarn validate-markdown` | markdownlint and link checking for a fast loop while editing |
+   | `yarn format-markdown` | automatically fixes markdownlint violations |
+   | `yarn build` | builds all published specifications into `deploy/overlay` |
+   | `yarn build-src` | validates and builds the work-in-progress specification and schema into `deploy-preview` |
+   | `yarn test` | runs the JSON Schema and build tooling test suites |
 
-Produce stand-alone HTML files for all work-in-progress specifications in the local `deploy-preview` folder:
+5. After `yarn build-src`, open the generated file in `deploy-preview` with a browser and check your changes
 
-```sh
-yarn build-src
-```
+Please make sure the Markdown validates and builds, and that `yarn test` passes, before creating a pull request or marking a draft pull request as ready for review.
 
 ## Publishing
 
 ### Specification Versions
 
-The specification versions are published to the [spec site](https://spec.openapis.org) by creating an `vX.Y.Z-rel` branch where `versions/X.Y.Z-dev.md` is renamed to `versions/X.Y.Z.md` and then merged into `main`.
-This renaming preserves the commit history when using `git log --follow`.
+The specification versions are published to the [spec site](https://spec.openapis.org) by creating a `vX.Y.Z-rel` branch from `vX.Y-dev`, copying `src/overlay.md` to `versions/X.Y.Z.md`, and then merging the release branch into `main`.
 
-The steps for creating a `vX.Y.Z-rel` branch are:
+Before starting, check that the release content and release notes have the required maintainer approval.
 
-1. Update `EDITORS.md` in a temporary branch and merge changes back into `main` via pull request
-2. Prepare spec files in a temporary branch:
+The steps for publishing a new specification version are:
+
+1. Update `EDITORS.md` on `main` via pull request
+2. Merge `main` into `vX.Y-dev` via pull request
+3. Prepare the specification files on `vX.Y-dev`:
    - `yarn format-markdown`
    - `yarn build-src`
-   - open `deploy-preview/X.Y.Z-dev.html` in browser and verify correct formatting
+   - `yarn test`
+   - open the generated HTML file in `deploy-preview` and verify correct formatting
    - adjust and repeat until done
-   - merge changes back into `main` via pull request
-3. Create branch `vX.Y.Z-rel` from `main` in the OAI/Overlay-Specification repo and adjust it
-   - `yarn adjust-release-branch` does this:
-     - move file `versions/X.Y.Z-dev.md` to `versions/X.Y.Z.md` and replace the release date placeholder `| TBD |` in the history table of Appendix A with the current date
-     - copy file `EDITORS.md` to `versions/X.Y.Z-editors.md`
-     - for an X.Y.0 release
-       - move folder `schemas/vX.Y-dev` to `schemas/vX.Y`
-       - move folder `tests/vX.Y-dev` to `tests/vX.Y`
-4. Commit, push, and merge `vX.Y.Z-rel` into `main` via pull request
-5. Archive branch `vX.Y.Z-rel`
+   - merge any final changes back into `vX.Y-dev` via pull request
+4. Create branch `vX.Y.Z-rel` from `vX.Y-dev` in the OAI/Overlay-Specification repository and run `yarn adjust-release-branch`
+   - the command:
+     - copies `src/overlay.md` to `versions/X.Y.Z.md` and replaces the release date placeholder `| TBD |` in the history table of Appendix A with the current date
+     - copies `EDITORS.md` to `versions/X.Y.Z-editors.md`
+     - removes the development-only `src` folder
+     - stages the release changes
+   - review the staged changes with `git diff --cached`
+   - commit the changes
+5. Push and merge `vX.Y.Z-rel` into `main` via pull request
+6. Tag a release using GitHub's Releases feature and add the release notes as the description
+7. Merge `main` back into `vX.Y-dev` via pull request
+8. Archive branch `vX.Y.Z-rel`
 
 HTML renderings of the specification versions are generated from the `versions` folder on `main` by the `respec` workflow on changes to files in that folder, which generates a pull request for publishing the HTML renderings to the [spec site](https://spec.openapis.org/overlay). The workflow can be run manually if required.
 
 Schema iterations are generated from the YAML source files in `schemas/vX.Y` by converting them to JSON, renaming to the relevant last-changed dates, and replacing the `WORK-IN-PROGRESS` placeholders with these dates. This is done by the `schema-publish` workflow on changes to files in these folders, which generates a pull request for publishing the new schema iterations to the [spec site](https://spec.openapis.org/overlay). The workflow can be run manually if required.
 
+The release commands are implemented in [`OAI/build-infra`](https://github.com/OAI/build-infra).
+If a command behaves unexpectedly, check this repository's `spec.config.json` first, then see the [build-infra release documentation](https://github.com/OAI/build-infra/blob/main/README.md#release-process-summary).
+
 #### Start Next Patch Version
 
-Once the released specification version is published, the next patch version X.Y.(Z+1) can be started:
+Once the released specification version is published and synced back to the `vX.Y-dev` branch, the next patch version X.Y.(Z+1) can be started:
 
-1. Run `yarn start-release X.Y.(Z+1)` in branch `main` to
-   - create branch `start-X.Y.(Z+1)`
-   - initialize `versions/X.Y.(Z+1)-dev.md` with empty history and content from `versions/X.Y.Z.md`
-   - change version heading to X.Y.(Z+1) and add a new line to the version history table in Appendix A
-   - commit changes
-2. Push branch `start-X.Y.(Z+1)` and merge into `main` via pull request
+1. Run `yarn start-release` on `vX.Y-dev` to:
+   - create branch `vX.Y-dev-start-X.Y.(Z+1)`
+   - initialize `src/overlay.md` with empty history and content from `versions/X.Y.Z.md`
+   - change the version heading to X.Y.(Z+1) and add a new line to the version history table in Appendix A
+   - commit the changes
+2. Push branch `vX.Y-dev-start-X.Y.(Z+1)` and merge it into `vX.Y-dev` via pull request
 
 #### Start New Minor or Major Version
 
 A new minor version X.(Y+1).0 or major version (X+1).0.0 is started similarly:
 
-1. Run `yarn start-release X'.Y'.0` in branch `main` to
-   - create branch `start-X'.Y'.0`
-   - initialize `versions/X'.Y'.0-dev.md` with empty history and content from `versions/X.Y.Z.md`
-   - change version heading to X'.Y'.0 and add a new line to the version history table in Appendix A
-   - copy schema files `schemas/vX.Y` to `schemas/vX'.YY'-dev` and change version in all schema files
-   - copy schema tests `tests/vX.Y` to `tests/vX'.YY'-dev` and change version in all test files
-   - commit changes
-2. Push branch `start-X'.Y'.0` and merge into `main` via pull request
+1. Create branch `vX'.Y'-dev` from the previous development branch
+2. Run `yarn start-release` on the new development branch to:
+   - create branch `vX'.Y'-dev-start-X'.Y'.0`
+   - initialize `src/overlay.md` with empty history and content from the latest published specification
+   - change the version heading to X'.Y'.0 and add a new line to the version history table in Appendix A
+   - update the configured schema files to the new minor version
+   - commit the changes
+3. Push branch `vX'.Y'-dev-start-X'.Y'.0` and merge it into `vX'.Y'-dev` via pull request
 
 ### Publishing using WSL
 

spec.config.json

@@ -1,10 +1,9 @@
 {
   "slug": "overlay",
-  "shortName": "Overlay",
-  "titleName": "OpenAPI Overlays",
+  "shortName": "OAI Overlay",
+  "titleName": "Overlay Specification",
   "specSrc": "overlay.md",
-  "abstractQuestion": "What is the OpenAPI Overlay Specification?",
-  "abstractText": "The OpenAPI Overlay Specification defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s).",
+  "extractAbstractFromMarkdown": true,
   "metaDescription": "The OpenAPI Overlay Specification defines a document format for information that augments an existing OpenAPI description yet remains separate from the OpenAPI description's source document(s).",
   "copyright": "the Linux Foundation",
   "edDraftURI": "https://github.com/OAI/Overlay-Specification/",
@@ -17,6 +16,10 @@
   "participateLinks": [
     { "value": "GitHub OAI/Overlay-Specification", "href": "https://github.com/OAI/Overlay-Specification/" },
     { "value": "File a bug", "href": "https://github.com/OAI/Overlay-Specification/issues" },
+    {
+      "value": "Commit history",
+      "href": "https://github.com/OAI/Overlay-Specification/commits/main/versions/{version}.md"
+    },
     { "value": "Pull requests", "href": "https://github.com/OAI/Overlay-Specification/pulls" }
   ],
   "titleSuffix": "",