### Getting Started with Redocly CLI

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Instructions for installing the Redocly CLI, a tool used for bundling and previewing API specifications.

```bash
npm i -g @redocly/cli
```

```bash
npm run bundle
```

```bash
npm run preview
```

--------------------------------

### Run Docs Preview

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Starts a local development server to preview the API documentation. This command is typically run after installing the necessary dependencies.

```bash
npm run preview
```

--------------------------------

### Install Redocly CLI

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Installs the Redocly CLI globally, which is used for managing and previewing API documentation.

```bash
npm i -g @redocly/cli
```

--------------------------------

### Example: AccountInfo Success Response Base

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

An example of a base success response schema for the AccountInfo request, including common fields like account flags.

```YAML
AccountInfoSuccessResponseBase:
      allOf:
        - $ref: '../base.yaml#/components/schemas/BaseSuccessResponse'
        - type: object
          properties:
            account_flags:
              $ref: '#/components/schemas/AccountFlags'
              description: The account's flag statuses.
            ... More common fields here ...
```

--------------------------------

### Redocly CLI Commands for API Linting and Preview

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This snippet details the commands used with Redocly CLI to lint the API specification and preview the documentation. It includes instructions for installation, linting, logging in, and previewing, along with links to relevant Redocly documentation.

```bash
redocly lint json_api.yaml
```

```bash
redocly login
```

```bash
redocly preview-docs json_api.yaml
```

--------------------------------

### Example: AccountInfo Success Response Version 2

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

An example of a version 2 success response schema for the AccountInfo request, adding version-specific fields like signer lists.

```YAML
AccountInfoSuccessResponseV2:
  allOf:
    - $ref: '#/components/schemas/AccountInfoSuccessResponseBase'
    - type: object
      properties:
        signer_lists:
          type: array
          description: Array of SignerList ledger objects associated with this account for Multi-Signing.
          items:
            $ref: '#/components/schemas/SignerList'
        ...More unique properties here...
```

--------------------------------

### AsyncAPI Request Schema Boilerplate

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Boilerplate for defining a new request schema in AsyncAPI format. This includes fields for description, type, command, ID, and an example request.

```APIDOC
...Request:
   description: >
     ...
   type: object
   allOf:
     - $ref: ... # Reference the Request in `shared/requests` here
   properties:
     command:
       type: string
       enum: # This is the most supported way to define a specific string as the only valid input. `const` is a new keyword which is supported in OpenAPI, but not in all corresponding codegen tools. https://github.com/OAI/OpenAPI-Specification/issues/1313
         - ...
     id:
       # Not specifying a type is how we express "any" value is acceptable
       description: 'A unique identifier for the request.'
   required:
     - command
     - id
   example:
     # Show a valid request that follows the schema here, for example for account_channels:
     # id: 1
     # command: account_channels
     # account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
     # destination_account: ra5nK24KXen9AHvsdFTKHSANinZseWnPcX
     # ledger_index: validated
     ...
```

--------------------------------

### Custom Rule Definition Example

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Provides a template for defining custom validation rules specific to a transaction type. Users can specify their own validation logic and error messages.

```yaml
x-custom-validation:
  validate{{tx_name}}:
    - message: 'specified rules here'
```

--------------------------------

### AsyncAPI Response Schema Boilerplate

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Boilerplate for defining a new response schema in AsyncAPI format. This includes fields for discriminator, oneOf references, type, ID, and an example response.

```APIDOC
...Response:
  discriminator: status
  oneOf:
    - $ref: # Reference the ...SuccessResponse in this file
    - $ref: # Reference the ...ErrorResponse in this file
  type: object
  properties:
    id:
      # Not specifying a type is how we express "any" value is acceptable
      description: 'A unique identifier for the request.'
    type:
      type: string
      description: The value response indicates a direct response to an API request. Asynchronous notifications use a different value such as `ledgerClosed` or `transaction`.
      enum: # This is the most supported way to define a specific string as the only valid input. `const` is a new keyword which is supported in OpenAPI, but not in all corresponding codegen tools. https://github.com/OAI/OpenAPI-Specification/issues/1313
        - response
  required:
    - id
    - type
  example:
   # Example formatting for `account_channels` response
   # id: 1
   # result:
   #   account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
   #   channels:
   #     - account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
   #       amount: '1000'
   #       balance: '0'
   #       channel_id: C7F634794B79DB40E87179A9D1BF05D05797AE7E92DF8E93FD6656E8C4BE3AE7
   #       destination_account: ra5nK24KXen9AHvsdFTKHSANinZseWnPcX
   #       public_key: aBR7mdD75Ycs8DRhMgQ4EMUEmBArF8SEh1hfjrT2V9DQTLNbJVqw

```

--------------------------------

### AI Integration for XRPL Interaction

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Highlights the benefits of a machine-readable API spec for AI, enabling natural language queries, automated query planning, and AI-driven tutorials for easier XRPL onboarding.

```APIDOC
AI Usage:
  - Machine-readable spec enables AI to plan and run queries against XRPL.
  - Facilitates natural language queries and responses.
  - Streamlines developer onboarding with AI-driven tutorials and guides based on the spec.
```

--------------------------------

### Code Generation Prototype for rippled and clio

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This outlines the prototype for code generation for both rippled and clio. It includes generating code stubs for handlers, integrating with the Request Handler for runtime verification, and potentially wiring up existing code execution handlers. It also addresses concerns about binary bloat and suggests PR checklist items for spec updates.

```APIDOC
Code generation prototype
  - Code stubs for handlers
  - Integration with Request Handler
    - Runtime request verification
  - (TBD) Wiring up existing code execution handlers
Integrate generated code with existing codebase, starting with v3 API
Address any concerns about binary bloat from maintaining hand-crafted v1 and v2 along with auto-generated v3 and v4
Add a PR checklist item to update this spec as a stop gap to long-term automated code generation that will bring compile time spec verification, integration tests, and changes to the request handler
```

--------------------------------

### rippled Project Directory Structure

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

This YAML snippet details the directory structure of the rippled project, highlighting key directories for API specifications (async_api, open_api, shared), documentation (docs), and project configuration (package.json, redocly.yaml).

```YAML
.
├── README.md
├── addRequestTemplate.js
├── async_api
│   ├── requests
│   │   ├── account_channels_async_api.yaml
│   │   ├── account_info_async_api.yaml
│   │   ├── submit_async_api.yaml
│   │   └── ...<new_async_api_request.yaml>
│   ├── websocket_api.yaml
│   ├── websocket_api_v2.yaml
│   └── ...<websocket_api_v3.yaml>
├── docs
│   ├── decisions
│   │   ├── 000-template.md
│   │   ├── 001-handle-different-rippled-api-version.md
│   │   └── ...<new_decision.md>
│   ├── ...<new_docs.md>
│   ├── contributing
│   │   ├── how-to-add-a-request.md
│   │   └── ...<other-guidelines.md>
├── open_api
│   ├── json_api.yaml
│   ├── json_api_v2.yaml
│   ├── requests
│   │   ├── account_channels_open_api.yaml
│   │   ├── account_info_open_api.yaml
│   │   ├── submit_open_api.yaml
│   │   └── ...<new_open_api_request.yaml>
│   └── ...<json_api_v3.yaml>
├── package-lock.json
├── package.json
├── redocly.yaml
├── shared
│   ├── base.yaml
│   ├── requests
│   │   ├── account_channels.yaml
│   │   ├── account_info.yaml
│   │   ├── submit.yaml
│   │   └── ...<new_shared_request.yaml>
│   ├── transactions
│   │   ├── payment.yaml
│   │   └── ...<new_transaction.yaml>
└── sidebars.yaml
```

--------------------------------

### rippled API Versioning Strategy

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Details how rippled manages multiple API versions, including splitting major versions into separate files and using shared data structures. It also explains the role of the `api_version` parameter for selecting specs.

```APIDOC
API Versioning:
  - Major API versions are split into different files (e.g., json_api.yaml, json_api_v2.yaml for JSON-RPC; websocket_api.yaml, websocket_api_v2.yaml for Websockets).
  - Shared data structures are split into base files and version-specific files (e.g., shared/requests/account_info.yaml#AccountInfoBase).
  - The `api_version` parameter selects the specification file to use within request handlers.
```

--------------------------------

### XRP Ledger API Documentation Reference

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Reference to the public API methods for the XRP Ledger, detailing the JSON-RPC and Websocket interfaces used for querying the ledger and submitting transactions.

```APIDOC
XRP Ledger API Specifications:

Overview:
  The XRP Ledger provides two primary interfaces for interacting with the blockchain: a JSON-RPC API and a Websockets API. Both are implemented in C++ and are currently documented sparsely in code comments and on xrpl.org.

Goals:
  - Create OpenAPI (for JSON-RPC) and AsyncAPI (for Websockets) specifications.
  - Intimately tie these specifications with `rippled`, `clio`, and all XRPL client libraries via tooling.
  - Enforce interface adherence through CI/CD testing, compile-time static checks, or runtime checking.
  - Automatically generate implementation stubs from the specifications to maintain backwards compatibility.

Existing Interfaces:
  - JSON-RPC: Ad-hoc API for querying and transaction submission.
  - Websockets: API for real-time ledger data and transaction submission.

Client Libraries:
  - xrpl.js
  - xrpl-py
  - xrpl-rust
  - xrpl-go
  - xrpl4j
  - xrpl-php

Motivation:
  - Address duplication of effort and error-proneness in manually keeping client libraries in sync with `rippled` changes.
  - Mitigate drift between client libraries in different languages, ensuring consistent feature support.
  - Improve overall ecosystem tooling and developer experience.

Related Resources:
  - Public API Methods Reference: https://xrpl.org/docs/references/http-websocket-apis/public-api-methods
```

