v3.3-dev: sync with dev

.github/workflows/respec.yaml

@@ -47,7 +47,7 @@ jobs:
         delete-branch: true
         path: deploy
         labels: Housekeeping
-        reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge
+        reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge
         title: Update ReSpec-rendered specification versions
         commit-message: Update ReSpec-rendered specification versions
         signoff: true

.github/workflows/sync-dev-to-vX.Y-dev.yaml

@@ -11,6 +11,7 @@ on:
   push:
     branches:
       - dev
+  workflow_dispatch: {}
 
 jobs:
   sync-branches:
@@ -22,36 +23,49 @@ jobs:
         with:
           app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }}
           private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }}
-    
+
       - name: Checkout repository
         uses: actions/checkout@v5
         with:
           fetch-depth: 0
+          token: ${{ steps.generate-token.outputs.token }}
 
       - name: Create pull requests
         id: pull_requests
         shell: bash
         run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
           DEV_BRANCHES=$(git branch -r --list origin/v?.?-dev)
           for DEV_BRANCH in $DEV_BRANCHES; do
             BASE=${DEV_BRANCH:7}
-            EXISTS=$(gh pr list --base $BASE --head $HEAD \
+            SYNC="$BASE-sync-with-$HEAD"
+
+            git checkout -b $SYNC origin/$SYNC || git checkout -b $SYNC origin/$BASE
+            git merge origin/$HEAD -m "Merge $HEAD into $SYNC"
+            git checkout origin/$BASE src/*
+            git checkout origin/$BASE tests/*
+            git commit -m "Restored src/* and tests/*" || echo ""
+            git push -u origin $SYNC
+
+            EXISTS=$(gh pr list --base $BASE --head $SYNC \
               --json number --jq '.[] | .number')
             if [ ! -z "$EXISTS" ]; then
-              echo "PR #$EXISTS already wants to merge $HEAD into $BASE"
+              echo "PR #$EXISTS already wants to merge $SYNC into $BASE"
               continue
             fi
 
-            PR=$(gh pr create --base $BASE --head $HEAD \
+            PR=$(gh pr create --base $BASE --head $SYNC \
               --label "Housekeeping" \
-              --title "$BASE: update from $HEAD" \
-              --body "Merge \`$HEAD\` into \`$BASE\`.")
+              --title "$BASE: sync with $HEAD" \
+              --body "Merge relevant changes from \`$HEAD\` into \`$BASE\`.")
             echo ""
             echo "PR to sync $DEV_BRANCH: $PR"
             sleep 10 # allow status checks to be triggered
 
             gh pr checks $PR --watch --required || continue
-            gh pr merge $PR --merge --admin
+            # gh pr merge $PR --merge --admin
           done
         env:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}

.github/workflows/sync-main-to-dev.yaml

@@ -11,6 +11,7 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch: {}
 
 jobs:
   sync-branch:
@@ -25,22 +26,36 @@ jobs:
 
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          token: ${{ steps.generate-token.outputs.token }}
 
       - name: Create pull request
         id: pull_request
         shell: bash
         run: |
-          EXISTS=$(gh pr list --base $BASE --head $HEAD \
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          SYNC="$BASE-sync-with-$HEAD"
+
+          git checkout -b $SYNC origin/$SYNC || git checkout -b $SYNC origin/$BASE
+          git merge origin/$HEAD -m "Merge $HEAD into $SYNC"
+          git checkout origin/$BASE src/*
+          git checkout origin/$BASE tests/*
+          git commit -m "Restored src/* and tests/*" || echo ""
+          git push -u origin $SYNC
+
+          EXISTS=$(gh pr list --base $BASE --head $SYNC \
             --json number --jq '.[] | .number')
           if [ ! -z "$EXISTS" ]; then
-            echo "PR #$EXISTS already wants to merge $HEAD into $BASE"
+            echo "PR #$EXISTS already wants to merge $SYNC into $BASE"
             exit 0
           fi
 
-          gh pr create --base $BASE --head $HEAD \
+          gh pr create --base $BASE --head $SYNC \
             --label "Housekeeping" \
-            --title "$BASE: update from $HEAD" \
-            --body "Merge \`$HEAD\` into \`$BASE\`."
+            --title "$BASE: sync with $HEAD" \
+            --body "Merge relevant changes from \`$HEAD\` into \`$BASE\`."
         env:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}
           HEAD: main

src/oas.md

@@ -95,7 +95,7 @@ In addition to the required fields, at least one of the `components`, `paths`, o
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
 | <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions-and-deprecation) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is _not_ related to the [`info.version`](#info-version) string, which describes the OpenAPI document's version. |
-| <a name="oas-self"></a>$self | `string` | This string MUST be in the form of a URI reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix F]((#appendix-f-examples-of-base-uri-determination-and-reference-resolution)) for examples of using `$self` to resolve references. |
+| <a name="oas-self"></a>$self | `string` | This string MUST be in the form of a URI reference as defined by [[RFC3986]] [Section 4.1](https://www.rfc-editor.org/rfc/rfc3986#section-4.1). The `$self` field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [[RFC3986]] [Section 5.1.1](https://www.rfc-editor.org/rfc/rfc3986#section-5.1.1). Implementations MUST support identifying the targets of [API description URIs](#relative-references-in-api-description-uris) using the URI defined by this field when it is present. See [Establishing the Base URI](#establishing-the-base-uri) for the base URI behavior when `$self` is absent or relative, and see [Appendix F](#appendix-f-examples-of-base-uri-determination-and-reference-resolution) for examples of using `$self` to resolve references. |
 | <a name="oas-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. |
 | <a name="oas-json-schema-dialect"></a> jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schema-object) contained within this OAS document. This MUST be in the form of a URI. |
 | <a name="oas-servers"></a>servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be an array consisting of a single [Server Object](#server-object) with a [url](#server-url) value of `/`. |
@@ -1099,7 +1099,7 @@ examples:
 ```
 
 A querystring parameter using regular form encoding, but managed with a Media Type Object.
-This shows spaces being handled per the `application/x-www-form-urlencoded` media type rules (encode as `+`) rather than the RFC6570 process (encode as `%20`); see [Appendix E](appendix-e-percent-encoding-and-form-media-types) for further guidance on this distinction.
+This shows spaces being handled per the `application/x-www-form-urlencoded` media type rules (encode as `+`) rather than the RFC6570 process (encode as `%20`); see [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for further guidance on this distinction.
 Examples are shown at both the media type and parameter level to emphasize that, since `application/x-www-form-urlencoded` is suitable for use in query strings by definition, no further encoding or escaping is applied to the serialized media type value:
 
 ```yaml
@@ -1857,7 +1857,7 @@ Using `contentEncoding` for a multipart field is equivalent to specifying an [En
 If `contentEncoding` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows the value from `contentEncoding`, the result is undefined for serialization and parsing.
 
 Note that as stated in [Working with Binary Data](#working-with-binary-data), if the Encoding Object's `contentType`, whether set explicitly or implicitly through its default value rules, disagrees with the `contentMediaType` in a Schema Object, the `contentMediaType` SHALL be ignored.
-Because of this, and because the Encoding Object's `contentType` defaulting rules do not take the Schema Object's`contentMediaType` into account, the use of `contentMediaType` with an Encoding Object is NOT RECOMMENDED.
+Because of this, and because the Encoding Object's `contentType` defaulting rules do not take the Schema Object's `contentMediaType` into account, the use of `contentMediaType` with an Encoding Object is NOT RECOMMENDED.
 
 Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
 
@@ -1991,7 +1991,7 @@ multipart/mixed:
 As described in [[?RFC2557]], a set of resources making up a web page can be sent in a `multipart/related` payload, preserving links from the `text/html` document to subsidiary resources such as scripts, style sheets, and images by defining a `Content-Location` header for each page.
 The first part is used as the root resource (unless using `Content-ID`, which RFC2557 advises against and is forbidden in this example), so we use `prefixItems` and `prefixEncoding` to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.
 
-The `Content-Location` header is defined using `content: {text/plain: {...}}` to avoid percent-encoding its URI value; see [Appendix D](appendix-d-serializing-headers-and-cookies) for further details.
+The `Content-Location` header is defined using `content: {text/plain: {...}}` to avoid percent-encoding its URI value; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for further details.
 
 ```yaml
 components:
@@ -2051,7 +2051,7 @@ multipart/mixed:
 
 For `multipart/byteranges` [[RFC9110]] [Section 14.6](https://www.rfc-editor.org/rfc/rfc9110.html#section-14.6), a `Content-Range` header is required:
 
-See [Appendix D](appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value.
+See [Appendix D](#appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value.
 
 ```yaml
 multipart/byteranges:
@@ -2789,7 +2789,7 @@ For HTTP messages, this is purely a serialization concern, and no more of a prob
 
 However, because examples and values modeled with `content` do not incorporate the header name, for these fields `Set-Cookie` MUST be handled by placing each value on a separate line, without the header name or the `:` delimiter.
 
-Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see [Appendix D](appendix-d-serializing-headers-and-cookies) for details.
+Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
 
 The following example shows two different ways to describe `Set-Cookie` headers that require cookies named `"lang"` and `"foo"`, as well as a `"urlSafeData"` cookie that is expected to be percent-encoded.  The first uses `content` in order to show exactly how such examples are formatted, but also notes the limitations of schema constraints with multi-line text.  The second shows the use of `style: "simple"`, which produces the same serialized example text (with each line corresponding to one `Set-Cookie:` line in the HTTP response), but allows schema constraints on each cookie; note that the percent-encoding is already applied in the `dataValue` field of the example:
 

versions/3.1.2-editors.md

@@ -0,0 +1,22 @@
+# OpenAPI Specification Editors
+
+## Active
+
+* Henry Andrews [@handrews](https://github.com/handrews)
+* Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
+* Karen Etheridge [@karenetheridge](https://github.com/karenetheridge)
+* Lorna Mitchell [@lornajane](https://github.com/lornajane)
+* Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
+* Miguel Quintero [@miqui](https://github.com/miqui)
+* Mike Kistler [@mikekistler](https://github.com/mikekistler)
+* Ralf Handl [@ralfhandl](https://github.com/ralfhandl)
+* Vincent Biret [@baywet](https://github.com/baywet)
+
+## Emeritus
+
+* Ron Ratovsky [@webron](https://github.com/webron)
+* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
+* Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
+* Uri Sarid [@usarid](https://github.com/usarid)
+* Jason Harmon [@jharmn](https://github.com/jharmn)
+* Tony Tam [@fehguy](https://github.com/fehguy)