diff --git a/README.markdown b/README.markdown index fd4a876..6f7e7c2 100644 --- a/README.markdown +++ b/README.markdown @@ -29,6 +29,18 @@ designing great APIs.* > All schemas target JSON Schema 2020-12, the dialect used by OpenAPI v3.1 and > later. Earlier JSON Schema dialects will be supported in the future. +## :bookmark_tabs: Table of Contents + +- [:blue_book: Standards](#blue_book-standards) +- [:rocket: Getting Started](#rocket-getting-started) + - [From Sourcemeta Schemas](#from-sourcemeta-schemas) + - [From GitHub Releases](#from-github-releases) + - [Using Git Submodules](#using-git-submodules) + - [Using Vendorpull](#using-vendorpull) +- [:page_facing_up: License](#page_facing_up-license) +- [:handshake: Contributing](#handshake-contributing) +- [:email: Contact](#email-contact) + ## :blue_book: Standards This library provides schemas that encode aspects of the following standards. @@ -60,6 +72,103 @@ expressed as JSON Schema definitions. To request coverage of another standard, please [open an issue on GitHub](https://github.com/sourcemeta/std/issues). +## :rocket: Getting Started + +While you can always copy-paste schemas directly, here are more convenient and +maintainable ways to consume them. + +### From Sourcemeta Schemas + +We periodically publish the JSON Schema standard library to [Sourcemeta +Schemas](https://schemas.sourcemeta.com/sourcemeta/std), our free service for +hosting open-source schemas. Each schema gets a unique HTTPS URL that you can +directly reference from your OpenAPI specifications using the +[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword. For +example: + +```yaml +schema: + type: object + properties: + email: + $ref: 'https://schemas.sourcemeta.com/sourcemeta/std/v0.0.1/ietf/email/address' +``` + +To de-reference and embed these external URLs when distributing your OpenAPI +specification, use standard tools like [`redocly +bundle`](https://redocly.com/docs/cli/commands/bundle). + +### From GitHub Releases + +We publish archives of the JSON Schema standard library to [GitHub +Releases](https://github.com/sourcemeta/std/releases). Download and extract an +archive to your preferred location, then reference the JSON files from your +OpenAPI specifications using the +[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a +relative path. For example: + +```yaml +schema: + type: object + properties: + email: + $ref: "../path/to/sourcemeta-std/ietf/email/address.json" +``` + +### Using Git Submodules + +If your OpenAPI specification lives in a Git repository, you can add this +library as a [git +submodule](https://git-scm.com/docs/git-submodule). This approach keeps the +schemas versioned alongside your code and ensures consistent access across your +team. Add the submodule to your repository: + +```sh +git submodule add https://github.com/sourcemeta/std std +``` + +Then reference the schemas using the +[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a +relative path. For example: + +```yaml +schema: + type: object + properties: + email: + $ref: './std/schemas/ietf/email/address.json' +``` + +### Using Vendorpull + +[Vendorpull](https://github.com/sourcemeta/vendorpull) is our tool for +vendoring Git repositories, which we use across our projects. It provides an +easier alternative to submodules by committing upstream contents directly into +your repository while letting you easily manage and update them. Add this line +to your `DEPENDENCIES` file: + +``` +std https://github.com/sourcemeta/std v +``` + +Then pull the library into your `vendor` directory: + +```sh +./vendor/vendorpull/pull std +``` + +Reference the schemas using the +[`$ref`](https://www.learnjsonschema.com/2020-12/core/ref) keyword with a +relative path. For example: + +```yaml +schema: + type: object + properties: + email: + $ref: './vendor/std/schemas/ietf/email/address.json' +``` + ## :page_facing_up: License While the project is publicly available on GitHub, it operates under a