--------------------------------

### AsyncAPI Specification Work Items

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This section details the planned work for the AsyncAPI specification, including handling amendments with external documentation, adding remaining methods and transactions, consolidating API fields for maintainability, and aligning request bodies with OpenAPI for better reuse.

```APIDOC
Handle amendment: use `externalDocs` with description and link toward the Explorer to show active status.
Add remaining methods
Add remaining transactions
Consolidation of API fields id and type into BaseSuccess and BaseError for maintainability and readability
Consolidate request bodies with OpenAPI for more reuse
```

--------------------------------

### XRP Ledger API Architecture

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

A Mermaid diagram illustrating the current and proposed implementation architectures for the XRP Ledger API, highlighting the role of OpenAPI and AsyncAPI specifications.

```mermaid
graph LR
  subgraph Current Implementation
    Websockets-->C++_Headers
    JSON_RPC-->C++_Headers
    C++_Headers-->Function_Calls
    Function_Calls-->Ad_hoc_API
    Ad_hoc_API-->XRP_Ledger
  end

  subgraph Proposed Implementation
    OpenAPI-->|Documents| JSON_RPC
    C++_API_Stubs-->C++_Headers
    C++_API_Stubs-->|Code Gen| Runtime_Validation
    Runtime_Validation-->|Manual Hookup by Devs| Function_Calls
    OpenAPI-->|Code Gen| C++_API_Stubs
    OpenAPI-->|Code Gen| Compile_Checks
    CI_CD_Tests-->XRP_Ledger
    Compile_Checks-->C++_Headers

    OpenAPI-->|Code Gen| CI_CD_Tests

    AsyncAPI-->|Documents| Websockets
    AsyncAPI--> Same_As_OpenAPI
  end

  subgraph Client_Libraries["Client Libraries"]
    XRPL_JS
    XRPL_PY
    XRPL_RUST
    XRPL_GO
    XRPL_4J
  end

  OpenAPI-->|Code Gen - Types, Calls, Tests| Client_Libraries

  JSON_RPC[JSON RPC]
  C++_Headers[C++ Headers]
  Function_Calls[Function Calls]
  Ad_hoc_API[Ad hoc API]
  XRP_Ledger[XRP Ledger]
  OpenAPI[OpenAPI]
  C++_API_Stubs["C++ API Stubs"]
  CI_CD_Tests[Integration Tests]
  Runtime_Validation["Runtime Validation"]
  Compile_Checks["Compile Static Checks"]
  AsyncAPI[AsyncAPI]
  Websockets[Websockets]
  Same_As_OpenAPI["Same As OpenAPI"]
  XRPL_JS["xrpl.js"]
  XRPL_PY["xrpl-py"]
  XRPL_RUST["xrpl-rust"]
  XRPL_GO["xrpl-go"]
  XRPL_4J["xrpl-4j"]

  linkStyle default stroke-width:4px,stroke:green
  linkStyle 3,4,5 stroke-width:4px,stroke:blue
  linkStyle 6,8 stroke-width:4px,stroke:red
  linkStyle 7,10 stroke-width:4px,stroke:orange
  linkStyle 9,11 stroke-width:4px,stroke:blueviolet
```

--------------------------------

### OpenAPI and AsyncAPI Overview

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

OpenAPI and AsyncAPI are industry standards for defining APIs. OpenAPI describes HTTP APIs, while AsyncAPI describes asynchronous APIs like those using WebSockets. These specifications facilitate documentation generation, client library creation, and server stub development, ensuring consistency and interoperability.

```APIDOC
OpenAPI:
  Description: Standard for describing HTTP APIs.
  Use Cases:
    - Generating documentation
    - Creating client libraries
    - Developing server stubs

AsyncAPI:
  Description: Standard for describing asynchronous (event/message based) APIs, such as those using Websockets.
  Use Cases:
    - Generating documentation
    - Creating client libraries
    - Developing server stubs
```

--------------------------------

### Code Generation Practices for API Schemas

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Details conventions for generating API code, including how required fields are specified (at the bottom of schemas), the use of discriminators for JSON RPC type derivation, and handling of binary options and error responses.

```APIDOC
Code Generation Practices:
  - Required fields specified at the bottom of request/response schemas, not per field.
  - JSON RPC request/response types use a generic path ('/') and a `discriminator` based on a parameter (e.g., `method` field).
  - Special handling for requests with a `binary` option, which results in 2 possible response structures.
  - Error responses (HTTP and rippled/clio errors) are documented as `oneOf` possible representations for each request response, specifying unique error codes.
```

--------------------------------

### OpenAPI Specification Work Items

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This section outlines tasks related to the OpenAPI specification, including handling amendments with external documentation links, generating sample requests for various scenarios (errors, multi-step transactions, successful transactions), adding missing methods and transactions, and capturing all HTTP error codes.

```APIDOC
Handle amendment: use `externalDocs` with description and link toward the Explorer to show active status.
Generate sample requests for exercising major features of `rippled` and `clio` and include them in the spec itself
  - All error conditions
    - Samples of different types of validation errors
  - Including things that require multiple things to happen, such as meeting reserve
  - Samples of successful transactions
Add remaining methods
Add remaining transactions
Capture all HTTP error codes in the spec
```

--------------------------------

### rippled API Specification Benefits

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

This section outlines the key benefits of adopting a specification-driven approach for the rippled API. It covers improvements in testing, documentation, robustness, code generation, and the review process.

```APIDOC
Project: /ripple/rippled-api-spec

Benefits:
  - Automated Integration Tests: Verify rippled behavior against specifications (return codes, data structures).
  - Automated Documentation: Keep xrpl.org reference documentation current.
  - Improved Robustness: Enable early design feedback, preventing issues and patches.
  - Automated Code Generation: Automate client library generation (xrpl.js, xrpl-py, etc.), preventing outdated libraries.
  - Consistent Updates: Allow clio to ingest changes and stay updated with rippled.
  - Improved Review Process: Facilitate easier interface code reviews using spec-as-code.
  - Generated Code Stubs: Provide implementation stubs within rippled and clio.
```

--------------------------------

### Account Info Success Response Base and Versioned Details

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/decisions/001-handle-different-rippled-api-version.md

Defines the base structure for Account Info success responses and version-specific details for v1 and v2. It uses allOf to combine base properties with version-specific data like account_data and signer_lists.

```APIDOC
AccountInfoSuccessResponseBase:
      allOf:
        - $ref: '../base.yaml#/components/schemas/BaseSuccessResponse'
        - type: object
          properties:
            account_flags:
              $ref: '#/components/schemas/AccountFlags'
              description: The account's flag statuses.
...

AccountInfoSuccessResponseV1:
  allOf:
    - $ref: '#/components/schemas/AccountInfoSuccessResponseBase'
    - type: object
      properties:
        account_data:
          $ref: '#/components/schemas/AccountRootWithSignerLists'
          description: The AccountRoot ledger object with this account's information, including signer lists, as stored in the ledger.

AccountInfoSuccessResponseV2:
  allOf:
    - $ref: '#/components/schemas/AccountInfoSuccessResponseBase'
    - type: object
      properties:
        account_data:
          $ref: '#/components/schemas/AccountRoot'
          description: The AccountRoot ledger object with this account's information, as stored in the ledger.
        signer_lists:
          type: array
          description: Array of SignerList ledger objects associated with this account for Multi-Signing.
          items:
            $ref: '#/components/schemas/SignerList'
...
```

--------------------------------

### Define Request Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Defines the structure for a new rippled API request. It includes a description, properties, and required fields. Common fields can be inherited from `shared/base.yaml` using `allOf`.

```YAML
...
Request:
  description: >
    ...
  type: object
  # TODO: Add any common fields from `shared/base.yaml` that are applicable using `allOf`. Otherwise delete these comments! For example:
  # allOf:
  #  - $ref: '../base.yaml#/components/schemas/LookupByLedgerRequest'
  #  - ...
  properties:
    # Example property
    # account:
      # type: string
      # description: The unique identifier of an account, typically the account's address.
    ...
  required:
    - ...

```

--------------------------------

### OpenAPI Response Schema References

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Specifies the structure of successful responses (HTTP 200) for a given API version, referencing different response schemas based on the request type. This ensures correct response parsing.

```APIDOC
'200':
          description: JSON-RPC response object
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsResponse'
                  - $ref: 'requests/account_info_open_api.yaml#/components/schemas/AccountInfoResponseV1'
                  ...More response types here...
```

--------------------------------

### Update open_api/json_api.yaml for New Request

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

This section details the necessary updates to the `open_api/json_api.yaml` file to integrate a new request, including modifications to the discriminator mapping, `oneOf` references for requests, and `oneOf` references for responses.

```APIDOC
#paths///post/requestBody/content/application/json/schema/discriminator/mapping
# Update with a mapping between the request name and your `...Request` object from the `..._open_api.yaml` file.
# Ex. account_channels: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsRequest'

# Update the `oneOf` just below the `mapping` with another reference to the `...Request` object from the `..._open_api.yaml` file.
# Ex. - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsRequest'

# Update `#paths///post/responses/200/content/application/json/schema/oneOf` with a reference to the `...Response` object from the `..._open_api.yaml` file.
# Ex. - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsResponse'

```

--------------------------------

### API Versioning and Reuse Strategy

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

The rippled API specification emphasizes reuse across different API types (OpenAPI and AsyncAPI) and within a single OpenAPI specification. Inputs and outputs for the same commands can be shared across transport layers (HTTP vs. WebSockets), mirroring rippled's internal request handling.

```APIDOC
Reuse within API Spec:
  - Inputs and outputs can be shared within a single OpenAPI spec.

Cross-API Reuse:
  - Inputs and outputs can be shared between AsyncAPI and OpenAPI for the same commands.
  - This applies when commands are communicated via different transport layers (HTTP vs. Websockets).
  - Internal Alignment: This strategy matches how rippled handles requests in its codebase.
```

--------------------------------

### Update SuccessResponse Schema Reference

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

This snippet demonstrates how to update the `allOf` block within a `...SuccessResponse` schema to reference a shared `BaseSuccessResponse` and the specific `...SuccessResponse` from the current file.

```APIDOC
...
  type: object
  allOf:
    - $ref: '../../shared/base.yaml#/components/schemas/BaseSuccessResponse'
    - $ref: # Reference the `...SuccessResponse` in the **SHARED** folder
...
```

--------------------------------

### Define Base Request Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Defines a base schema for API requests that includes common fields across all versions. It references a shared base success response and adds common properties.

```YAML
<request_name>ResponseBase:
  allOf:
    - $ref: '../base.yaml#/components/schemas/BaseSuccessResponse'
    - type: object
      properties:
        ...Add all common properties here...
```

--------------------------------

### OpenAPI Request Schema Boilerplate

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Boilerplate for defining a new request schema in OpenAPI format. Includes fields for method, description, and referencing shared request types.

```APIDOC
...Request:
  type: object
  description: >
    ...
  properties:
    method:
      type: string
      enum: # This is the most supported way to define a specific string as the only valid input. `const` is a new keyword which is supported in OpenAPI, but not in all corresponding codegen tools. https://github.com/OAI/OpenAPI-Specification/issues/1313
        - ...
    params:
      type: array
      items:
        $ref: # Reference the shared `...Request` schema
  required:
    - method
  example:
    # Provide a valid example here, such as:
    # method: 'account_channels'
    # params:
    #   - account: 'rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn'
    #     destination_account: 'ra5nK24KXen9AHvsdFTKHSANinZseWnPcX'
    #     ledger_index": 'validated'
```

--------------------------------

### Unprotected Chrome for CORS Error Resolution

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This command launches an unprotected Google Chrome instance to bypass CORS errors when using the Redocly 'Try it!' feature. It creates a temporary user data directory for the instance.

```shell
open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-security
```

--------------------------------

### OpenAPI Discriminator Mapping

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Defines the mapping between request method names and their corresponding OpenAPI schema definitions for a specific API version. This is crucial for routing requests to the correct schema.

```APIDOC
discriminator:
  propertyName: method
  mapping:
    account_channels: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsRequest'
    account_info: 'requests/account_info_open_api.yaml#/components/schemas/AccountInfoRequest'
    ...More request types here...
```

--------------------------------

### AsyncAPI Publish Message Schemas

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Defines the structure of messages that can be published via WebSocket for a specific API version. It maps message IDs to their corresponding payload schemas.

```APIDOC
publish:
      message:
        oneOf:
          - messageId: 'AccountChannelsResponse'
            payload:
              $ref: './requests/account_channels_async_api.yaml#/components/schemas/AccountChannelsResponse'
          - messageId: 'AccountInfoResponse'
            payload:
              $ref: './requests/account_info_async_api.yaml#/components/schemas/AccountInfoResponseV1'
          ...More response types here...
```

--------------------------------

### OpenAPI String Constraints

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Defines string constraints like minimum length, maximum length, and regex patterns using OpenAPI keywords.

```yaml
MPTokenMetadata:
  type: string
  pattern: '^[^0-9A-Fa-f]*$'
  description: |
    Arbitrary metadata about this issuance, in hex format. The limit for this field is 1024 bytes.
  minLength: 0
