@@ -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
3446This library provides schemas that encode aspects of the following standards.
@@ -60,6 +72,103 @@ expressed as JSON Schema definitions.
6072To request coverage of another standard, please [ open an issue on
6173GitHub] ( 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
65174While the project is publicly available on GitHub, it operates under a
0 commit comments