# spscommerce/sps-api-standards architecture

> Architecture diagram of the GitHub repository spscommerce/sps-api-standards, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spscommerce/sps-api-standards
- Repository: https://github.com/spscommerce/sps-api-standards

## Overview

This repository publishes SPS Commerce REST API design standards and a Spectral ruleset for linting OpenAPI specifications. The principal workflow is for API teams to consult the standards, provide an OpenAPI 3.x specification to Spectral, and validate it against the combined ruleset. The README documents the standards-to-ruleset relationship and linting workflow; source excerpts are limited to package metadata, so internal rule composition is not mapped in detail.

Main entry points: [`rulesets/src`](https://github.com/spscommerce/sps-api-standards/tree/main/rulesets/src) (Ruleset definitions), [`standards/url-structure.md`](https://github.com/spscommerce/sps-api-standards/blob/main/standards/url-structure.md) (URL structure), [`standards/request-response.md`](https://github.com/spscommerce/sps-api-standards/blob/main/standards/request-response.md) (Requests and responses), [`standards/naming.md`](https://github.com/spscommerce/sps-api-standards/blob/main/standards/naming.md) (Naming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["API Standards"]
  node_url_standards["URL structure<br/>[url-structure.md]"]
  node_request_standards["Requests and responses"]
  node_bulk_standards["Bulk operations<br/>[bulk.md]"]
  node_naming_standards["Naming<br/>[naming.md]"]
  node_serialization_standards["Serialization<br/>[serialization.md]"]
  node_collection_standards["Collections<br/>[collections.md]"]
  node_auth_standards["Authentication<br/>[authentication.md]"]
  node_error_standards["Errors<br/>[errors.md]"]
  node_webhook_standards["Webhooks<br/>[webhooks.md]"]
end

subgraph group_validation["Spectral Rules"]
  node_rules_catalog["Ruleset definitions"]
  node_merged_ruleset["Combined ruleset"]
end

subgraph group_workflow["Linting Workflow"]
  node_openapi_spec["OpenAPI specification"]
  node_spectral_cli["Spectral CLI"]
end

node_api_teams(("API teams"))

node_api_teams -->|"consult"| node_url_standards
node_api_teams -->|"consult"| node_request_standards
node_api_teams -->|"consult"| node_bulk_standards
node_api_teams -->|"consult"| node_naming_standards
node_api_teams -->|"consult"| node_serialization_standards
node_api_teams -->|"consult"| node_collection_standards
node_api_teams -->|"consult"| node_auth_standards
node_api_teams -->|"consult"| node_error_standards
node_api_teams -->|"consult"| node_webhook_standards
node_url_standards -->|"represented by"| node_rules_catalog
node_request_standards -->|"represented by"| node_rules_catalog
node_naming_standards -->|"represented by"| node_rules_catalog
node_serialization_standards -->|"represented by"| node_rules_catalog
node_collection_standards -->|"represented by"| node_rules_catalog
node_auth_standards -->|"represented by"| node_rules_catalog
node_error_standards -->|"represented by"| node_rules_catalog
node_rules_catalog -->|"merged into"| node_merged_ruleset
node_api_teams -->|"design"| node_openapi_spec
node_api_teams -->|"run"| node_spectral_cli
node_openapi_spec -->|"lint with"| node_spectral_cli
node_spectral_cli -->|"validate against"| node_merged_ruleset

click node_url_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/url-structure.md"
click node_request_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/request-response.md"
click node_bulk_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/bulk.md"
click node_naming_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/naming.md"
click node_serialization_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/serialization.md"
click node_collection_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/collections.md"
click node_auth_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/authentication.md"
click node_error_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/errors.md"
click node_webhook_standards "https://github.com/spscommerce/sps-api-standards/blob/main/standards/webhooks.md"
click node_rules_catalog "https://github.com/spscommerce/sps-api-standards/tree/main/rulesets/src"
click node_merged_ruleset "https://github.com/spscommerce/sps-api-standards/blob/main/sps-api-standards.spectral.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_url_standards,node_request_standards,node_bulk_standards,node_naming_standards,node_serialization_standards,node_collection_standards,node_auth_standards,node_error_standards,node_webhook_standards toneBlue
class node_rules_catalog,node_merged_ruleset toneAmber
class node_openapi_spec,node_spectral_cli,node_api_teams toneMint
```

## Components

### API Standards

- [URL structure](https://github.com/spscommerce/sps-api-standards/blob/main/standards/url-structure.md): `standards/url-structure.md`
- [Requests and responses](https://github.com/spscommerce/sps-api-standards/blob/main/standards/request-response.md): `standards/request-response.md`
- [Bulk operations](https://github.com/spscommerce/sps-api-standards/blob/main/standards/bulk.md): `standards/bulk.md`
- [Naming](https://github.com/spscommerce/sps-api-standards/blob/main/standards/naming.md): `standards/naming.md`
- [Serialization](https://github.com/spscommerce/sps-api-standards/blob/main/standards/serialization.md): `standards/serialization.md`
- [Collections](https://github.com/spscommerce/sps-api-standards/blob/main/standards/collections.md): `standards/collections.md`
- [Authentication](https://github.com/spscommerce/sps-api-standards/blob/main/standards/authentication.md): `standards/authentication.md`
- [Errors](https://github.com/spscommerce/sps-api-standards/blob/main/standards/errors.md): `standards/errors.md`
- [Webhooks](https://github.com/spscommerce/sps-api-standards/blob/main/standards/webhooks.md): `standards/webhooks.md`

### Spectral Rules

- [Ruleset definitions](https://github.com/spscommerce/sps-api-standards/tree/main/rulesets/src): `rulesets/src`
- [Combined ruleset](https://github.com/spscommerce/sps-api-standards/blob/main/sps-api-standards.spectral.yml): `sps-api-standards.spectral.yml`

### Linting Workflow

- **OpenAPI specification**
- **Spectral CLI**

### Other components

- **API teams**

## Connections

- API teams → URL structure: consult (evidence: `README.md`)
- API teams → Requests and responses: consult (evidence: `README.md`)
- API teams → Bulk operations: consult (evidence: `README.md`)
- API teams → Naming: consult (evidence: `README.md`)
- API teams → Serialization: consult (evidence: `README.md`)
- API teams → Collections: consult (evidence: `README.md`)
- API teams → Authentication: consult (evidence: `README.md`)
- API teams → Errors: consult (evidence: `README.md`)
- API teams → Webhooks: consult (evidence: `README.md`)
- URL structure → Ruleset definitions: represented by (evidence: `README.md`)
- Requests and responses → Ruleset definitions: represented by (evidence: `README.md`)
- Naming → Ruleset definitions: represented by (evidence: `README.md`)
- Serialization → Ruleset definitions: represented by (evidence: `README.md`)
- Collections → Ruleset definitions: represented by (evidence: `README.md`)
- Authentication → Ruleset definitions: represented by (evidence: `README.md`)
- Errors → Ruleset definitions: represented by (evidence: `README.md`)
- Ruleset definitions → Combined ruleset: merged into (evidence: `README.md`)
- API teams → OpenAPI specification: design (evidence: `README.md`)
- API teams → Spectral CLI: run (evidence: `README.md`)
- OpenAPI specification → Spectral CLI: lint with (evidence: `README.md`)
- Spectral CLI → Combined ruleset: validate against (evidence: `README.md`)
