Skip to content

Commit b3e8434

Browse files
lornajanelornajane
authored
Merge pull request #4567 from DavidBiesack/gh-pages
Add new Specification Extension namespace registry x-fdx ; add better instructions for new registry entries
2 parents 41d2d6c + 7a048e7 commit b3e8434

File tree

4 files changed

+154
-6
lines changed

4 files changed

+154
-6
lines changed

‎CONTRIBUTING.md

Lines changed: 125 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
## Building the site
44

5-
The registy site uses [jekyll](https://jekyllrb.com/), a Ruby based static site generator, with the Dinky theme.
5+
The registry site uses [jekyll](https://jekyllrb.com/),
6+
a Ruby based static site generator, with the Dinky theme.
67

78
### Docker dev
89

@@ -28,9 +29,10 @@ With all the gems (dependencies) installed, you can launch the jekyll server.
2829
bundle exec jekyll serve
2930
```
3031

31-
It will show output like this, and you can grab the Server address and open it in your browser.
32+
It will show output like this, and you can grab the Server address
33+
and open it in your browser.
3234

33-
```
35+
```md
3436
Configuration file: /site/_config.yml
3537
Source: /site
3638
Destination: /site/_site
@@ -41,3 +43,123 @@ Configuration file: /site/_config.yml
4143
Server address: http://0.0.0.0:4000
4244
```
4345

46+
## Adding New Entries to the Registries
47+
48+
To add a new entry to the registries (either an OpenAPI
49+
Specification Extension namespace or a specific OpenAPI
50+
Specification Extension),
51+
fork this repository in GitHub.
52+
Make a local clone of your fork and check out the
53+
`gh-pages` branch.
54+
55+
### Add a New Extension Namespace Registry Entry
56+
57+
Working in the `gh-pages` branch,
58+
add a new Markdown file in `registries/_namespace/`. The file name
59+
should be the namespace name with a `.md` extension. For example,
60+
to add an extension namespace `abc` for extensions named `x-abc-*`,
61+
create `registries/_namespace/abc.md`. Use the following template,
62+
replacing the instruction text in `<<instruction-text>>` markers:
63+
64+
```md
65+
---
66+
owner: <<Your-GutHub-username>>
67+
issue:
68+
description: <<Briefly describe your namespace>>
69+
layout: default
70+
---
71+
72+
{% capture summary %}
73+
The `x-{{page.slug}}-` prefix is reserved for extensions created by
74+
<<describe your organization and namespace>>
75+
{% endcapture %}
76+
77+
{% include namespace-entry.md summary=summary %}
78+
79+
```
80+
81+
You may use [GitHub Flavored Markdown](https://github.github.com/gfm/)
82+
in the short and long descriptions.
83+
84+
See [oai.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_namespace/oai.md)
85+
for an example for the `x-oai-*` namespace.
86+
87+
Next, locally build
88+
the site as described above and view
89+
[http://127.0.0.1:4000/registry/namespace/index.html](http://127.0.0.1:4000/registry/namespace/index.html)
90+
to verify your namespace is listed.
91+
(Modify the URL if Jekyll is running on a different IP or port.)
92+
The namespace name in Value column
93+
should link to your namespace page, and the __Description__
94+
text should be the `description:` from the Markdown frontmatter.
95+
96+
Preview your content at
97+
`http://127.0.0.1:4000/registry/namespace/abc.html`
98+
(change `abc` in to your namespace URL).
99+
100+
### Add a New Specification Extension Registry Entry
101+
102+
add a new Markdown file in `registries/_extension/`.
103+
The file name should be your specification extension name with
104+
a `.md` file extension, such as
105+
`registries/_extension/x-abc-wander.md` to document the
106+
`x-abc-wander` extension.
107+
108+
Use this template for your file,
109+
replacing the instruction text in `<<instruction-text>>` markers:
110+
111+
```md
112+
---
113+
owner: <<Your-GutHub-username>>
114+
issue:
115+
description: <<Brief description of your Specification Extension>>.
116+
schema:
117+
<<JSON Schema, in YAML format, for validating specification extension instances>>
118+
objects: <<Array of OAS objects where the specification may be used.>>
119+
layout: default
120+
---
121+
122+
{% capture summary %}
123+
<<Detailed description of the extension.>>
124+
125+
Used by: (informational)
126+
127+
* <<bullet list of representative users of the extension>>>
128+
{% endcapture %}
129+
130+
{% capture example %}
131+
132+
<<YAML snippet of OpenAPI source code example showing use of your specification example>
133+
134+
{% endcapture %}
135+
136+
{% include extension-entry.md summary=summary example=example %}
137+
```
138+
139+
You may use [GitHub Flavored Markdown](https://github.github.com/gfm/)
140+
in the short and long descriptions.
141+
142+
See [x-twitter.md](https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/gh-pages/registries/_extension/x-twitter.md)
143+
for an example.
144+
145+
Build the site locally as described above.
146+
147+
Preview [http://127.0.0.1:4000/registry/extension/](http://127.0.0.1:4000/registry/extension/).
148+
149+
(Modify the URL if Jekyll is running on a different IP or port.)
150+
Verify that you specification extension
151+
should is listed. The __Value__ column should contain you extension name
152+
with a link to you documentation, such as
153+
`http://127.0.0.1:4000/registry/extension/x-abc-wander.html`,
154+
and the __Description__ should be your brief description.
155+
156+
### Submitting
157+
158+
When you have verified your content renders correctly,
159+
submit a Pull Request against the `gh-pages` branch
160+
of `[email protected]:OAI/OpenAPI-Specification.git`.
161+
Committers will review the PR and you may be asked
162+
to update the PR. When approved, committers
163+
will merge your PR into `[email protected]:OAI/OpenAPI-Specification.git`
164+
and the merge actions will publish your changes to
165+
[https://spec.openapis.org/registry/](https://spec.openapis.org/registry/).

‎registries/_namespace/fdx.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
owner: DavidBiesack
3+
issue:
4+
description: Extensions created and used by [Financial Data Exchange (FDX)](https://financialdataexchange.org)
5+
layout: default
6+
---
7+
8+
{% capture summary %}
9+
The `x-{{page.slug}}-` prefix is reserved for extensions created by
10+
[Financial Data Exchange (FDX)](https://financialdataexchange.org).
11+
FDX is the
12+
[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
13+
standard in the US under
14+
[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/).
15+
16+
{% endcapture %}
17+
18+
{% include namespace-entry.md summary=summary %}

‎registry/extension.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,15 @@ parent: Registry
1313

1414
## Contributing
1515

16-
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.
16+
Please raise a [Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and
17+
follow the instructions in the
18+
[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md),
19+
or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues)
20+
to contribute or discuss a registry value.
1721

1822
## Values
1923

2024
|Value|Description|Issue|
2125
|---|---|---|
2226
{% for value in site.extension %}| <a href="./{{ value.slug }}.html">{{ value.slug }}</a> | {{ value.description }} | {% if value.issue %}<a href="https://github.com/OAI/OpenAPI-Specification/issues/{{ value.issue }}">#{{ value.issue }}</a>{% endif %} |
2327
{% endfor %}
24-

‎registry/namespace.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,12 @@ To allow for creators of OpenAPI descriptions to define new extensions without t
1111

1212
## Contributing
1313

14-
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.
14+
Please raise a
15+
[Pull-Request](https://github.com/OAI/OpenAPI-Specification/pulls) and
16+
follow the instructions in the
17+
[`CONTRIBUTING.md` file in the `gh-pages` branch](https://github.com/OAI/OpenAPI-Specification/blob/gh-pages/CONTRIBUTING.md),
18+
or open an [Issue](https://github.com/OAI/OpenAPI-Specification/issues)
19+
to contribute or discuss a registry value.
1520

1621
## Values
1722

0 commit comments

Comments
 (0)