Documentation

Convert a Specification into an OpenApi Schema. The type class Schemaable is an internal and opaque implementation detail and not something you should have to worry about.

It should already have an instance for every Specification that can be turned into a Schema. If it does not, then that is a bug. Please report it! :-)

The limitations of this function are:

• It behaves in a possibly unexpected way when given a top level schema of the form:

  JsonLet '[
    '("foo", ...)
  ] (
    JsonRef "foo"
  )

  toOpenApiSchema returns a Schema, not a Referenced Schema. Therefore, if the "top level" of the Specification is a JsonRef, then we will try to dereference and inline the referenced schema. In other words,

  toOpenApiSchema (Proxy @(
      JsonLet
        '[ '("foo", JsonString) ]
        (JsonRef "foo")
    ))

  will behave as if you had called

  toOpenApiSchema (Proxy @(
      JsonLet
        '[ '("foo", JsonString) ]
        JsonString
    ))

  However, if the reference is undefined, then you will get a custom type error explaining what the problem is.

• With the exception of the above point, we do not check to make sure that every referenced used in the returned Schema actually contains a definition. So for instance this will "work":

  let
    (defs, schema) =
      toOpenApiSchema
        (Proxy @(
          JsonObject '[
            ("bar", JsonRef "not-defined")
          ]
        ))
  in
    ...

  This will compile, and will not throw any runtime errors directly, but depending on how you use defs and schema (like, for instance, generating an OpenApi specification) you will probably encounter a runtime error complaining that "not-defined" hasn't been defined.

Specifications that can be turned into OpenApi Schemas.

This is intended to be an opaque implementation detail. The only reason it is exported is because there are some cases where you might need to be able to spell this constraint in code that builds off of this package.

Helper for defining ToSchema instances based on HasJsonEncodingSpec using deriving via.

Example:

data MyType = ...
  deriving ToSchema via (EncodingSchema MyType)
instance HasJsonEncodingSchema MyType where
  ...

Helper for defining ToSchema instances based on HasJsonDecodingSpec using deriving via.

Example:

data MyType = ...
  deriving ToSchema via (DecodingSchema MyType)
instance HasJsonDecodingSchema MyType where
  ...

Resolve OpenApi name conflicts.

The json-spec mechanism for giving names to things is more powerful than OpenApi mechanism for naming things. JsonLet allows for nested scopes, where deeper names can shadow other names. OpenApi on the other hand only has a flat space to name schemas, so every name is "globally scoped", resulting in possible name conflicts when mapping JsonLet names to OpenApi names.

This type family resolves the conflict by renaming the JsonLet names in your Specification so that they are all unique, so they won't conflict when mapping them into the global OpenApi schema namespace.

We do not apply this type family by default because it has the potential to add significant compilation time if your Specifications are large. If you happen to know that your Specification contains no name conflicts then you can avoid paying that cost.

It isn't perfect. I've tried to strike a balance between implementation complexity and avoiding unnecessary renames.

Essentially, if a duplicate name is detected, I append a ".n" to the name, where n is an integer. So if you are using names that already follow this format you might get into trouble.

For instance, this Specification will fail to rename properly: > JsonLet > '[ '("foo", JsonString) > , '("foo.1", JsonString) > ] > ( JsonObject > '[ "field1" ::: JsonRef "foo" > , "field2" ::: JsonLet '[ '("foo", JsonInt)] (JsonRef "foo") > ] > )

because the "foo" in "field2" will be renamed to "foo.1", causing a new conflict with the existing "foo.1".