```

--------------------------------

### Semantic Versioning (Semver) in rippled

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Explains the Semver (Major.Minor.Patch) system as applied to the rippled API. It defines what constitutes a Major (breaking changes), Minor (backward-compatible new features), and Patch (backward-compatible bug fixes) version increment.

```APIDOC
Semantic Versioning (Semver):
  - Major: Incompatible API changes (e.g., method name change, method removal). Requires incrementing Major version (e.g., 1.x.x to 2.0.0).
  - Minor: Backward-compatible addition of new features (e.g., new method, optional parameters). Requires incrementing Minor version (e.g., 1.0.x to 1.1.0).
  - Patch: Backward-compatible bug fix. Requires incrementing Patch version (e.g., 1.0.0 to 1.0.1).
```

--------------------------------

### AccountChannelsSuccessResponse Schema Definition

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Defines the `AccountChannelsSuccessResponse` schema by combining a base success response with a shared success schema. This structure aligns with JSON RPC response formats while promoting schema reusability.

```APIDOC
AccountChannelsSuccessResponse:
  type: object
  allOf:
    - $ref: '../../shared/base.yaml#/components/schemas/BaseSuccessResponse'
    - $ref: # Reference the `...SuccessResponse` in the **SHARED** folder
```

--------------------------------

### Rippled API v2 Specification

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/decisions/001-handle-different-rippled-api-version.md

Defines the OpenAPI 3.1.0 specification for the XRP Ledger Public API (v2). It includes API title, description, license, and version information, along with response schemas for various requests.

```APIDOC
openapi: 3.1.0
info:
  title: XRP Ledger Public API
  description: A JSON RPC API used to query rippled.
  license:
    name: MIT License
    identifier: mit
    url: https://opensource.org/licenses/mit/
  version: 2.0.0
...
      responses:
        '200':
          description: JSON-RPC response object
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: 'requests/account_channels_open_api.yaml#/components/schemas/AccountChannelsResponse'
                  - $ref: 'requests/submit_open_api.yaml#/components/schemas/AccountInfoResponseV2'
...
```

--------------------------------

### AsyncAPI Subscribe Message Schemas

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Defines the structure of messages that can be subscribed to via WebSocket for a specific API version. It maps message IDs to their corresponding payload schemas.

```APIDOC
subscribe:
      message:
        oneOf:
          - messageId: 'AccountChannelsRequest'
            payload:
              $ref: './requests/account_channels_async_api.yaml#/components/schemas/AccountChannelsRequest'
          - messageId: 'AccountInfoRequest'
            payload:
              $ref: './requests/account_info_async_api.yaml#/components/schemas/AccountInfoRequest'
          ...More request types here...
```

--------------------------------

### Account Info Response Schemas (v1 and v2)

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/decisions/001-handle-different-rippled-api-version.md

Defines the structure for Account Info API responses for both v1 and v2. It uses discriminators and oneOf to specify different success and error response types based on the API version.

```APIDOC
AccountInfoResponseV1:
  type: object
  properties:
    result:
      type: object
      discriminator:
        propertyName: status
        mapping:
          success: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoSuccessResponseV1'
          error: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoErrorResponse'
      oneOf:
        - $ref: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoSuccessResponseV1'
        - $ref: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoErrorResponse'
...

AccountInfoResponseV2:
  type: object
  properties:
    result:
      type: object
      discriminator:
        propertyName: status
        mapping:
          success: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoSuccessResponseV2'
          error: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoErrorResponse'
      oneOf:
        - $ref: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoSuccessResponseV2'
        - $ref: '../../shared/requests/account_info.yaml#/components/schemas/AccountInfoErrorResponse'
...
```

--------------------------------

### Define Transaction Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-transaction.md

Defines the structure for a new transaction type in YAML format. Includes transaction name, description, common fields using `allOf`, properties, and required fields.

```YAML
...Transaction:
  description: >
    ...
  type: object
  # TODO: Add any common fields from `shared/base.yaml` that are applicable using `allOf`. Otherwise delete these comments! For example:
  # allOf:
  #  - $ref: '../base.yaml#/components/schemas/BaseTransaction'
  #  - ...
  properties:
    # Example property
    # account:
      # type: string
      # description: The unique identifier of an account, typically the account's address.
    ...
  required:
    - ...

```

--------------------------------

### Define Versioned Request Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-rippled-api-version.md

Creates a specific version of a request schema that inherits from the base request schema. It includes unique properties for that version.

```YAML
<request_name>SuccessResponseV<version>:
  allOf:
    - $ref: '#/components/schemas/<request_name>SuccessResponseBase'
    - type: object
      properties:
        ...Add unique properties here...
