---
title: "JSON Schemas"
description: "Validate stored forges data, or generate types for another language, from a JSON Schema for each public model."
canonical_url: "https://forgeslink-dy7thxyug-poetry.vercel.app/reference/json-schemas"
---
# JSON Schemas

> Validate stored forges data, or generate types for another language, from a JSON Schema for each public model.

`forges` describes its data model with JSON Schemas. They let you check data that you stored as JSON, and they let languages other than TypeScript generate the same types. The schemas are generated from the TypeScript types, so they always match.

## Use the models in code

`forges/schema` exports `models`, an object keyed by model name. The schemas refer to each other in the OpenAPI form `#/components/schemas/<Type>`, which means you can use `models` directly as the `components.schemas` of an OpenAPI document.

```ts
import { models } from 'forges/schema'

// { type: 'object', properties: { ref: ..., kind: ... }, required: [...] }
models.Thread
```

## Use the verb signatures

`forges/schema` also exports `verbs`, keyed by the verb's path on `ForgeProvider`. Each signature carries the verb's JSDoc summary, its `write`, `account` and `listing` flags, its positional parameters, and its result. The parameter that carries the request's `AbortSignal` is marked with `options: true`, and its schema leaves `signal` out. A verb that answers with a byte stream sets `stream: true`.

```ts
import { models, verbs } from 'forges/schema'

const get = verbs['repos.get']
// get.params[0].schema is { $ref: '#/components/schemas/RepoRef' }
// get.params[1].options is true
// get.result is { $ref: '#/components/schemas/Repo' }
```

Every `$ref` points into `models`, so the two exports describe the same OpenAPI components.

## Use the models as files

