From 1e278dbc61a9ddd9eba446beb0261cff665ab63e Mon Sep 17 00:00:00 2001 From: David Biesack Date: Wed, 7 May 2025 10:17:04 -0400 Subject: [PATCH 1/3] Add new Specfication Extension namespace registry: registries/_namespace/fdx.md Modified `CONTRIBUTING.md` to add instructions for registering new namespaces and extensions. Modified `registry/extension.md` and `registry/namespace.md` to link to instuctions in `CONTRIBUTING.md`. --- CONTRIBUTING.md | 128 ++++++++++++++++++++++++++++++++++- registries/_namespace/fdx.md | 18 +++++ registry/extension.md | 11 +-- registry/namespace.md | 7 +- 4 files changed, 155 insertions(+), 9 deletions(-) create mode 100644 registries/_namespace/fdx.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d450c89763..3b6614769b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ ## Building the site -The registy site uses [jekyll](https://jekyllrb.com/), a Ruby based static site generator, with the Dinky theme. +The registry site uses [jekyll](https://jekyllrb.com/), +a Ruby based static site generator, with the Dinky theme. ### Docker dev @@ -28,9 +29,10 @@ With all the gems (dependencies) installed, you can launch the jekyll server. bundle exec jekyll serve ``` -It will show output like this, and you can grab the Server address and open it in your browser. +It will show output like this, and you can grab the Server address +and open it in your browser. -``` +```md Configuration file: /site/_config.yml Source: /site Destination: /site/_site @@ -41,3 +43,123 @@ Configuration file: /site/_config.yml Server address: http://0.0.0.0:4000 ``` +## Adding New Entries to the Registries + +To add a new entry to the registries (either an OpenAPI +Specification Extension namespace or a specific OpenAPI +Specification Extension), +fork this repository in GitHub. +Make a local clone of your fork and check out the +`gh-pages` branch. + +### Add a New Extension Namespace Registry Entry + +Working in the `gh-pages` branch, +add a new Markdown file in `registries/_namespace/`. The file name +should be the namespace name with a `.md` extension. For example, +to add an extension namespace `abc` for extensions named `x-abc-*`, +create `registries/_namespace/abc.md`. Use the following template, +replacing the instruction text in `<>` markers: + +```md +--- +owner: <> +issue: +description: <> +layout: default +--- + +{% capture summary %} +The `x-{{page.slug}}-` prefix is reserved for extensions created by +<> +{% endcapture %} + +{% include namespace-entry.md summary=summary %} + +``` + +You may use [GitHub Flavored Markdown](https://github.github.com/gfm/) +in the short and long descriptions. + +See [oai.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_namespace/oai.md) +for an example for the `x-oai-*` namespace. + +Next, locally build +the site as described above and view +[http://127.0.0.1:4000/registry/namespace/index.html](http://127.0.0.1:4000/registry/namespace/index.html) +to verify your namespace is listed. +(Modify the URL if Jekyll is running on a different IP or port.) +The namespace name in Value column +should link to your namespace page, and the __Description__ +text should be the `description:` from the Markdown frontmatter. + +Preview your content at +`http://127.0.0.1:4000/registry/namespace/abc.html` +(change `abc` in to your namespace URL). + +### Add a New Specification Extension Registry Entry + +add a new Markdown file in `registries/_extension/`. +The file name should be your specification extension name with +a `.md` file extension, such as +`registries/_extension/x-abc-wander.md` to document the +`x-abc-wander` extension. + +Use this template for your file, +replacing the instruction text in `<>` markers: + +```md +--- +owner: <> +issue: +description: <>. +schema: + <> + objects: <> +layout: default +--- + +{% capture summary %} +<> + +Used by: (informational) + + * <>> +{% endcapture %} + +{% capture example %} + +< + +{% endcapture %} + +{% include extension-entry.md summary=summary example=example %} +``` + +You may use [GitHub Flavored Markdown](https://github.github.com/gfm/) +in the short and long descriptions. + +See [x-twitter.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_extension/x-twitter.md) +for an example. + +Build the site locally as described above. + +Preview [http://127.0.0.1:4000/registry/extension/](http://127.0.0.1:4000/registry/extension/). + +(Modify the URL if Jekyll is running on a different IP or port.) +Verify that you specification extension +should is listed. The __Value__ column should contain you extension name +with a link to you documentation, such as +`http://127.0.0.1:4000/registry/extension/x-abc-wander.html`, +and the __Description__ should be your brief description. + +### Submitting + +When you have verified your content renders correctly, +submit a Pull Request against the `gh-pages` branch +of `git@github.com:OAI/OpenAPI-Specification.git`. +Committers will review the PR and you may be asked +to update the PR. When approved, committers +will merge your PR into `git@github.com:OAI/OpenAPI-Specification.git` +and the merge actions will publish your changes to +[https://spec.openapis.org/registry/](https://spec.openapis.org/registry/). diff --git a/registries/_namespace/fdx.md b/registries/_namespace/fdx.md new file mode 100644 index 0000000000..a932f205c9 --- /dev/null +++ b/registries/_namespace/fdx.md @@ -0,0 +1,18 @@ +--- +owner: DavidBiesack +issue: +description: Extensions created and used by [Financial Data Exchange (FDX)](https://financialdataexchange.org) +layout: default +--- + +{% capture summary %} +The `x-{{page.slug}}-` prefix is reserved for extensions created by +[Financial Data Exchange (FDX)](https://financialdataexchange.org). +FDX is the +[standard-setting organization](https://www.consumerfinance.gov/about-us/newsroom/cfpb-approves-application-from-financial-data-exchange-to-issue-standards-for-open-banking/) which is defining the open banking +standard in the US under +[Dodd-Frank Section 1033](https://www.consumerfinance.gov/rules-policy/notice-opportunities-comment/archive-closed/dodd-frank-act-section-1033-consumer-access-to-financial-records/). + +{% endcapture %} + +{% include namespace-entry.md summary=summary %} diff --git a/registry/extension.md b/registry/extension.md index 226b8730e7..3912bc2b1c 100644 --- a/registry/extension.md +++ b/registry/extension.md @@ -1,6 +1,4 @@ ---- -# title: Extensions Registry -layout: default +efault permalink: /registry/extension/index.html parent: Registry --- @@ -13,7 +11,11 @@ parent: Registry ## Contributing -Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. +Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls)and +follow the instructions in the +[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md), +or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues) +to contribute or discuss a registry value. ## Values @@ -21,4 +23,3 @@ Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls |---|---|---| {% for value in site.extension %}| {{ value.slug }} | {{ value.description }} | {% if value.issue %}#{{ value.issue }}{% endif %} | {% endfor %} - diff --git a/registry/namespace.md b/registry/namespace.md index 6b05c8c1b7..9f2ee6d483 100644 --- a/registry/namespace.md +++ b/registry/namespace.md @@ -11,7 +11,12 @@ To allow for creators of OpenAPI descriptions to define new extensions without t ## Contributing -Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) or [Issue](https://github.com/OAI/OpenAPI-Specification/issues) to contribute or discuss a registry value. +Please raise a +[Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and +follow the instructions in the +[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md), +or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues) +to contribute or discuss a registry value. ## Values From c74617be637f0d5c624585e4166a28bd2e6d1986 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Thu, 8 May 2025 15:04:40 -0400 Subject: [PATCH 2/3] Fix frontmatter typo --- registry/extension.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/registry/extension.md b/registry/extension.md index 3912bc2b1c..9aab692a55 100644 --- a/registry/extension.md +++ b/registry/extension.md @@ -1,4 +1,6 @@ -efault +--- +# title: Extensions Registry +layout: default permalink: /registry/extension/index.html parent: Registry --- From 7a048e7292c52506bf79197407f4b77310f26308 Mon Sep 17 00:00:00 2001 From: David Biesack Date: Thu, 8 May 2025 15:05:21 -0400 Subject: [PATCH 3/3] Fix markdown typo --- registry/extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/registry/extension.md b/registry/extension.md index 9aab692a55..8bf28d4020 100644 --- a/registry/extension.md +++ b/registry/extension.md @@ -13,7 +13,7 @@ parent: Registry ## Contributing -Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls)and +Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and follow the instructions in the [`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md), or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues)