Merge pull request #355 from OAI/dev

Merge Dev to v1.0-dev

Author: frankkilcommins

.github/workflows/respec.yaml

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

.github/workflows/schema-publish.yaml

@@ -1,6 +1,6 @@
 name: schema-publish
 
-# author: @ralfhandl
+# author: @ralfhandl, @frankkilcommins
 
 #
 # This workflow copies the x.y schemas to the gh-pages branch
@@ -10,7 +10,11 @@ name: schema-publish
 on:
   push:
     branches:
-      - main
+      - 'v[0-9].[0-9]-dev'
+    paths:
+      - 'src/schemas/validation/*.yaml'
+      - 'scripts/schema-publish.sh'
+      - '.github/workflows/schema-publish.yaml'
   workflow_dispatch: {}
 
 jobs:
@@ -33,7 +37,7 @@ jobs:
 
       - uses: actions/setup-node@v4 # setup Node.js
         with:
-          node-version: 20.x
+          node-version: 22.x
 
       - name: Install dependencies
         run: npm ci
@@ -57,10 +61,10 @@ jobs:
           delete-branch: true
           path: deploy
           labels: Housekeeping,Schema
-          reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,handrews,ralfhandl
+          reviewers: darrelmiller,webron,earth2marsh,lornajane,mikekistler,miqui,ralfhandl,handrews,karenetheridge
           title: Arazzo - Publish Schema Iterations
           commit-message: New Arazzo schema iterations
           signoff: true
           body: |
             This pull request is automatically triggered by GitHub action `schema-publish` in the OAI/Arazzo-Specification repo.
-            The `schemas/**/*.yaml` files have changed and JSON files are automatically generated.
+            The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated.

.github/workflows/schema-tests.yaml

@@ -29,8 +29,7 @@ jobs:
         node-version: '20.x'
 
     - name: Install dependencies from main
-      run: |
-        # git checkout remotes/origin/main -- package.json package-lock.json #TODO: uncomment with subsequent PR
-        npm ci
+      run: npm ci
+      
     - name: Run tests
-      run: npm test
+      run: npm run test

.github/workflows/validate-markdown.yaml

@@ -4,7 +4,8 @@ name: validate-markdown
 # Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130
 
 #
-# This workflow validates files in the versions directory matching 1.*.md
+# This workflow validates markdown files in the project root.
+# It also validates the work-in-progress specification file src/arazzo.md with slightly different rules.
 #
 
 # run this on push to any branch and creation of pull-requests
@@ -16,9 +17,16 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2 # checkout repo content
-    - uses: actions/setup-node@v1 # setup Node.js
+    - uses: actions/checkout@v4 # checkout repo content
       with:
-        node-version: '18.x'
-    - name: Validate markdown
-      run: npx mdv versions/1.*.md
+        fetch-depth: 0
+
+    - uses: actions/setup-node@v4 # setup Node.js
+      with:
+        node-version: '20.x'
+
+    - name: Lint work-in-progress spec
+      run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/arazzo.md
+
+    - name: Lint other files
+      run: npx --yes markdownlint-cli2 *.md

.gitignore

@@ -7,6 +7,7 @@ target
 atlassian-ide-plugin.xml
 node_modules/
 deploy/
+deploy-preview/
 history
 Gemfile.lock
 coverage/

.markdownlint.yaml

