Data.OpenApi.Schema

Types and functions for working with Swagger schema.

Encoding

class ToSchema a where

Convert a type into Schema.

An example type and instance:

{-# LANGUAGE OverloadedStrings #-}   -- allows to write Text literals
{-# LANGUAGE OverloadedLists #-}     -- allows to write Map and HashMap as lists

import Control.Lens
import Data.Proxy
import Data.OpenApi

data Coord = Coord { x :: Double, y :: Double }

instance ToSchema Coord where
  declareNamedSchema _ = do
    doubleSchema <- declareSchemaRef (Proxy :: Proxy Double)
    return $ NamedSchema (Just "Coord") $ mempty
      & type_ ?~ OpenApiObject
      & properties .~
          [ ("x", doubleSchema)
          , ("y", doubleSchema)
          ]
      & required .~ [ "x", "y" ]

Instead of manually writing your ToSchema instance you can use a default generic implementation of declareNamedSchema.

To do that, simply add deriving Generic clause to your datatype and declare a ToSchema instance for your datatype without giving definition for declareNamedSchema.

For instance, the previous example can be simplified into this:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics (Generic)

data Coord = Coord { x :: Double, y :: Double } deriving Generic

instance ToSchema Coord

Minimal complete definition

Nothing

Methods

declareNamedSchema :: Proxy a -> Declare (Definitions Schema) NamedSchema

Convert a type into an optionally named schema together with all used definitions. Note that the schema itself is included in definitions only if it is recursive (and thus needs its definition in scope).

default declareNamedSchema :: (Generic a, GToSchema (Rep a)) => Proxy a -> Declare (Definitions Schema) NamedSchema

Instances

ToSchema Bool

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Bool -> Declare (Definitions Schema) NamedSchema

ToSchema Char

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Char -> Declare (Definitions Schema) NamedSchema

ToSchema Double

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Double -> Declare (Definitions Schema) NamedSchema

ToSchema Float

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Float -> Declare (Definitions Schema) NamedSchema

ToSchema Int

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Int -> Declare (Definitions Schema) NamedSchema

ToSchema Int8

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Int8 -> Declare (Definitions Schema) NamedSchema

ToSchema Int16

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Int16 -> Declare (Definitions Schema) NamedSchema

ToSchema Int32

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Int32 -> Declare (Definitions Schema) NamedSchema

ToSchema Int64

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Int64 -> Declare (Definitions Schema) NamedSchema

ToSchema Integer

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Integer -> Declare (Definitions Schema) NamedSchema

ToSchema Natural

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Natural -> Declare (Definitions Schema) NamedSchema

ToSchema Word

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Word -> Declare (Definitions Schema) NamedSchema

ToSchema Word8

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Word8 -> Declare (Definitions Schema) NamedSchema

ToSchema Word16

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Word16 -> Declare (Definitions Schema) NamedSchema

ToSchema Word32

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Word32 -> Declare (Definitions Schema) NamedSchema

ToSchema Word64

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Word64 -> Declare (Definitions Schema) NamedSchema

ToSchema ()

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy () -> Declare (Definitions Schema) NamedSchema

ToSchema String

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy String -> Declare (Definitions Schema) NamedSchema

ToSchema Version

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Version -> Declare (Definitions Schema) NamedSchema

(ToSchemaByteStringError ByteString :: Constraint) => ToSchema ByteString

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy ByteString -> Declare (Definitions Schema) NamedSchema

(ToSchemaByteStringError ByteString :: Constraint) => ToSchema ByteString

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy ByteString -> Declare (Definitions Schema) NamedSchema

ToSchema Scientific

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Scientific -> Declare (Definitions Schema) NamedSchema

ToSchema Text

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Text -> Declare (Definitions Schema) NamedSchema

ToSchema UTCTime

>>> toSchema (Proxy :: Proxy UTCTime) ^. format
Just "yyyy-mm-ddThh:MM:ssZ"

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy UTCTime -> Declare (Definitions Schema) NamedSchema

ToSchema Object

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Object -> Declare (Definitions Schema) NamedSchema

ToSchema Text

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Text -> Declare (Definitions Schema) NamedSchema

ToSchema All

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy All -> Declare (Definitions Schema) NamedSchema

ToSchema Any

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Any -> Declare (Definitions Schema) NamedSchema

ToSchema IntSet

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy IntSet -> Declare (Definitions Schema) NamedSchema

ToSchema ZonedTime

Format "date" corresponds to yyyy-mm-ddThh:MM:ss(Z|+hh:MM) format.

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy ZonedTime -> Declare (Definitions Schema) NamedSchema

ToSchema LocalTime

>>> toSchema (Proxy :: Proxy LocalTime) ^. format
Just "yyyy-mm-ddThh:MM:ss"

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy LocalTime -> Declare (Definitions Schema) NamedSchema

ToSchema TimeOfDay

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy TimeOfDay -> Declare (Definitions Schema) NamedSchema

ToSchema NominalDiffTime

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy NominalDiffTime -> Declare (Definitions Schema) NamedSchema

ToSchema Day

Format "date" corresponds to yyyy-mm-dd format.

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy Day -> Declare (Definitions Schema) NamedSchema

ToSchema UUID

For ToJSON instance, see uuid-aeson package.

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy UUID -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema [a]

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy [a] -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Maybe a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Maybe a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Identity a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Identity a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (First a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (First a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Last a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Last a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Dual a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Dual a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Sum a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Sum a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Product a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Product a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (NonEmpty a)

Since: 2.2.1

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (NonEmpty a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (IntMap a)

NOTE: This schema does not account for the uniqueness of keys.

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (IntMap a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Set a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Set a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (HashSet a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (HashSet a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Vector a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Vector a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Vector a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Vector a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Vector a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Vector a) -> Declare (Definitions Schema) NamedSchema

ToSchema a => ToSchema (Vector a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Vector a) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b) => ToSchema (Either a b)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Either a b) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b) => ToSchema (a, b)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b) -> Declare (Definitions Schema) NamedSchema

(ToJSONKey k, ToSchema k, ToSchema v) => ToSchema (HashMap k v)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (HashMap k v) -> Declare (Definitions Schema) NamedSchema

(ToJSONKey k, ToSchema k, ToSchema v) => ToSchema (Map k v)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Map k v) -> Declare (Definitions Schema) NamedSchema

HasResolution a => ToSchema (Fixed a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (Fixed a) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b, ToSchema c) => ToSchema (a, b, c)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b, c) -> Declare (Definitions Schema) NamedSchema

(ToSchema1 f, Generic (f a), GToSchema (Rep (f a)), Typeable (f a), ToSchema a) => ToSchema (BySchema1 f a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (BySchema1 f a) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b, ToSchema c, ToSchema d) => ToSchema (a, b, c, d)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b, c, d) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e) => ToSchema (a, b, c, d, e)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b, c, d, e) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f) => ToSchema (a, b, c, d, e, f)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b, c, d, e, f) -> Declare (Definitions Schema) NamedSchema

