Start 1.1.0 from 1.0.0 with simplified branch setup

CONTRIBUTING.md

@@ -34,10 +34,14 @@ Pull requests must come from a fork; create a fresh branch on your fork based on
 
 Overview of branches:
 
-- `main` holds the published versions of the specification, utility scripts and supporting documentation.
-- `dev` is for development infrastructure and other changes that apply to multiple versions of development.
-- Branches named `vX.Y-dev` are the active development branches for future releases.
-  All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance.
+The `main` branch holds 
+- 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.
+
+Other branches are usually short-lived, for example and for maintaining utility scripts.
 
 ## Build the HTML version to publish
 

schemas/v1.1-dev/readme.md

@@ -0,0 +1,36 @@
+# OpenAPI Overlay 1.1.x JSON Schema
+
+Here you can find the JSON Schema for validating Overlays of versions 1.1.x.
+
+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 iteration version of the JSON Schema can be found in the `$id` field.
+For example, the value of `$id: https://spec.openapis.org/overlay/1.1/schema/2024-10-17` means this iteration was created on October 17, 2024.
+
+## Contributing
+
+To submit improvements to the schema, modify the `schema.yaml` and add test cases for your changes.
+
+The TSC will then:
+- Run tests on the updated schema
+- Update the iteration version
+- Publish the new version
+
+## Tests
+
+The [test suite](../../tests/v1.1) is part of this package.
+
+```bash
+npm install
+npm test
+```
+
+You can also validate a document individually.
+
+```bash
+node scripts/validate.mjs path/to/document/to/validate.yaml
+```

schemas/v1.1-dev/schema.yaml

@@ -0,0 +1,63 @@
+$id: https://spec.openapis.org/overlay/1.1/schema/WORK-IN-PROGRESS
+$schema: https://json-schema.org/draft/2020-12/schema
+description: The description of Overlay v1.1.x documents
+type: object
+properties:
+  overlay:
+    type: string
+    pattern: ^1\.1\.\d+$
+  info:
+    $ref: "#/$defs/info-object"
+  extends:
+    type: string
+    format: uri-reference
+  actions:
+    type: array
+    minItems: 1
+    uniqueItems: true
+    items:
+      $ref: "#/$defs/action-object"
+required:
+  - overlay
+  - info
+  - actions
+$ref: "#/$defs/specification-extensions"
+unevaluatedProperties: false
+$defs:
+  info-object:
+    type: object
+    properties:
+      title:
+        type: string
+      version:
+        type: string
+    required:
+      - title
+      - version
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
+  action-object:
+    properties:
+      target:
+        type: string
+        pattern: ^\$
+      description:
+        type: string
+      update:
+        type:
+          - string
+          - boolean
+          - object
+          - array
+          - number
+          - "null"
+      remove:
+        type: boolean
+        default: false
+    required:
+      - target
+    $ref: "#/$defs/specification-extensions"
+    unevaluatedProperties: false
+  specification-extensions:
+    patternProperties:
+      ^x-: true

scripts/schema-publish.sh

@@ -6,6 +6,12 @@
 
 for schemaDir in schemas/v* ; do
   vVersion=$(basename "$schemaDir")
+
+  if [[ "$vVersion" =~ -dev$ ]] ; then
+    echo "Skipping dev version $vVersion"
+    continue
+  fi
+
   version=${vVersion:1}
   echo $version
 

tests/v1.0/schema.test.mjs → tests/schema.test.mjs

@@ -25,9 +25,12 @@ function runTestSuite(version, suite) {
   });
 }
 
-const version = "v1.0";
-
-describe(version, () => {
-  runTestSuite(version, "pass");
-  runTestSuite(version, "fail");
-});
+readdirSync(`./schemas`, { withFileTypes: true })
+  .filter((dirEntry) => dirEntry.isDirectory() && /^v\d+\.\d+/.test(dirEntry.name))
+  .forEach((dirEntry) => {
+    const version = dirEntry.name;
+    describe(version, () => {
+      runTestSuite(version, "pass");
+      runTestSuite(version, "fail");
+    });
+  });

tests/v1.1-dev/fail/actions-invalid-description.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Actions invalid description
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document
+    description: 10

tests/v1.1-dev/fail/actions-invalid-target.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Invalid `target`, must begin with `$`
+  version: 1.0.0
+actions:
+  - target: info.description
+    update: An updated description

tests/v1.1-dev/fail/actions-minimal.yaml

@@ -0,0 +1,5 @@
+overlay: 1.1.0
+info:
+  title: Minimal actions
+  version: 1.0.0
+actions: []

tests/v1.1-dev/fail/actions-missing-target.yaml

@@ -0,0 +1,6 @@
+overlay: 1.1.0
+info:
+  title: Missing actions `target`
+  version: 1.0.0
+actions:
+  - update: my description

tests/v1.1-dev/fail/actions-missing.yaml

@@ -0,0 +1,5 @@
+overlay: 1.1.0
+info:
+  title: Missing `actions`
+  version: 1.0.0
+extends: '/openapi.yaml'

tests/v1.1-dev/fail/actions-not-unique.yaml

@@ -0,0 +1,9 @@
+overlay: 1.1.0
+info:
+  title: Actions not unique
+  version: 1.0.0
+actions:
+  - target: '$.info.title'
+    update: 'My New title'
+  - target: '$.info.title'
+    update: 'My New title'

tests/v1.1-dev/fail/extends-invalid-type.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Invalid `extends` type
+  version: 1.0.0
+extends: {}
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/fail/info-missing-title.yaml

@@ -0,0 +1,5 @@
+overlay: 1.1.0
+info:
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/fail/info-missing-version.yaml

@@ -0,0 +1,5 @@
+overlay: 1.1.0
+info:
+  title: Missing Info version
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/fail/invalid-overlay-version.yaml

@@ -0,0 +1,6 @@
+overlay: 2
+info:
+  title: Invalid Overlay version
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/fail/not-an-object.yaml

@@ -0,0 +1,5 @@
+- root
+- must
+- be
+- an
+- object

tests/v1.1-dev/pass/actions-array-modification-example-remove.yaml

@@ -0,0 +1,11 @@
+overlay: 1.1.0
+info:
+  title: Add an array element
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get.parameters
+    update:
+      name: newParam
+      in: query
+      schema:
+        type: string

tests/v1.1-dev/pass/actions-array-modification-example-update.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Remove a array element
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get.parameters[[email protected] == 'dummy']
+    remove: true

tests/v1.1-dev/pass/actions-description.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Actions Description
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document
+    description: this is an action description

tests/v1.1-dev/pass/actions-extensions.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Actions Extensions
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document
+    x-myActionsExtension: {}

tests/v1.1-dev/pass/actions-structured-overlay-example.yaml

@@ -0,0 +1,22 @@
+overlay: 1.1.0
+info:
+  title: Structured Overlay
+  version: 1.0.0
+extends: '/openapi.yaml'
+actions:
+  - target: '$' # Root of document
+    update:
+      info:
+        x-overlay-applied: structured-overlay
+      paths:
+        '/':
+          summary: 'The root resource'
+          get:
+            summary: 'Retrieve the root resource'
+            x-rate-limit: 100
+        '/pets':
+          get:
+            summary: 'Retrieve a list of pets'
+            x-rate-limit: 100
+      components:
+      tags: []

tests/v1.1-dev/pass/actions-targeted-overlay-example.yaml

@@ -0,0 +1,16 @@
+overlay: 1.1.0
+info:
+  title: Targeted Overlay
+  version: 1.0.0
+actions:
+  - target: $.paths['/foo'].get
+    update:
+      description: This is the new description
+  - target: $.paths['/bar'].get
+    update:
+      description: This is the updated description
+  - target: $.paths['/bar']
+    update:
+      post:
+        description: This is an updated description of a child object
+        x-safe: false

tests/v1.1-dev/pass/actions-traits-example.yaml

@@ -0,0 +1,14 @@
+overlay: 1.1.0
+info:
+  title: Apply Traits
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get[[email protected]]
+    update:
+      parameters:
+        - name: top
+          in: query
+          # ...
+        - name: skip
+          in: query
+          # ...

tests/v1.1-dev/pass/actions-update-with-remove.yaml

@@ -0,0 +1,12 @@
+overlay: 1.1.0
+info:
+  title: Actions Remove and Update defined
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get.parameters
+    update:
+      name: newParam
+      in: query
+      schema:
+        type: string
+    remove: true

tests/v1.1-dev/pass/actions-wildcard-overlay-example.yaml

@@ -0,0 +1,12 @@
+overlay: 1.1.0
+info:
+  title: Update many objects at once
+  version: 1.0.0
+actions:
+  - target: $.paths.*.get
+    update:
+      x-safe: true
+  - target: $.paths.*.get.parameters[[email protected]=='filter' && @.in=='query']
+    update:
+      schema:
+        $ref: '#/components/schemas/filterSchema'

tests/v1.1-dev/pass/info-extensions.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Info Extensions
+  version: 1.0.0
+  x-myInfoExtension: {}
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/pass/minimal.yaml

@@ -0,0 +1,6 @@
+overlay: 1.1.0
+info:
+  title: Minimal
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document

tests/v1.1-dev/pass/root-extensions.yaml

@@ -0,0 +1,7 @@
+overlay: 1.1.0
+info:
+  title: Root Extensions
+  version: 1.0.0
+actions:
+  - target: '$' # Root of document
+x-myExtension: {}