@@ -0,0 +1,33 @@
+# First heading is a top-level heading
+MD002: true
+
+# Heading style (ATX is leading # symbols)
+MD003:
+  style: atx
+
+# Unordered list symbol can be anything
+MD004: false
+
+# Unordered list indentation size
+MD007:
+    indent: 2
+
+# Allow additional blank lines
+MD012: false
+
+# Maximum line length
+MD013:
+    line_length: 800
+    tables: false
+
+# Headings need blank lines before and after
+MD022: true
+
+# Duplicate headings are allowed
+MD024: false
+
+# Surround lists with blank lines
+MD032: true
+
+# Allow inline HTML
+MD033: false

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contribute to the Arazzo Specification
+
+We welcome contributions and discussion.
+Bug reports and feature requests are welcome, please add an issue explaining your use case.
+Pull requests are also welcome, but it is recommended to create an issue first, to allow discussion.
+
+Questions and comments are also welcome - use the GitHub Discussions feature.
+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.
+
+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.
+
+Published versions of the specification are in the `versions/` folder.
+The under-development versions of the specification are in the file `src/arazzo.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/arazzo.md`.
+
+The [spec site](https://spec.openapis.org) is the source of truth for the Arazzo specification as it contains all the citations and author credits.
+
+The OpenAPI project (which Arazzo sits under) 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.
+
+### Active branches
+
+The current active specification releases are:
+
+| Version | Branch | Notes |
+| ------- | ------ | ----- |
+| 1.0.2 | `v1.0-dev` | active patch release line |
+| 1.1.0 | `v1.1-dev` | minor release in development |
+
+## Pull Requests
+
+Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start.
+
+Pull requests MUST come from a fork; create a fresh branch on your fork based on the target branch for your change.
+
+### Branching Strategy
+
+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.
+- Branches name `vX.Y.Z-rel` are release branches (including when Z == 0). They exist primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links.
+
+> All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance.
+
+## Release Process and Scope
+
+### Minor Releases
+
+Our roadmap for Arazzo releases is community-driven, meaning the specification is open for proposed additions by anyone.
+
+Changes in minor releases (such as 1.1) meet the following criteria:
+
+- Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version.
+  For example, new optional fields can be added.
+- Drive quality-of-life improvements to support how Arazzo is used by practitioners, so that Arazzo evolves to continue to meet user needs.
+  For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification.
+- Make the specification document clearer or easier to understand.
+
+A minor release is due when there are some meaningful features (including one or a small number of headline features).
+
+### Patch Releases
+
+Patch releases reflect a constant quest for improving the active minor versions of Arazzo.
+Since we do not edit specification documents after publication, even the smallest change has to be in a new release.
+
+Changes in patch releases meet the following criteria:
+
+- Editorial changes such as spelling or formatting fixes, including link updates.
+- Clarifications or additions that do not change the meaning of the specification.
+
+Patch releases are created as often as there are changes to the specification worth releasing.
+
+## Get in touch
+
+To get in touch with other people on the project, ask questions, or anything else:
+
+- Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi) and join the `#arazzo` channel.
+- Start a [GitHub Discussion](https://github.com/OAI/Arazzo-Specification/discussions/).
+- Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/Arazzo-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHouse-keeping).
+
+## Appendix
+
+### Build the HTML version to publish
+
+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.
+
+You will need NodeJS 18 or later.
+
+Install dependencies:
+
+```sh
+npm install
+```
+
+Produce stand-alone HTML files in the local `deploy/arazzo` folder:
+
+```sh
+npm run build
+```
+
+Note that Linux users may need to add `--no-sandbox` to run `npx respec` as found in the `scripts/md2html/build.sh` file.

MAINTAINERS.md

@@ -1,4 +1,7 @@
+# Arazzo Specification Maintainers
+
 ## Active
