Skip to content

Commit 989ddbf

Browse files
authored
Add Getting Started instructions to the README (#33)
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
1 parent 280fc84 commit 989ddbf

1 file changed

Lines changed: 109 additions & 0 deletions

File tree

README.markdown

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,18 @@ designing great APIs.*
2929
> All schemas target JSON Schema 2020-12, the dialect used by OpenAPI v3.1 and
3030
> later. Earlier JSON Schema dialects will be supported in the future.
3131
32+
## :bookmark_tabs: Table of Contents
33+
34+
- [:blue_book: Standards](#blue_book-standards)
35+
- [:rocket: Getting Started](#rocket-getting-started)
36+
- [From Sourcemeta Schemas](#from-sourcemeta-schemas)
37+
- [From GitHub Releases](#from-github-releases)
38+
- [Using Git Submodules](#using-git-submodules)
39+
- [Using Vendorpull](#using-vendorpull)
40+
- [:page_facing_up: License](#page_facing_up-license)
41+
- [:handshake: Contributing](#handshake-contributing)
42+
- [:email: Contact](#email-contact)
43+
3244
## :blue_book: Standards
3345

3446
This library provides schemas that encode aspects of the following standards.
@@ -60,6 +72,103 @@ expressed as JSON Schema definitions.
6072
To request coverage of another standard, please [open an issue on
6173
GitHub](https://github.com/sourcemeta/std/issues).
6274

75+
## :rocket: Getting Started
76+
77+
While you can always copy-paste schemas directly, here are more convenient and
78+
maintainable ways to consume them.
79+
80+
### From Sourcemeta Schemas
81+
82+
We periodically publish the JSON Schema standard library to [Sourcemeta
83+
Schemas](https://schemas.sourcemeta.com/sourcemeta/std), our free service for
84+
hosting open-source schemas. Each schema gets a unique HTTPS URL that you can
85+
directly reference from your OpenAPI specifications using the
86+
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword. For
87+
example:
88+
89+
```yaml
90+
schema:
91+
type: object
92+
properties:
93+
email:
94+
$ref: 'https://schemas.sourcemeta.com/sourcemeta/std/v0.0.1/ietf/email/address'
95+
```
96+
97+
To de-reference and embed these external URLs when distributing your OpenAPI
98+
specification, use standard tools like [`redocly
99+
bundle`](https://redocly.com/docs/cli/commands/bundle).
100+
101+
### From GitHub Releases
102+
103+
We publish archives of the JSON Schema standard library to [GitHub
104+
Releases](https://github.com/sourcemeta/std/releases). Download and extract an
105+
archive to your preferred location, then reference the JSON files from your
106+
OpenAPI specifications using the
107+
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a
108+
relative path. For example:
109+
110+
```yaml
111+
schema:
112+
type: object
113+
properties:
114+
email:
115+
$ref: "../path/to/sourcemeta-std/ietf/email/address.json"
116+
```
117+
118+
### Using Git Submodules
119+
120+
If your OpenAPI specification lives in a Git repository, you can add this
121+
library as a [git
122+
submodule](https://git-scm.com/docs/git-submodule). This approach keeps the
123+
schemas versioned alongside your code and ensures consistent access across your
124+
team. Add the submodule to your repository:
125+
126+
```sh
127+
git submodule add https://github.com/sourcemeta/std std
128+
```
129+
130+
Then reference the schemas using the
131+
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a
132+
relative path. For example:
133+
134+
```yaml
135+
schema:
136+
type: object
137+
properties:
138+
email:
139+
$ref: './std/schemas/ietf/email/address.json'
140+
```
141+
142+
### Using Vendorpull
143+
144+
[Vendorpull](https://github.com/sourcemeta/vendorpull) is our tool for
145+
vendoring Git repositories, which we use across our projects. It provides an
146+
easier alternative to submodules by committing upstream contents directly into
147+
your repository while letting you easily manage and update them. Add this line
148+
to your `DEPENDENCIES` file:
149+
150+
```
151+
std https://github.com/sourcemeta/std v<x.y.z>
152+
```
153+
154+
Then pull the library into your `vendor` directory:
155+
156+
```sh
157+
./vendor/vendorpull/pull std
158+
```
159+
160+
Reference the schemas using the
161+
[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a
162+
relative path. For example:
163+
164+
```yaml
165+
schema:
166+
type: object
167+
properties:
168+
email:
169+
$ref: './vendor/std/schemas/ietf/email/address.json'
170+
```
171+
63172
## :page_facing_up: License
64173

65174
While the project is publicly available on GitHub, it operates under a

0 commit comments

Comments
 (0)