Merge remote-tracking branch 'upstream/main' into publish-schemas

Author: ralfhandl

.github/workflows/schema-tests.yaml

@@ -5,7 +5,7 @@ name: schema-test
 
 #
 # This workflow runs the npm test script to validate passing and failing
-# testcases for the metaschema.
+# testcases for the metaschemas
 #
 
 # run this on push to any branch and creation of pull-requests
@@ -23,13 +23,15 @@ jobs:
     - uses: actions/checkout@v4 # checkout repo content
       with:
         fetch-depth: 0
+
     - uses: actions/setup-node@v4 # setup Node.js
       with:
         node-version: '20.x'
+
     - name: Install dependencies from main
       run: |
         git checkout remotes/origin/main -- package.json package-lock.json
         npm ci
+
     - name: Run tests
       run: npm run test
-

.github/workflows/validate-markdown.yaml

@@ -23,10 +23,13 @@ jobs:
         fetch-depth: 0
     - name: use the javascript environment from main
       run: |
-        git checkout remotes/origin/main -- package.json package-lock.json
+        git checkout remotes/origin/main -- package.json package-lock.json .markdownlint.yaml
     - uses: actions/setup-node@v4 # setup Node.js
       with:
         node-version: '20.x'
     - name: Validate markdown
       run: npx --yes mdv versions/3.*.md
-
+    - name: Lint markdown v3.0.4
+      run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/3.0.4.md
+    - name: Lint markdown v3.1.1
+      run: npx --yes markdownlint-cli --config .markdownlint.yaml versions/3.1.1.md

schemas/v3.0/README.md

@@ -1,16 +1,43 @@
-OpenAPI 3.0.X JSON Schema
----
+# OpenAPI 3.0.X JSON Schema
 
-Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.0.X.
+This directory contains the YAML source for generating the JSON Schema for validating OpenAPI definitions of versions 3.0.X, which is published on [https://spec.openapis.org](https://spec.openapis.org).
 
-As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance.
+Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`.
 
-The iteration version of the JSON Schema can be found in the `id` field. For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019.
+The source in this directory, which has `WORK-IN-PROGRESS` in its `id`, is _not intended for direct use_.
 
-To submit improvements to the schema, modify the schema.yaml file only.
+## Schema `id` dates
+
+The published schemas on the spec site have an _iteration date_ in their `id`s.
+This allows the schemas for a release line (in this case 3.0) to be updated independent of the spec patch release cycle.
+
+The iteration version of the JSON Schema can be found in the `id` field.
+For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019.
+
+We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema.
+
+## Improving the schema
+
+As a reminder, the JSON Schema is not the source of truth for the Specification.
+In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins.
+Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance.
+
+The schema only validates the mandatory aspects of the OAS.
+Validating requirements that are optional, or field usage that has undefined or ignored behavior are not within the scope of this schema.
+Schemas to perform additional optional validation are [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4141).
+
+Improvements can be submitted by opening a PR against the `main` branch.
+
+Modify the `schema.yaml` file and add test cases for your changes.
 
 The TSC will then:
 - Run tests on the updated schema
 - Update the iteration version
-- Convert the schema.yaml to schema.json
 - Publish the new version
+
+The [test suite](../../tests/v3.0) is part of this package.
+
+```bash
+npm install
+npm test
+```