+
 * Frank Kilcommins [@frankkilcommins](https://github.com/frankkilcommins)
 * Nick Denny [@ndenny](https://github.com/ndenny)
-* Kevin Duffey [@kevinduffey](https://github.com/kevinduffey)
+* Kevin Duffey [@kevinduffey](https://github.com/kevinduffey)

README.md

@@ -1,13 +1,15 @@
 # The Arazzo Specification
+
 ![alt Arazzo logo](./images/Arazzo-logo.png)
 
 The Arazzo Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
 
-The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI descriptions). 
+The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI descriptions).
 
 The Arazzo Specification can articulate these workflows in a deterministic human-readable and machine-readable manner, thus improving provider and consumer experiences when working with APIs. Similar to what OpenAPI has done for describing HTTP interfaces, the Arazzo Specification enables the ability to articulate the functional use cases offered by an API (or group of APIs) thus removing the guesswork for both human and machine consumers.
 
 Use cases for machine-readable API workflow definition documents include, but are not limited to:
+
 - interactive _living_ workflow documentation
 - automated documentation generation (e.g. Developer Portal documentation)
 - code and SDK generation driven by functional use cases
@@ -19,9 +21,9 @@ The Arazzo Specification does not mandate a specific development process such as
 
 This GitHub project is the starting point for Arazzo. Here you will find the information you need about the Arazzo Specification, simple examples of what it looks like, and some general information regarding the project.
 
-## Current Version - 1.0.0
+## Current Version - 1.0.1
 
-The current version of the Arazzo Specification is [Arazzo Specification 1.0.0](./versions/1.0.0.md).
+The latest version of the Arazzo Specification can be viewed at [Arazzo Specification - latest](https://spec.openapis.org/arazzo/latest.html).
 
 ![alt The Arazzo Specification Structure](./images/Arazzo-Specification-Structure.png)
 
@@ -40,8 +42,7 @@ The OpenAPI Initiative encourages participation from individuals and companies a
 - [Bi-weekly Call](https://github.com/OAI/Arazzo-Specification/discussions/5) - Wednesdays at 09:00 AM PDT
 - [Discussions](https://github.com/OAI/Arazzo-Specification/discussions) - Use the GitHub discussions to ask questions, provide opinions and engage with the group
 - [Issues](https://github.com/OAI/Arazzo-Specification/issues) - Feel free to submit a Github issue with any question or comment about the working group
-- Slack - if you have access to the OpenAPI slack workspace, then join the `sig-workflows` channel. If you do not have access, you're welcome to join by clicking [here](https://communityinviter.com/apps/open-api/openapi)
-
+- Slack - if you have access to the OpenAPI slack workspace, then join the `arazzo` channel. If you do not have access, [you're welcome to join](https://communityinviter.com/apps/open-api/openapi)
 
 ## Licensing
 

SPECIAL_INTEREST_GROUP.md

@@ -10,17 +10,18 @@ For more information, see [OAI Special Interest Groups](https://github.com/OAI/O
 
 ## Workflows Special Interest Group - Charter / Motivation
 
-Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of an API specification. 
+Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of an API specification.
 
-Our aim is to propose an enhancement to the current OpenAPI, or accompanying specification (or means), that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes. 
+Our aim is to propose an enhancement to the current OpenAPI, or accompanying specification (or means), that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes.
 
-The creation of the SIG-Workflows group is inspired by the need to store sequences of calls in the context of specific tests, and in order to communicate the particulars of a complex set of security related calls such as when using OAuth2 and the Financial-grade API security profile of OpenID Connect. 
+The creation of the SIG-Workflows group is inspired by the need to store sequences of calls in the context of specific tests, and in order to communicate the particulars of a complex set of security related calls such as when using OAuth2 and the Financial-grade API security profile of OpenID Connect.
 
 However, such a definition will be useful for understanding how to implement any dependent sequence of functional calls for any user of an API such as authorization calls, redirects and web hooks in order to achieve a certain technical or functional outcome.
 
 Optimally, it should be possible to articulate these workflows in a human and machine readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience and understanding of an API specified using OpenAPI (or other supported specifications).
 
-**Key focus areas**
+### Key focus areas
+
 - **Context** - How to define quickly and easily what goal and key functions of an API are, and how to represent that in a specification
 - **Workflows** - Handling key and complex sequences which may involve the reuse of endpoints for multiple uses, like token calls in a FAPI compliant sequence, in both a human and machine readable way, supporting both understanding and automation
 - **Tooling** - How to best integrate to tools and provide machine readable context for those tools so that the spec can integrate with the tools used by developers