JWT to OpenAPI Schema Generator

Paste a decoded JWT JSON payload to generate an OpenAPI 3.0 Schema Object or JSON Schema. 100% client-side.

JWT Payload (JSON)
Generated Schema
Paste a JWT payload JSON object above to generate the schema.

How to Use the JWT to OpenAPI Schema Generator

  1. Decode your JWT — use our JWT Decoder or copy the payload section directly (the middle part of the three dot-separated segments, Base64-decoded to JSON).
  2. Paste the payload JSON into the left panel.
  3. Choose your output mode — OpenAPI 3.0 YAML schema, standalone JSON Schema, or a $ref pointer for inline referencing.
  4. Copy or download the generated schema and paste it into your API specification document.

What Is a JWT Payload?

A JSON Web Token (JWT) is composed of three Base64URL-encoded parts separated by dots: the header, the payload, and the signature. The payload is a JSON object containing claims — name/value pairs that carry information about the token subject, issuer, expiry time, and any custom application data. Common registered claims include sub (subject), iss (issuer), aud (audience), exp (expiration time), nbf (not before), and iat (issued at). Private claims are any additional fields your application needs.

Why Generate an OpenAPI Schema from a JWT Payload?

When building REST APIs that accept or return JWT claims — such as user-info endpoints, token introspection responses, or authentication request bodies — you need a machine-readable description of those fields so that API clients, SDK generators, and documentation tools can understand them. Writing OpenAPI schemas by hand for complex JWT payloads is tedious and error-prone. This tool automates type inference from a real token, saving significant time when documenting /auth/token, /userinfo, or webhook event payloads.

How Type Inference Works

Each key in the JWT payload JSON is examined using JavaScript's typeof operator and Array.isArray():

  • string — maps to type: string
  • number (integer) — maps to type: integer, format: int64 (standard Unix timestamps like iat/exp receive a description annotation)
  • number (float) — maps to type: number, format: float
  • boolean — maps to type: boolean
  • array — maps to type: array with items type inferred from the first element
  • object — maps recursively to a nested type: object with properties
  • null — maps to type: string, nullable: true

OpenAPI 3.0 vs JSON Schema

The OpenAPI 3.0 specification uses a dialect of JSON Schema Draft 07 with several differences: it uses nullable: true instead of type: ["string", "null"], does not support $schema or $id keywords, and adds proprietary extensions like discriminator and xml. The JSON Schema output mode of this tool generates a fully self-contained JSON Schema document, including a $schema declaration, suitable for use with validators like ajv or jsonschema in Python. The Reference mode generates a $ref string you can drop inline inside an OpenAPI path operation's requestBody or responses section, pointing to the schema in components/schemas/JwtPayload.

Standard JWT Claim Annotations

The following registered claim names defined in RFC 7519 are automatically annotated with descriptions when present:

  • sub — Subject: identifies the principal that is the subject of the JWT
  • iss — Issuer: identifies the principal that issued the JWT
  • aud — Audience: identifies the recipients that the JWT is intended for
  • exp — Expiration Time: Unix timestamp after which the JWT must not be accepted
  • nbf — Not Before: Unix timestamp before which the JWT must not be accepted
  • iat — Issued At: Unix timestamp when the JWT was issued
  • jti — JWT ID: unique identifier for the token, used to prevent replay attacks

Integrating into Your OpenAPI Document

After generating the schema, paste it into the components.schemas section of your OpenAPI 3.0 YAML or JSON document. For example:

components:
  schemas:
    JwtPayload:
      type: object
      properties:
        sub:
          type: string
          description: Subject identifier
        exp:
          type: integer
          format: int64
          description: Expiration time (Unix timestamp)

You can then reference this schema in path operations using $ref: '#/components/schemas/JwtPayload'. For more API documentation tooling, try our JSON-LD Schema Generator or JSON Formatter.

Frequently Asked Questions

An OpenAPI Schema Object is a JSON or YAML structure defined in the OpenAPI 3.0 specification that describes the shape, types, and constraints of a data model. It follows a subset of JSON Schema Draft 07 and is used inside OpenAPI documents to describe request bodies, response payloads, and component schemas.
OpenAPI Schema is a strict subset of JSON Schema with a few additions (like 'nullable' and 'discriminator'). JSON Schema is the broader standard. This tool outputs both: the OpenAPI 3.0 Schema Object format (YAML) and a standalone JSON Schema (JSON).
No. This tool runs 100% in your browser. Your JWT payload is never transmitted anywhere. All type inference and schema generation happens locally using client-side JavaScript. There is no server, no logging, and no data collection.
The tool uses JavaScript's typeof operator and Array.isArray() to determine types at runtime. Standard JWT claims like 'iat', 'exp', 'nbf', and 'sub' are annotated with their semantic meaning. Nested objects are recursively described with 'type: object' and nested properties. Arrays infer the type of their first element.
Yes. The 'Generate' mode outputs a YAML snippet you can paste directly into the 'components/schemas' section of an OpenAPI 3.0 document. The 'Reference' mode outputs a $ref pointer so you can reference it from path operations. Review and adjust the generated schema before using it in production.