(ToSchema a, ToSchema b, ToSchema c, ToSchema d, ToSchema e, ToSchema f, ToSchema g) => ToSchema (a, b, c, d, e, f, g)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (a, b, c, d, e, f, g) -> Declare (Definitions Schema) NamedSchema

declareSchema :: ToSchema a => Proxy a -> Declare (Definitions Schema) Schema

Convert a type into a schema and declare all used schema definitions.

declareSchemaRef :: ToSchema a => Proxy a -> Declare (Definitions Schema) (Referenced Schema)

Convert a type into a referenced schema if possible and declare all used schema definitions. Only named schemas can be referenced, nameless schemas are inlined.

Schema definitions are typically declared for every referenced schema. If declareSchemaRef returns a reference, a corresponding schema will be declared (regardless of whether it is recusive or not).

toSchema :: ToSchema a => Proxy a -> Schema

Convert a type into a schema.

>>> BSL.putStrLn $ encode $ toSchema (Proxy :: Proxy Int8)
{"maximum":127,"minimum":-128,"type":"integer"}

>>> BSL.putStrLn $ encode $ toSchema (Proxy :: Proxy [Day])
{"items":{"$ref":"#/components/schemas/Day"},"type":"array"}

toSchemaRef :: ToSchema a => Proxy a -> Referenced Schema