```

--------------------------------

### OpenAPI Request/Response Mapping with Discriminator

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/README.md

This snippet demonstrates how the `discriminator` property in OpenAPI 3.0 is used to map request parameters to different schemas and how responses can be differentiated. It highlights a limitation where strict mapping between request and response schemas based on a discriminator is not enforced, which OpenAPI 4.0 aims to resolve.

```APIDOC
paths:
  /: 
    post:
      requestBody:
        content:
          application/json:
            schema:
              discriminator:
                propertyName: method
                mapping:
                  account_channels: '#/components/schemas/AccountChannelsRequest'
                  account_info: '#/components/schemas/AccountInfoRequest'
              oneOf:
                - $ref: '#/components/schemas/AccountChannelsRequest'
                - $ref: '#/components/schemas/AccountInfoRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                discriminator:
                  propertyName: method
                  mapping:
                    account_channels: '#/components/schemas/AccountChannelsResponse'
                    account_info: '#/components/schemas/AccountInfoResponse'
                oneOf:
                  - $ref: '#/components/schemas/AccountChannelsResponse'
                  - $ref: '#/components/schemas/AccountInfoResponse'
```

--------------------------------

### Define Success Response Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Defines the structure for a successful API response. It includes properties and required fields, with the option to inherit common fields from `shared/base.yaml`.

```YAML
...
SuccessResponse:
  # TODO: Add any common fields from `shared/base.yaml` that are applicable using `allOf`. Otherwise delete these comments! For example:
  # allOf:
  #  - $ref: '../base.yaml#/components/schemas/LookupByLedgerRequest'
  #  - ...
  type: object
  properties:
    # Example property
    # account:
      # type: string
      # description: The unique identifier of an account, typically the account's address.
    ...
  required:
    - ...

```

--------------------------------

### Generate Request Boilerplate

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Generates boilerplate code for a new API request using an npm script. The request name should follow snake_case convention. This command creates three YAML files for shared, OpenAPI, and AsyncAPI request specifications.

```bash
npm run template <request_name>
```

--------------------------------

### WebSocket Publish Message Configuration

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Configures the `publish` message in the WebSocket API to reference a specific response schema defined in an asynchronous API file. This links WebSocket published messages to their corresponding response definitions.

```APIDOC
message:
  name: '...Response'
  payload:
    $ref: .../requests/account_channels_async_api.yaml#/components/schemas/AccountChannelsResponse
```

--------------------------------

### Custom Validation: isAccount

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Applies a custom validation rule to ensure a string field represents a valid XRPL base58 account.

```yaml
BaseTransaction:
  type: object
  properties:
    Account:
      type: string
      x-custom-validation:
        isAccount: true
```

--------------------------------

### OpenAPI Number Constraints

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Defines number and integer constraints such as minimum and maximum values, including format specifications.

```yaml
TradingFee:
  type: integer
  format: uint16
  description: |
    (Required) The fee to charge for trades against this AMM instance, in units of 1/100,000.
    A value of 1 is equivalent to 0.001%. The maximum value is 1000, indicating a 1% fee.
  minimum: 0
  maximum: 1000
```

--------------------------------

### Amendments and API Compatibility

Source: https://github.com/ripple/rippled-api-spec/blob/main/README.md

Describes how amendments to the blockchain affect API users. It clarifies that all API versions should access amendment transaction types, potential parameter changes (e.g., DeliverMax vs Amount), and that schema changes to existing transactions necessitate a major API version bump.

```APIDOC
Amendments:
  - Support for new transaction types via blockchain amendments.
  - All API versions (v1, v2, v3, etc.) should access amendment transaction types.
  - Parameters may change (e.g., DeliverMax vs Amount).
  - Schema changes to existing transactions require a major API version bump (breaking change).
  - Documentation should use the `description` field for amendment-specific fields/transactions.
  - Use the `example` field of `ledger_entry` to query for active amendment objects.
