diff --git a/src/schemas/validation/README.md b/src/schemas/validation/README.md
new file mode 100644
index 0000000..6bb2cf7
--- /dev/null
+++ b/src/schemas/validation/README.md
@@ -0,0 +1,20 @@
+# OpenAPI Security Specification JSON Schema
+
+This directory contains the YAML sources for generating the JSON Schemas for validating OpenAPI Security Specification (OSS) Standardized API Features (SAFs), which are published on [https://spec.openapis.org](https://spec.openapis.org).
+
+***NOTE:*** The exact structure and versioning policy of SAF schemas is still being discussed. The current schemas are ported over from the OpenAPI Specification but the approach is subject to change.
+
+Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`.
+
+The sources in this directory, which have `WORK-IN-PROGRESS` in their `$id`s, are _not intended for direct use_.
+
+## Schema `$id` dates
+
+The published schemas on the spec site have an _iteration date_ in their `id`s.
+This allows the schemas for a release line to be updated independent of the spec patch release cycle.
+
+The iteration version of the JSON Schema can be found in the `$id` field.
+For example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` means this iteration was created on March 2nd, 2021.
+
+We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema.
+
diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml
new file mode 100644
index 0000000..ac50562
--- /dev/null
+++ b/src/schemas/validation/schema.yaml
@@ -0,0 +1,230 @@
+$id: 'https://spec.openapis.org/security/legacy/3.3/schema/WORK-IN-PROGRESS'
+$schema: 'https://json-schema.org/draft/2020-12/schema'
+
+description: The description of OpenAPI legacy security Objects
+
+$defs:
+ security-scheme:
+ $comment: https://spec.openapis.org/oas/v3.3#security-scheme-object
+ type: object
+ properties:
+ type:
+ enum:
+ - apiKey
+ - http
+ - mutualTLS
+ - oauth2
+ - openIdConnect
+ description:
+ type: string
+ deprecated:
+ default: false
+ type: boolean
+ required:
+ - type
+ allOf:
+ - $ref: '#/$defs/specification-extensions'
+ - $ref: '#/$defs/security-scheme/$defs/type-apikey'
+ - $ref: '#/$defs/security-scheme/$defs/type-http'
+ - $ref: '#/$defs/security-scheme/$defs/type-http-bearer'
+ - $ref: '#/$defs/security-scheme/$defs/type-oauth2'
+ - $ref: '#/$defs/security-scheme/$defs/type-oidc'
+ unevaluatedProperties: false
+
+ $defs:
+ type-apikey:
+ if:
+ properties:
+ type:
+ const: apiKey
+ then:
+ properties:
+ name:
+ type: string
+ in:
+ enum:
+ - query
+ - header
+ - cookie
+ required:
+ - name
+ - in
+
+ type-http:
+ if:
+ properties:
+ type:
+ const: http
+ then:
+ properties:
+ scheme:
+ type: string
+ required:
+ - scheme
+
+ type-http-bearer:
+ if:
+ properties:
+ type:
+ const: http
+ scheme:
+ type: string
+ pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$
+ required:
+ - type
+ - scheme
+ then:
+ properties:
+ bearerFormat:
+ type: string
+
+ type-oauth2:
+ if:
+ properties:
+ type:
+ const: oauth2
+ then:
+ properties:
+ flows:
+ $ref: '#/$defs/oauth-flows'
+ oauth2MetadataUrl:
+ type: string
+ format: uri-reference
+ required:
+ - flows
+
+ type-oidc:
+ if:
+ properties:
+ type:
+ const: openIdConnect
+ then:
+ properties:
+ openIdConnectUrl:
+ type: string
+ format: uri-reference
+ required:
+ - openIdConnectUrl
+
+ oauth-flows:
+ type: object
+ properties:
+ implicit:
+ $ref: '#/$defs/oauth-flows/$defs/implicit'
+ password:
+ $ref: '#/$defs/oauth-flows/$defs/password'
+ clientCredentials:
+ $ref: '#/$defs/oauth-flows/$defs/client-credentials'
+ authorizationCode:
+ $ref: '#/$defs/oauth-flows/$defs/authorization-code'
+ deviceAuthorization:
+ $ref: '#/$defs/oauth-flows/$defs/device-authorization'
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ $defs:
+ implicit:
+ type: object
+ properties:
+ authorizationUrl:
+ type: string
+ format: uri-reference
+ refreshUrl:
+ type: string
+ format: uri-reference
+ scopes:
+ $ref: '#/$defs/map-of-strings'
+ required:
+ - authorizationUrl
+ - scopes
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ password:
+ type: object
+ properties:
+ tokenUrl:
+ type: string
+ format: uri-reference
+ refreshUrl:
+ type: string
+ format: uri-reference
+ scopes:
+ $ref: '#/$defs/map-of-strings'
+ required:
+ - tokenUrl
+ - scopes
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ client-credentials:
+ type: object
+ properties:
+ tokenUrl:
+ type: string
+ format: uri-reference
+ refreshUrl:
+ type: string
+ format: uri-reference
+ scopes:
+ $ref: '#/$defs/map-of-strings'
+ required:
+ - tokenUrl
+ - scopes
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ authorization-code:
+ type: object
+ properties:
+ authorizationUrl:
+ type: string
+ format: uri-reference
+ tokenUrl:
+ type: string
+ format: uri-reference
+ refreshUrl:
+ type: string
+ format: uri-reference
+ scopes:
+ $ref: '#/$defs/map-of-strings'
+ required:
+ - authorizationUrl
+ - tokenUrl
+ - scopes
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ device-authorization:
+ type: object
+ properties:
+ deviceAuthorizationUrl:
+ type: string
+ format: uri-reference
+ tokenUrl:
+ type: string
+ format: uri-reference
+ refreshUrl:
+ type: string
+ format: uri-reference
+ scopes:
+ $ref: '#/$defs/map-of-strings'
+ required:
+ - deviceAuthorizationUrl
+ - tokenUrl
+ - scopes
+ $ref: '#/$defs/specification-extensions'
+ unevaluatedProperties: false
+
+ specification-extensions:
+ $comment: https://spec.openapis.org/oas/v3.3#specification-extensions
+ patternProperties:
+ '^x-': true
+
+ additionalProperties:
+ $ref: '#/$defs/example-or-reference'
+
+ map-of-strings:
+ type: object
+ additionalProperties:
+ type: string
diff --git a/src/security.md b/src/security.md
index f0191f2..99937e3 100644
--- a/src/security.md
+++ b/src/security.md
@@ -10,6 +10,126 @@
TODO: Define the Security Specification.
+## Specification
+
+### Security Scheme Object
+
+Defines a security scheme that can be used by the operations.
+
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), and [[OpenID-Connect-Core]].
+Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use cases is Authorization Code Grant flow with PKCE.
+
+#### Fixed Fields
+
+| Field Name | Type | Applies To | Description |
+| ---- | :----: | ---- | ---- |
+| type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`. |
+| description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
+| name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. |
+| in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"`, or `"cookie"`. |
+| scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-16.4.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1). |
+| bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. |
+| flows | [OAuth Flows Object](#oauth-flows-object) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. |
+| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [[OpenID-Connect-Discovery]] [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). |
+| oauth2MetadataUrl | `string` | `oauth2` | URL to the OAuth2 authorization server metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required. |
+| deprecated | `boolean` | Any | Declares this security scheme to be deprecated. Consumers SHOULD refrain from usage of the declared scheme. Default value is `false`. |
+
+This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions).
+
+#### Security Scheme Object Examples
+
+##### Basic Authentication Example
+
+```yaml
+type: http
+scheme: basic
+```
+
+##### API Key Example
+
+```yaml
+type: apiKey
+name: api-key
+in: header
+```
+
+##### JWT Bearer Example
+
+```yaml
+type: http
+scheme: bearer
+bearerFormat: JWT
+```
+
+##### MutualTLS Example
+
+```yaml
+type: mutualTLS
+description: Cert must be signed by example.com CA
+```
+
+##### Implicit OAuth2 Example
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+### OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+#### Fixed Fields
+
+| Field Name | Type | Description |
+| ---- | :----: | ---- |
+| implicit | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow |
+| password | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Password flow |
+| clientCredentials | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. |
+| authorizationCode | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. |
+| deviceAuthorization | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Device Authorization flow. |
+
+This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions).
+
+### OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+#### Fixed Fields
+
+| Field Name | Type | Applies To | Description |
+| ---- | :----: | ---- | ---- |
+| authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
+| deviceAuthorizationUrl | `string` | `oauth2` (`"deviceAuthorization"`) | **REQUIRED**. The device authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
+| tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"deviceAuthorization"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
+| refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. |
+| scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. |
+
+This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions).
+
+#### OAuth Flow Object Example
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+ authorizationCode:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ tokenUrl: https://example.com/api/oauth/token
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
## Appendix A - Revision History
TODO: Document notable changes between versions.