If you need a file, `forges/schema/<Type>.json` contains one type as a standalone [draft-07](https://json-schema.org/draft-07) document. It carries the definitions that it refers to, so a validator needs nothing else. The following example validates stored data with Ajv:

```ts
import Ajv from 'ajv'
import { reviveDates } from 'forges'
import thread from 'forges/schema/Thread.json' with { type: 'json' }

const validate = new Ajv({ strict: false, validateFormats: false }).compile(thread)

const stored = JSON.parse(text)
if (!validate(stored)) {
  throw new Error('Not a Thread')
}

// JSON has no dates, so turn the ISO strings back into `Date`s.
const value = reviveDates(stored)
```

## What the models say

A few conventions apply to every model:

- `Date` fields are `{ type: 'string', format: 'date-time' }`, because JSON has no dates. To turn them back into dates, use [`reviveDates()`](https://forgeslink-dy7thxyug-poetry.vercel.app/reference/data-model#revivedates).
- JSON can't carry bytes, so `Uint8Array` fields, such as the content of a binary file, are `{ "$bytes": "<base64>" }`.
- A listing result is `PageOf<Type>`, the schema of `Page<Type>` with its `items` of that type.
- The `raw` and `payload` fields accept anything, because they hold the response of the forge as it was.
- Objects accept extra properties. This way, a newer version of `forges` can add a field without breaking data that you stored earlier.
- Every model has an `x-forges-type` with its name.

## Available models

`Actor`, `AddCollaboratorResult`, `AlertSupport`, `AuthKind`, `AuthorAssociation`, `BaseOptions`, `Branch`, `BranchRules`, `BulkNotificationOptions`, `ChangedFile`, `Check`, `CheckRef`, `CheckReportInput`, `CheckState`, `ChecksSummary`, `CiJob`, `CiJobRef`, `CiRun`, `CiRunQuery`, `CiRunRef`, `CloseOptions`, `CodeFragment`, `CodeMatch`, `CodeSearchQuery`, `Collaborator`, `Comment`, `CommentRef`, `Commit`, `CommitComment`, `CommitCommentRef`, `CommitFilesInput`, `CommitQuery`, `CommitRef`, `CommitSearchQuery`, `CommitSignature`, `CompareOptions`, `Comparison`, `Contributor`, `ContributorQuery`, `ContributorStats`, `ContributorWeek`, `Cursor`, `EventAction`, `EventDetail`, `EventFeedOptions`, `EventKind`, `FileChange`, `FileContent`, `FileOptions`, `FileStatus`, `ForgeCapabilities`, `ForgeEvent`, `ForgeInstance`, `ForgeKind`, `ForgeWarning`, `ForgeWarningCode`, `GetManyResult`, `Installation`, `InstallationToken`, `IssueType`, `KnownForgeKind`, `Label`, `LabelInput`, `ListOptions`, `LockOptions`, `MergeCommitDefaults`, `MergeMethod`, `MergeOptions`, `MergeResult`, `Milestone`, `MilestoneListOptions`, `Notification`, `NotificationListOptions`, `NotificationReason`, `NotificationRef`, `NotificationSubject`, `NotificationWriteOptions`, `OwnerRepoQuery`, `PageOfActor`, `PageOfBranch`, `PageOfChangedFile`, `PageOfCheck`, `PageOfCiJob`, `PageOfCiRun`, `PageOfCodeMatch`, `PageOfCollaborator`, `PageOfComment`, `PageOfCommit`, `PageOfCommitComment`, `PageOfContributor`, `PageOfForgeEvent`, `PageOfInstallation`, `PageOfLabel`, `PageOfMilestone`, `PageOfNotification`, `PageOfReaction`, `PageOfRelease`, `PageOfRepo`, `PageOfReview`, `PageOfReviewThread`, `PageOfSecurityAlert`, `PageOfTag`, `PageOfTeam`, `PageOfThread`, `PageOfTreeEntry`, `PageOfWebhook`, `PageOfWebhookDeliveryRecord`, `PageOptions`, `PerKind`, `PullBranches`, `PullStats`, `PushCommit`, `RateLimit`, `Reaction`, `ReactionContent`, `ReactionSummary`, `Release`, `ReleaseAsset`, `ReleaseAssetRef`, `ReleaseInput`, `ReleaseRef`, `ReleaseUpdate`, `Repo`, `RepoAffiliation`, `RepoFeatures`, `RepoGetOptions`, `RepoPermissions`, `RepoQuery`, `RepoRef`, `RepoRole`, `RepoSearchQuery`, `RepoTemplate`, `RepoTemplateField`, `RepoTemplateOptions`, `RepoVisibility`, `RequiredCheck`, `ResolvedCommentRef`, `ResolvedReviewRef`, `ResolvedThreadRef`, `Review`, `ReviewComment`, `ReviewCommentInput`, `ReviewEvent`, `ReviewInput`, `ReviewRef`, `ReviewState`, `ReviewThread`, `ReviewThreadListOptions`, `Reviewer`, `SecurityAlert`, `SecurityAlertKind`, `SecurityAlertListOptions`, `SecurityAlertRef`, `SecuritySeverity`, `SourceKind`, `SponsorableManyResult`, `StreamOptions`, `SubscriptionState`, `Support`, `Tag`, `Team`, `TeamRef`, `TextLimits`, `Thread`, `ThreadInput`, `ThreadKind`, `ThreadQuery`, `ThreadRef`, `ThreadSearchQuery`, `ThreadSnapshot`, `ThreadStack`, `ThreadState`, `ThreadUpdate`, `TreeEntry`, `TreeEntryType`, `TreeOptions`, `UpdateBranchMethod`, `UpdateBranchOptions`, `UpdateBranchResult`, `User`, `Webhook`, `WebhookDelivery`, `WebhookDeliveryRecord`, `WebhookDeliveryRef`, `WebhookEventType`, `WebhookInput`, `WebhookRef`, `WebhookUpdate`


## Sitemap

See the full [sitemap](https://forgeslink-dy7thxyug-poetry.vercel.app/sitemap.md) for all pages.