Convert a type into a referenced schema if possible. Only named schemas can be referenced, nameless schemas are inlined.

>>> BSL.putStrLn $ encode $ toSchemaRef (Proxy :: Proxy Integer)
{"type":"integer"}

>>> BSL.putStrLn $ encode $ toSchemaRef (Proxy :: Proxy Day)
{"$ref":"#/components/schemas/Day"}

schemaName :: ToSchema a => Proxy a -> Maybe Text

Get type's schema name according to its ToSchema instance.

>>> schemaName (Proxy :: Proxy Int)
Nothing

>>> schemaName (Proxy :: Proxy UTCTime)
Just "UTCTime"

toInlinedSchema :: ToSchema a => Proxy a -> Schema

Convert a type into a schema without references.

>>> BSL.putStrLn $ encode $ toInlinedSchema (Proxy :: Proxy [Day])
{"items":{"example":"2016-07-22","format":"date","type":"string"},"type":"array"}

WARNING: toInlinedSchema will produce infinite schema when inlining recursive schemas.

class ToSchema1 (f :: * -> *) where

This class allows to generate schemas for polymorphic types (of kind Type -> Type).

Intended usage:

>>> data Foo a = Foo { foo :: a, bar :: Int } deriving (Eq, Show, Generic, ToSchema1)
>>> :{
instance (ToSchema a, Typeable a) => ToSchema (Foo a) where
  declareNamedSchema _ = declareNamedSchema @(BySchema1 Foo a) Proxy
:}

>>> toNamedSchema @(Foo Int) Proxy ^. name
Just "Foo_Int"
>>> toNamedSchema @(Foo Bool) Proxy ^. name
Just "Foo_Bool"
>>> toNamedSchema @(Foo (Foo T.Text)) Proxy ^. name
Just "Foo_(Foo_Text)"

Minimal complete definition

Nothing

Methods

declareNamedSchema1 :: (Generic (f a), GToSchema (Rep (f a)), ToSchema a) => Proxy f -> Proxy a -> Declare (Definitions Schema) NamedSchema

default declareNamedSchema1 :: forall a. (ToSchema a, Generic (f a), GToSchema (Rep (f a))) => Proxy f -> Proxy a -> Declare (Definitions Schema) NamedSchema

newtype BySchema1 f a

For GHC 8.6+ it's more convenient to use DerivingVia to derive instances of ToSchema using ToSchema1 instance, like this:

>>> data Foo a = Foo { foo :: a, bar :: Int } deriving (Eq, Show, Generic, ToSchema1)
>>> deriving via BySchema1 Foo a instance (ToSchema a, Typeable a) => ToSchema (Foo a)

Constructors

BySchema1 (f a)

Instances

(ToSchema1 f, Generic (f a), GToSchema (Rep (f a)), Typeable (f a), ToSchema a) => ToSchema (BySchema1 f a)

Defined in Data.OpenApi.Internal.Schema

Methods

declareNamedSchema :: Proxy (BySchema1 f a) -> Declare (Definitions Schema) NamedSchema

Generic schema encoding

genericDeclareNamedSchema :: forall a. (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) NamedSchema

A configurable generic NamedSchema creator. This function applied to defaultSchemaOptions is used as the default for declareNamedSchema when the type is an instance of Generic.

genericDeclareSchema :: (Generic a, GToSchema (Rep a)) => SchemaOptions -> Proxy a -> Declare (Definitions Schema) Schema

A configurable generic Schema creator.

genericDeclareNamedSchemaNewtype

Arguments

:: forall a d c s i inner. (Generic a, Datatype d, Rep a ~ D1 d (C1 c (S1 s (K1 i inner))))

=> SchemaOptions

How to derive the name.

-> (Proxy inner -> Declare (Definitions Schema) Schema)

How to create a schema for the wrapped type.

-> Proxy a

-> Declare (Definitions Schema) NamedSchema

Declare a named schema for a newtype wrapper.

