-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | json-spec-openapi
--   
--   This package provides a way to produce <a>openapi3</a> documentation
--   from a <a>json-spec</a> specification.
--   
--   <h1>Example</h1>
--   
--   Given this data type:
--   
--   <pre>
--   data User = User
--     {      name :: Text
--     , lastLogin :: UTCTime
--     }
--     deriving ToSchema via (EncodingSchema User) -- &lt;-- ToSchema instance defined here
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ '("name", JsonString)
--          , '("last-login", JsonDateTime)
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (Field @"last-login" (lastLogin user),
--       ()))
--   </pre>
--   
--   Calling `Data.Aeson.encode (Data.OpenApi3.toSchema (Proxy :: Proxy
--   User))` will produce the following Schema:
--   
--   <pre>
--   {
--     "additionalProperties": false,
--     "properties": {
--       "last-login": {
--         "format": "date-time",
--         "type": "string"
--       },
--       "name": {
--         "type": "string"
--       }
--     },
--     "required": [
--       "name",
--       "last-login"
--     ],
--     "type": "object"
--   }
--   </pre>
@package json-spec-openapi
@version 0.2.0.0


-- | This module provides tools for integrating the type-level JSON
--   <a>Specification</a> with the "openapi" package.
--   
--   You can use <a>toOpenApiSchema</a> as a low-level tool to transform
--   <tt>json-spec</tt> <a>Specification</a>s into <tt>openapi3</tt>
--   <a>Schema</a>s directly, irrespective of any particular business data
--   type.
--   
--   More likely you will want to use <tt>-XDerivingVia</tt> along with
--   <a>EncodingSchema</a> or <a>DecodingSchema</a> to derive
--   <a>ToSchema</a> instances for your data types.
--   
--   Example, given this data type:
--   
--   <pre>
--   data User = User
--     {      name :: Text
--     , lastLogin :: UTCTime
--     }
--     deriving ToSchema via (EncodingSchema User) -- &lt;-- ToSchema instance defined here
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ '("name", JsonString)
--          , '("last-login", JsonDateTime)
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (Field @"last-login" (lastLogin user),
--       ()))
--   </pre>
--   
--   Calling <tt><a>encode</a> (<a>toSchema</a> (<a>Proxy</a> ::
--   <a>Proxy</a> User))</tt> will produce the following Schema:
--   
--   <pre>
--   {
--     "additionalProperties": false,
--     "properties": {
--       "last-login": {
--         "format": "date-time",
--         "type": "string"
--       },
--       "name": {
--         "type": "string"
--       }
--     },
--     "required": [
--       "name",
--       "last-login"
--     ],
--     "type": "object"
--   }
--   </pre>
--   
--   If you needed more control over the content of the schema you might
--   also consider doing something like this, e.g. in the case where you
--   would like to allow additional properties:
--   
--   <pre>
--   data User = User
--     {      name :: Text
--     , lastLogin :: UTCTime
--     }
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ '("name", JsonString)
--          , '("last-login", JsonDateTime)
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (Field @"last-login" (lastLogin user),
--       ()))
--   instance ToSchema User where
--     declareNamedSchema _proxy =
--         pure $
--           NamedSchema
--             Nothing
--             (
--               toOpenApiSchema (EncodingSpec User)
--                 &amp; set
--                     additionalProperties
--                     (Just (AdditionalPropertiesAllowed True))
--             )
--   </pre>
module Data.JsonSpec.OpenApi

-- | Convert a <a>Specification</a> into an OpenApi <a>Schema</a>. The type
--   class <a>Schemaable</a> is an internal and opaque implementation
--   detail and not something you should have to worry about.
--   
--   It should already have an instance for every <a>Specification</a> that
--   can be turned into a <a>Schema</a>. If it does not, then that is a
--   bug. Please report it! :-)
--   
--   The limitations of this function are:
--   
--   <ul>
--   <li>It behaves in a possibly unexpected way when given a top level
--   schema of the form:<pre>JsonLet '[ '("foo", ...) ] ( JsonRef "foo"
--   )</pre><a>toOpenApiSchema</a> returns a <a>Schema</a>, not a
--   <tt><a>Referenced</a> <a>Schema</a></tt>. Therefore, if the "top
--   level" of the <a>Specification</a> is a <a>JsonRef</a>, then we will
--   try to dereference and inline the referenced schema. In other
--   words,<pre>toOpenApiSchema (Proxy @( JsonLet '[ '("foo", JsonString) ]
--   (JsonRef "foo") ))</pre>will behave as if you had
--   called<pre>toOpenApiSchema (Proxy @( JsonLet '[ '("foo", JsonString) ]
--   JsonString ))</pre>However, if the reference is undefined, then you
--   will get a custom type error explaining what the problem is.</li>
--   <li>With the exception of the above point, we do not check to make
--   sure that every referenced used in the returned <a>Schema</a> actually
--   contains a definition. So for instance this will "work":<pre>let
--   (defs, schema) = toOpenApiSchema (Proxy @( JsonObject '[ ("bar",
--   JsonRef "not-defined") ] )) in ...</pre>This will compile, and will
--   not throw any runtime errors directly, but depending on how you
--   <i>use</i> <tt>defs</tt> and <tt>schema</tt> (like, for instance,
--   generating an OpenApi specification) you will probably encounter a
--   runtime error complaining that "not-defined" hasn't been defined.</li>
--   </ul>
toOpenApiSchema :: forall (spec :: Specification). Schemaable spec => Proxy spec -> (Definitions Schema, Schema)