```

--------------------------------

### OpenAPI Response Schema Boilerplate

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Boilerplate for defining a new response schema in OpenAPI format. It handles the mapping of success and error responses and includes a oneOf structure for different response types.

```APIDOC
...Response:
  type: object
  properties:
    result:
      type: object
      discriminator:
        propertyName: status
        mapping:
          success: # Include a reference to ...SuccessResponse from this file
          error: # Include a reference to the **shared** ...ErrorResponse
      oneOf:
        - $ref: # Include a reference to ...SuccessResponse from this file
        - $ref: # Include a reference to the **shared** ...ErrorResponse
  required:
    - result
  example:
    # result:
    #   account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
    #   channels:
    #     - account: rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn
    #       amount: '1000'
    #       balance: '0'
    #       channel_id: C7F634794B79DB40E87179A9D1BF05D05797AE7E92DF8E93FD6656E8C4BE3AE7
    #       destination_account: ra5nK24KXen9AHvsdFTKHSANinZseWnPcX
    #       public_key: aBR7mdD75Ycs8DRhMgQ4EMUEmBArF8SEh1hfjrT2V9DQTLNbJVqw
    #       public_key_hex: 03CFD18E689434F032A4E84C63E2A3A6472D684EAF4FD52CA67742F3E24BAE81B2
    #       settle_delay: 60
    #   ledger_hash: 27F530E5C93ED5C13994812787C1ED073C822BAEC7597964608F2C049C2ACD2D
    #   ledger_index: 71766343
    #   status: success
    #   validated: true
    ...
```

--------------------------------

### Define Error Response Schema

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Defines the structure for an API error response. It includes specific error codes, a status, and a reference to the corresponding request schema. It also references universal error codes from `shared/base.yaml`.

```YAML
...
ErrorResponse:
  type: object
  properties:
    error:
      type: string
      oneOf:
        - $ref: '../base.yaml#/components/schemas/UniversalErrorResponseCodes'
        # Add the error codes specific to this response here (ex. invalidParams)
        - enum:
            - ...
      # Include a bullet descrip for every
      description: >
        ...
    status:
      type: string
      enum:
        - error
    request:
      # This should link to the ...Request type you defined above
      $ref: ...
  required:
    - status
    - error
    - request

```

--------------------------------

### WebSocket Subscribe Message Configuration

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/add-a-new-request.md

Configures the `subscribe` message in the WebSocket API to reference a specific request schema defined in an asynchronous API file. This links WebSocket subscriptions to their corresponding request definitions.

```APIDOC
message:
  name: '...Request'
  payload:
    $ref: .../requests/account_channels_async_api.yaml#/components/schemas/AccountChannelsRequest
```

--------------------------------

### OpenAPI Array Constraints

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Defines array constraints including minimum items, maximum items, and uniqueness of elements.

```yaml
NFTokenOffers:
  type: array
  items:
    type: string
  minItems: 1
  description: |
    An array of IDs of the NFTokenOffer objects to cancel. Each entry must be unique.
```

--------------------------------

### Matching Currency Type Validation

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Verifies that two amount fields have the same currency type, meaning both must be XRP or both must be an IOU. This ensures consistency in currency handling.

```yaml
x-custom-validation:
  matchingCurrencyType:
    - field1: { { fieldname } }
      field2: { { fieldname } }
```

--------------------------------

### Require One Of Fields Validation

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Ensures that at least one field from a given list of fields must be present. This is useful for optional fields where at least one is mandatory.

```yaml
x-custom-validation:
  requireOneOf:
    - fields:
        - { { fieldname } }
        - { { fieldname } }
      message: 'Require at-least one of these fields.'
```

--------------------------------

### Custom Validation: dependentPresence

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Applies a custom validation rule where a set of fields are required if a specific dependent field is not empty.

```yaml
x-custom-validation:
  dependentPresence:
    - dependentField: NFTokenBrokerFee
      requiredFields:
        - NFTokenSellOffer
        - NFTokenBuyOffer
```

--------------------------------

### Require Exactly One Field Validation

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Verifies that exactly one field from a specified list of fields must be present. This enforces a single choice among multiple options.

```yaml
x-custom-validation:
  requireExactlyOne:
    - fields:
        - { { fieldname } }
        - { { fieldname } }
      message: 'Exactly one field must be present.'
```

--------------------------------

### Custom Validation: amountGreaterThan

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Applies a custom validation rule to ensure an 'Amount' property is numerically greater than a specified value.

```yaml
Amount:
  type: string
  x-custom-validation:
    amountGreaterThan: 0
```

--------------------------------

### Custom Validation: isLowerCase

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Applies a custom validation rule to ensure a string field is entirely in lower case.

```yaml
Domain:
  type: string
  format: hex
  maxLength: 256
  x-custom-validation:
    isLowerCase: true
```

--------------------------------

### Custom Validation: greaterThan / lessThan

Source: https://github.com/ripple/rippled-api-spec/blob/main/docs/contributing/validation-rules-appendix.md

Applies custom validation rules to ensure an integer field is strictly greater than or less than a specified value.

```yaml
LastUpdateTime:
  type: integer
  x-custom-validation:
    greaterThan: 946684799
```