README.md

Saleor JSON Schemas

Tip

Questions or issues? Check our discord channel for help.

Overview

This repository contains JSON schemas used in various Saleor projects. These schemas are written in the 2020-12 JSON Schema specification.

Contents

• Saleor sync webhook response payloads
  • Defines the expected format for responses from synchronous webhooks in Saleor.
  • Further Reading: Saleor Sync Webhooks Documentation
• Adyen App data parameter payloads
  • Specifies the structure of the data parameter used in certain mutations for the Adyen SDK.
  • Further Reading: Adyen App Storefront Integration Guide

Schemas in this repository are written in 2020-12 JSON Schema specification

Using JSON Schemas

You can access these schemas in two ways:

• Clone the repository locally:

git clone https://github.com/saleor/json-schemas.git

• Use the deployed schemas on GitHub pages:

https://saleor.github.io/json-schemas/schemas/saleor/sync-webhooks/transactions/TransactionRefundRequestedResponse.json

JSON Schema docs have a list of available tools you can use schemas for.

Here are some examples that can be used when developing Saleor apps or storefront for Saleor:

TypeScript codegen: json-schema-to-typescript

Using json-schema-to-typescript you can generate TypeScript types based on Saleor JSON Schemas to use in your project:

pnpm i -g json-schema-to-typescript
json2ts -i 'schemas/**/!(*definitions).json' -o ./types

Tip

This codegen supports discriminated unions for more strict type checking (see example)

👉 Example output

export type TransactionCancelationRequestedResponse =
  | {
      pspReference: string;
    }
  | {
      actions?: TransactionActions;
      amount: number;
      externalUrl?: string;
      message?: string;
      pspReference: string;
      result: "CANCEL_SUCCESS";
      time?: string;
    }
  | {
      actions?: TransactionActions;
      amount?: number;
      externalUrl?: string;
      message?: string;
      pspReference: string;
      result: "CANCEL_FAILURE";
      time?: string;
    };
export type TransactionActions = ("CHARGE" | "REFUND" | "CANCEL")[];

Multi-language codegen: quicktype

Quicktype generates strongly-typed models and serializes from JSON Schemas in many programming languages (e.g. Ruby, Flow, Rust, Kotlin, Python, Swift, etc.).

pnpm i -g quicktype
# Generate all Saleor schemas
mkdir types
quicktype -s schema schemas/saleor/**/*.json -o types/saleor.ts --lang typescript

👉 Example output

export interface TransactionCancelationRequestedResponse {
  pspReference: string;
  actions?: Definition[];
  amount?: number;
  externalUrl?: string;
  message?: string;
  result?: TransactionCancelationRequestedResponseResult;
  time?: Date;
}

For TypeScript Quicktype can also generate zod and effect schemas for parsing data to match JSON Schema specification:

# Zod
quicktype -s schema schemas/saleor/**/*.json -o types/saleor.ts --lang typescript-zod
# Effect
quicktype -s schema schemas/saleor/**/*.json -o types/saleor.ts --lang typescript-effect-schema

Note

This codegen doesn't support discriminated unions in TypeScript

👉 Example output

export const TransactionCancelationRequestedResponseSchema = z.object({
  pspReference: z.string(),
  actions: z.array(DefinitionSchema).optional(),
  amount: z.number().optional(),
  externalUrl: z.string().optional(),
  message: z.string().optional(),
  result: TransactionCancelationRequestedResponseResultSchema.optional(),
  time: z.coerce.date().optional(),
});
export type TransactionCancelationRequestedResponse = z.infer<
  typeof TransactionCancelationRequestedResponseSchema
>;

Development

Before starting, install dependencies using pnpm:

pnpm i

Make sure not to use $id parameter in the schema, as it's known to cause issues with codegens.

When using $ref parameter, remember to use path from the root of the repository, wihtout a forward slash, for example:

"time": {
  "$ref": "saleor/definitions.json#/$defs/DateTime"
}

Tip

When referencing to a specific $defs either from another file or in the same file that is not a schema in itself (i.e. it doesn't contain type field in the root JSON object), you need to use a JSON Pointer: #/#defs/<your_definitioon_name> to reference the specific definition.