-- | Specifications that can be turned into OpenApi <a>Schema</a>s.
--   
--   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.
class Schemaable (spec :: Specification)

-- | Helper for defining <a>ToSchema</a> instances based on
--   <a>HasJsonEncodingSpec</a> using <tt>deriving via</tt>.
--   
--   Example:
--   
--   <pre>
--   data MyType = ...
--     deriving ToSchema via (EncodingSchema MyType)
--   instance HasJsonEncodingSchema MyType where
--     ...
--   </pre>
newtype EncodingSchema a
EncodingSchema :: a -> EncodingSchema a
[unEncodingSchema] :: EncodingSchema a -> a

-- | Helper for defining <a>ToSchema</a> instances based on
--   <a>HasJsonDecodingSpec</a> using <tt>deriving via</tt>.
--   
--   Example:
--   
--   <pre>
--   data MyType = ...
--     deriving ToSchema via (DecodingSchema MyType)
--   instance HasJsonDecodingSchema MyType where
--     ...
--   </pre>
newtype DecodingSchema a
DecodingSchema :: a -> DecodingSchema a
[unDecodingSchema] :: DecodingSchema a -> a
instance (Data.JsonSpec.OpenApi.Defs more, Data.JsonSpec.OpenApi.Schemaable spec, GHC.TypeLits.KnownSymbol name) => Data.JsonSpec.OpenApi.Defs ('(name, spec) : more)
instance Data.JsonSpec.OpenApi.Defs '[]
instance (Data.JsonSpec.OpenApi.Defs defs, GHC.TypeLits.KnownSymbol name) => Data.JsonSpec.OpenApi.Refable ('Data.JsonSpec.Spec.JsonLet defs ('Data.JsonSpec.Spec.JsonRef name))
instance GHC.TypeLits.KnownSymbol name => Data.JsonSpec.OpenApi.Refable ('Data.JsonSpec.Spec.JsonRef name)
instance Data.JsonSpec.OpenApi.Schemaable a => Data.JsonSpec.OpenApi.Refable a
instance Data.JsonSpec.OpenApi.Schemaable spec => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonArray spec)
instance Data.JsonSpec.OpenApi.Schemaable 'Data.JsonSpec.Spec.JsonBool
instance Data.JsonSpec.OpenApi.Schemaable 'Data.JsonSpec.Spec.JsonDateTime
instance (Data.JsonSpec.OpenApi.Schemaable left, Data.JsonSpec.OpenApi.Schemaable right) => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonEither left right)
instance Data.JsonSpec.OpenApi.Schemaable 'Data.JsonSpec.Spec.JsonInt
instance GHC.TypeError.Unsatisfiable (((((((Data.JsonSpec.OpenApi.T "`JsonRef \"" 'GHC.TypeError.:<>: Data.JsonSpec.OpenApi.T target) 'GHC.TypeError.:<>: Data.JsonSpec.OpenApi.T "\"` is not defined.\n") 'GHC.TypeError.:$$: Data.JsonSpec.OpenApi.T "You are trying to use a JsonRef as the \"top level\" ") 'GHC.TypeError.:$$: Data.JsonSpec.OpenApi.T "schema. We try to satisfy this request by looking up ") 'GHC.TypeError.:$$: Data.JsonSpec.OpenApi.T "the reference and inlining it.  However in this case you ") 'GHC.TypeError.:$$: Data.JsonSpec.OpenApi.T "are trying to reference a schema which is not defined, ") 'GHC.TypeError.:$$: Data.JsonSpec.OpenApi.T "so this won't work.\n") => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet '[] ('Data.JsonSpec.Spec.JsonRef target))
instance (Data.JsonSpec.OpenApi.Defs defs, Data.JsonSpec.OpenApi.Schemaable spec) => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet defs spec)
instance (GHC.TypeLits.KnownSymbol target, Data.JsonSpec.OpenApi.Schemaable def, Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet more def)) => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet ('(target, def) : more) ('Data.JsonSpec.Spec.JsonRef target))
instance (GHC.TypeLits.KnownSymbol name, Data.JsonSpec.OpenApi.Schemaable def, Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet more ('Data.JsonSpec.Spec.JsonRef target))) => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonLet ('(name, def) : more) ('Data.JsonSpec.Spec.JsonRef target))
instance Data.JsonSpec.OpenApi.Schemaable 'Data.JsonSpec.Spec.JsonNum
instance Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonObject '[])
instance (Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonObject more), Data.JsonSpec.OpenApi.Refable spec, GHC.TypeLits.KnownSymbol key) => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonObject ('(key, spec) : more))
instance Data.JsonSpec.OpenApi.Schemaable 'Data.JsonSpec.Spec.JsonString
instance GHC.TypeLits.KnownSymbol tag => Data.JsonSpec.OpenApi.Schemaable ('Data.JsonSpec.Spec.JsonTag tag)
instance (Data.JsonSpec.OpenApi.Schemaable (Data.JsonSpec.Decode.DecodingSpec a), Data.Typeable.Internal.Typeable a) => Data.OpenApi.Internal.Schema.ToSchema (Data.JsonSpec.OpenApi.DecodingSchema a)
instance (Data.JsonSpec.OpenApi.Schemaable (Data.JsonSpec.Encode.EncodingSpec a), Data.Typeable.Internal.Typeable a) => Data.OpenApi.Internal.Schema.ToSchema (Data.JsonSpec.OpenApi.EncodingSchema a)