genericNameSchema :: forall a d f. (Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> Schema -> NamedSchema

Derive a Generic-based name for a datatype and assign it to a given Schema.

Bounded Integral

genericToNamedSchemaBoundedIntegral :: forall a d f. (Bounded a, Integral a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema

Default generic named schema for Bounded, Integral types.

toSchemaBoundedIntegral :: forall a. (Bounded a, Integral a) => Proxy a -> Schema

Default schema for Bounded, Integral types.

>>> BSL.putStrLn $ encode $ toSchemaBoundedIntegral (Proxy :: Proxy Int16)
{"maximum":32767,"minimum":-32768,"type":"integer"}

Bounded Enum key mappings

declareSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Declare (Definitions Schema) Schema

Declare Schema for a mapping with Bounded Enum keys. This makes a much more useful schema when there aren't many options for key values.

>>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
>>> instance ToJSON ButtonState
>>> instance ToSchema ButtonState
>>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
>>> type ImageUrl = T.Text
>>> BSL.putStrLn $ encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
{"type":"object","properties":{"Focus":{"type":"string"},"Disabled":{"type":"string"},"Active":{"type":"string"},"Neutral":{"type":"string"},"Hover":{"type":"string"}}}

Note: this is only useful when key is encoded with ToJSONKeyText. If it is encoded with ToJSONKeyValue then a regular schema for [(key, value)] is used.

toSchemaBoundedEnumKeyMapping :: forall map key value. (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value) => Proxy (map key value) -> Schema

A Schema for a mapping with Bounded Enum keys. This makes a much more useful schema when there aren't many options for key values.

>>> data ButtonState = Neutral | Focus | Active | Hover | Disabled deriving (Show, Bounded, Enum, Generic)
>>> instance ToJSON ButtonState
>>> instance ToSchema ButtonState
>>> instance ToJSONKey ButtonState where toJSONKey = toJSONKeyText (T.pack . show)
>>> type ImageUrl = T.Text
>>> BSL.putStrLn $ encode $ toSchemaBoundedEnumKeyMapping (Proxy :: Proxy (Map ButtonState ImageUrl))
{"type":"object","properties":{"Focus":{"type":"string"},"Disabled":{"type":"string"},"Active":{"type":"string"},"Neutral":{"type":"string"},"Hover":{"type":"string"}}}

Note: this is only useful when key is encoded with ToJSONKeyText. If it is encoded with ToJSONKeyValue then a regular schema for [(key, value)] is used.

Reusing ToParamSchema

paramSchemaToNamedSchema :: (ToParamSchema a, Generic a, Rep a ~ D1 d f, Datatype d) => SchemaOptions -> Proxy a -> NamedSchema

Construct NamedSchema usinng ToParamSchema.

paramSchemaToSchema :: ToParamSchema a => Proxy a -> Schema

Construct Schema usinng ToParamSchema.

Sketching Schemas using ToJSON

sketchSchema :: ToJSON a => a -> Schema

Make an unrestrictive sketch of a Schema based on a ToJSON instance. Produced schema can be used for further refinement.

>>> BSL.putStrLn $ encode $ sketchSchema "hello"
{"example":"hello","type":"string"}

>>> BSL.putStrLn $ encode $ sketchSchema (1, 2, 3)
{"example":[1,2,3],"items":{"type":"number"},"type":"array"}

>>> BSL.putStrLn $ encode $ sketchSchema ("Jack", 25)
{"example":["Jack",25],"items":[{"type":"string"},{"type":"number"}],"type":"array"}

>>> data Person = Person { name :: String, age :: Int } deriving (Generic)
>>> instance ToJSON Person
>>> BSL.putStrLn $ encode $ sketchSchema (Person "Jack" 25)
{"example":{"age":25,"name":"Jack"},"required":["age","name"],"type":"object","properties":{"age":{"type":"number"},"name":{"type":"string"}}}

sketchStrictSchema :: ToJSON a => a -> Schema

Make a restrictive sketch of a Schema based on a ToJSON instance. Produced schema uses as much constraints as possible.

>>> BSL.putStrLn $ encode $ sketchStrictSchema "hello"
{"maxLength":5,"pattern":"hello","minLength":5,"type":"string","enum":["hello"]}

>>> BSL.putStrLn $ encode $ sketchStrictSchema (1, 2, 3)
{"minItems":3,"uniqueItems":true,"items":[{"maximum":1,"minimum":1,"multipleOf":1,"type":"number","enum":[1]},{"maximum":2,"minimum":2,"multipleOf":2,"type":"number","enum":[2]},{"maximum":3,"minimum":3,"multipleOf":3,"type":"number","enum":[3]}],"maxItems":3,"type":"array","enum":[[1,2,3]]}

>>> BSL.putStrLn $ encode $ sketchStrictSchema ("Jack", 25)
{"minItems":2,"uniqueItems":true,"items":[{"maxLength":4,"pattern":"Jack","minLength":4,"type":"string","enum":["Jack"]},{"maximum":25,"minimum":25,"multipleOf":25,"type":"number","enum":[25]}],"maxItems":2,"type":"array","enum":[["Jack",25]]}

>>> data Person = Person { name :: String, age :: Int } deriving (Generic)
>>> instance ToJSON Person
>>> BSL.putStrLn $ encode $ sketchStrictSchema (Person "Jack" 25)
{"minProperties":2,"required":["age","name"],"maxProperties":2,"type":"object","enum":[{"age":25,"name":"Jack"}],"properties":{"age":{"maximum":25,"minimum":25,"multipleOf":25,"type":"number","enum":[25]},"name":{"maxLength":4,"pattern":"Jack","minLength":4,"type":"string","enum":["Jack"]}}}

Inlining Schemas

inlineNonRecursiveSchemas :: Data s => Definitions Schema -> s -> s

Inline all non-recursive schemas for which the definition can be found in Definitions.

inlineAllSchemas :: Data s => Definitions Schema -> s -> s

Inline all schema references for which the definition can be found in Definitions.

WARNING: inlineAllSchemas will produce infinite schemas when inlining recursive schemas.

inlineSchemas :: Data s => [Text] -> Definitions Schema -> s -> s

Inline any referenced schema if its name is in the given list.

NOTE: if a referenced schema is not found in definitions it stays referenced even if it appears in the list of names.

WARNING: inlineSchemas will produce infinite schemas when inlining recursive schemas.

inlineSchemasWhen :: Data s => (Text -> Bool) -> Definitions Schema -> s -> s

Inline any referenced schema if its name satisfies given predicate.

NOTE: if a referenced schema is not found in definitions the predicate is ignored and schema stays referenced.

WARNING: inlineSchemasWhen will produce infinite schemas when inlining recursive schemas.

Generic encoding configuration

data SchemaOptions

Options that specify how to encode your type to Swagger schema.

Constructors

SchemaOptions

Fields

• fieldLabelModifier :: String -> String

  Function applied to field labels. Handy for removing common record prefixes for example.

• constructorTagModifier :: String -> String

  Function applied to constructor tags which could be handy for lower-casing them for example.

• datatypeNameModifier :: String -> String

  Function applied to datatype name.

• allNullaryToStringTag :: Bool

  If True the constructors of a datatype, with all nullary constructors, will be encoded to a string enumeration schema with the constructor tags as possible values.

• unwrapUnaryRecords :: Bool

  Hide the field name when a record constructor has only one field, like a newtype.

• sumEncoding :: SumEncoding

  Specifies how to encode constructors of a sum datatype.

defaultSchemaOptions :: SchemaOptions

Default encoding SchemaOptions.

SchemaOptions
{ fieldLabelModifier     = id
, constructorTagModifier = id
, datatypeNameModifier   = id
, allNullaryToStringTag  = True
, unwrapUnaryRecords     = False
, sumEncoding            = defaultTaggedObject
}

fromAesonOptions :: Options -> SchemaOptions

Convert Options to SchemaOptions.

Specifically the following fields get copied:

• fieldLabelModifier
• constructorTagModifier
• allNullaryToStringTag
• unwrapUnaryRecords

Note that these fields have no effect on SchemaOptions:

• omitNothingFields
• tagSingleConstructors

The rest is defined as in defaultSchemaOptions.

Since: 2.2.1