HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Moduleswagger2-2.8.9Haskell2010

Data.Swagger.Internal.Schema

  • 3 types
  • 3 classes
  • 44 values
  • Packageswagger2-2.8.9
  • Exports51
  • LanguageHaskell2010
  • LicenceBSD-3-Clause
  • SourceSchema.hs
classclass 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.Swagger

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

instance ToSchema Coord where
  declareNamedSchema _ = do
    doubleSchema <- declareSchemaRef (Proxy :: Proxy Double)
    return $ NamedSchema (Just "Coord") $ mempty
      & type_ ?~ SwaggerObject
      & 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

Methods

Instances61ToSchema, …
valuetoNamedSchema :: ToSchema a => Proxy a -> NamedSchema
#

Convert a type into an optionally named schema.

Example2 expressions
toNamedSchema (Proxy :: Proxy String) ^. nameNothingencode (toNamedSchema (Proxy :: Proxy String) ^. schema)"{\"type\":\"string\"}"
Example2 expressions
toNamedSchema (Proxy :: Proxy Day) ^. nameJust "Day"encode (toNamedSchema (Proxy :: Proxy Day) ^. schema)"{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}"
valueschemaName :: ToSchema a => Proxy a -> Maybe Text
#

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

Example1 expression
schemaName (Proxy :: Proxy Int)Nothing
Example1 expression
schemaName (Proxy :: Proxy UTCTime)Just "UTCTime"
valuetoSchema :: ToSchema a => Proxy a -> Schema
#

Convert a type into a schema.

Example1 expression
encode $ toSchema (Proxy :: Proxy Int8)"{\"maximum\":127,\"minimum\":-128,\"type\":\"integer\"}"
Example1 expression
encode $ toSchema (Proxy :: Proxy [Day])"{\"items\":{\"$ref\":\"#/definitions/Day\"},\"type\":\"array\"}"
valuetoSchemaRef :: 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.

Example1 expression
encode $ toSchemaRef (Proxy :: Proxy Integer)"{\"type\":\"integer\"}"
Example1 expression
encode $ toSchemaRef (Proxy :: Proxy Day)"{\"$ref\":\"#/definitions/Day\"}"
valuedeclareSchemaRef
  1. :: ToSchema a
  2. => Proxy a
  3. -> 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).

valueinlineSchemasWhen
  1. :: Data s
  2. => Text -> Bool
  3. -> Definitions Schema
  4. -> s
  5. -> 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.

valueinlineSchemas :: 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.

valuetoInlinedSchema :: ToSchema a => Proxy a -> Schema
#

Convert a type into a schema without references.

Example1 expression
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.

valuepasswordSchema :: Schema
#

Default schema for password string. "password" format is used to hint UIs the input needs to be obscured.

valuesketchSchema :: ToJSON a => a -> Schema
#

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

Example1 expression
encode $ sketchSchema "hello""{\"example\":\"hello\",\"type\":\"string\"}"
Example1 expression
encode $ sketchSchema (1, 2, 3)"{\"example\":[1,2,3],\"items\":{\"type\":\"number\"},\"type\":\"array\"}"
Example1 expression
encode $ sketchSchema ("Jack", 25)"{\"example\":[\"Jack\",25],\"items\":[{\"type\":\"string\"},{\"type\":\"number\"}],\"type\":\"array\"}"
Example2 expressions
data Person = Person { name :: String, age :: Int } deriving (Generic)instance ToJSON Person
valuesketchStrictSchema :: ToJSON a => a -> Schema
#

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

Example1 expression
encode $ sketchStrictSchema "hello""{\"enum\":[\"hello\"],\"maxLength\":5,\"minLength\":5,\"pattern\":\"hello\",\"type\":\"string\"}"
Example1 expression
encode $ sketchStrictSchema (1, 2, 3)"{\"enum\":[[1,2,3]],\"items\":[{\"enum\":[1],\"maximum\":1,\"minimum\":1,\"multipleOf\":1,\"type\":\"number\"},{\"enum\":[2],\"maximum\":2,\"minimum\":2,\"multipleOf\":2,\"type\":\"number\"},{\"enum\":[3],\"maximum\":3,\"minimum\":3,\"multipleOf\":3,\"type\":\"number\"}],\"maxItems\":3,\"minItems\":3,\"type\":\"array\",\"uniqueItems\":true}"
Example1 expression
encode $ sketchStrictSchema ("Jack", 25)"{\"enum\":[[\"Jack\",25]],\"items\":[{\"enum\":[\"Jack\"],\"maxLength\":4,\"minLength\":4,\"pattern\":\"Jack\",\"type\":\"string\"},{\"enum\":[25],\"maximum\":25,\"minimum\":25,\"multipleOf\":25,\"type\":\"number\"}],\"maxItems\":2,\"minItems\":2,\"type\":\"array\",\"uniqueItems\":true}"
Example2 expressions
data Person = Person { name :: String, age :: Int } deriving (Generic)instance ToJSON Person
classclass GToSchema (f :: Type -> Type) where
#

Methods

Instances10GToSchema, …
valuedeclareSchemaBoundedEnumKeyMapping
  1. :: (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value)
  2. => Proxy (map key value)
  3. -> 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.

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

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.

valuetoSchemaBoundedEnumKeyMapping
  1. :: (Bounded key, Enum key, ToJSONKey key, ToSchema key, ToSchema value)
  2. => Proxy (map key value)
  3. -> 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.

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

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.

classclass GSumToSchema (f :: Type -> Type) where
#

Methods

Instances4GSumToSchema
Example3 expressions
import Data.Swaggerimport Data.Aeson (encode)import Data.Aeson.Types (toJSONKeyText)