Skip to content

Choose the component you need

Before using Jane you have to understand the two schema descriptors we are using:

Each of theses schema descriptors have their own use and you should choose the one that fit your use-case.

At a glance

  • Use JSON Schema when you want DTO/model generation and serializer support from data schemas.
  • Use OpenAPI when you want everything from JSON Schema plus generated API endpoints and an HTTP client.
  • Check Compatibility for version support details.

In depth

JSON Schema

“JSON Schema is a vocabulary that allows you to annotate and validate JSON documents”. So it will allow you to describe your existing data format(s) and provides clear human- and machine- readable documentation. With that descriptor you can describe documents and Jane will generate models & normalizers. This is mostly used when you need DTO or you need to use/store a JSON object that our normalizer can normalize/denormalize.

Tip

You can read more about what is JSON Schema and how to use it on the excellent “Understanding JSON Schema” book.

If you think this is what you need, start with Getting started: using JSON Schema.

Or you can see our detailed guides with more feature-focused content: - Elasticsearch models - API Platform DTO - Validation

OpenAPI

“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection”. This descriptor is on top of JSON Schema, so every feature we have in JSON Schema will be in OpenAPI. And Jane will also generate a Client, endpoints and needed exceptions (for HTTP error responses). This is used with any API Client, some API even provide this file, like Stripe or Slack.

Tip

You can read more about what is OpenAPI and how to use it on API Handyman tutorials.

If you think this is what you need, start with Getting started: using OpenAPI.

Or you can see our detailed guides with more feature-focused content: