-- 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 :: Maybe UTCTime
--     }
--     deriving ToSchema via (EncodingSchema User) -- &lt;-- ToSchema instance defined here
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ Required "name" JsonString
--          , Optional "last-login" JsonDateTime
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (fmap (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"
--     ],
--     "type": "object"
--   }
--   </pre>
@package json-spec-openapi
@version 1.0.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 :: Maybe UTCTime
--     }
--     deriving ToSchema via (EncodingSchema User) -- &lt;-- ToSchema instance defined here
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ Required "name" JsonString
--          , Optional "last-login" JsonDateTime
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (fmap (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"
--     ],
--     "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 :: Maybe UTCTime
--     }
--   instance HasJsonEncodingSpec User where
--     type EncodingSpec User =
--       JsonObject
--         '[ Required "name" JsonString
--          , Optional "last-login" JsonDateTime
--          ]
--     toJSONStructure user =
--       (Field @"name" (name user),
--       (fmap (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

-- | Resolve OpenApi name conflicts.
--   
--   The json-spec mechanism for giving names to things is more powerful
--   than OpenApi mechanism for naming things. <a>JsonLet</a> 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
--   <a>JsonLet</a> names to OpenApi names.
--   
--   This type family resolves the conflict by renaming the <a>JsonLet</a>
--   names in your <a>Specification</a> 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
--   <a>Specification</a>s are large. If you happen to know that your
--   <a>Specification</a> 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
--   <tt>".<a>n</a>"</tt> to the name, where <tt><a>n</a></tt> is an
--   integer. So if you are using names that <i>already</i> follow this
--   format you might get into trouble.
--   
--   For instance, this <a>Specification</a> will fail to rename properly:
--   &gt; JsonLet &gt; '[ '("foo", JsonString) &gt; , '("foo.1",
--   JsonString) &gt; ] &gt; ( JsonObject &gt; '[ "field1" ::: JsonRef
--   "foo" &gt; , "field2" ::: JsonLet '[ '("foo", JsonInt)] (JsonRef
--   "foo") &gt; ] &gt; )
--   
--   because the "foo" in "field2" will be renamed to "foo.1", causing a
--   new conflict with the existing "foo.1".
type family Rename (spec :: Specification) :: Specification
instance (Data.JsonSpec.OpenApi.Defs defs more, Data.JsonSpec.OpenApi.Inlineable defs spec, GHC.Internal.TypeLits.KnownSymbol name) => Data.JsonSpec.OpenApi.Defs defs ('(name, spec) : more)
instance Data.JsonSpec.OpenApi.Defs defs '[]
instance Data.JsonSpec.OpenApi.Inlineable defs spec => Data.JsonSpec.OpenApi.Deref defs ('(target, spec) : more) target
instance Data.JsonSpec.OpenApi.Deref defs more target => Data.JsonSpec.OpenApi.Deref defs ('(miss, spec) : more) target
instance Data.JsonSpec.OpenApi.NotDereferenceable defs target => Data.JsonSpec.OpenApi.Deref defs '[] target
instance Data.JsonSpec.OpenApi.Refable defs spec => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonArray spec)
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonBool
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonDateTime
instance (Data.JsonSpec.OpenApi.Refable defs left, Data.JsonSpec.OpenApi.Refable defs right) => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonEither left right)
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonInt
instance (Data.JsonSpec.OpenApi.Inlineable (Data.JsonSpec.OpenApi.Concat newDefs defs) spec, Data.JsonSpec.OpenApi.Defs newDefs newDefs) => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonLet newDefs spec)
instance Data.JsonSpec.OpenApi.Refable defs spec => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonNullable spec)
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonNum
instance (Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonObject more), Data.JsonSpec.OpenApi.Refable defs spec, GHC.Internal.TypeLits.KnownSymbol key) => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonObject ('Data.JsonSpec.Spec.Optional key spec : more))
instance Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonObject '[])
instance (Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonObject ('Data.JsonSpec.Spec.Optional key spec : more)), GHC.Internal.TypeLits.KnownSymbol key) => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonObject ('Data.JsonSpec.Spec.Required key spec : more))
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonRaw
instance Data.JsonSpec.OpenApi.Deref defs defs target => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonRef target)
instance Data.JsonSpec.OpenApi.Inlineable defs 'Data.JsonSpec.Spec.JsonString
instance GHC.Internal.TypeLits.KnownSymbol tag => Data.JsonSpec.OpenApi.Inlineable defs ('Data.JsonSpec.Spec.JsonTag tag)
instance (Data.JsonSpec.OpenApi.Defs newDefs newDefs, Data.JsonSpec.OpenApi.Refable (Data.JsonSpec.OpenApi.Concat newDefs defs) spec) => Data.JsonSpec.OpenApi.Refable defs ('Data.JsonSpec.Spec.JsonLet newDefs spec)
instance GHC.Internal.TypeLits.KnownSymbol name => Data.JsonSpec.OpenApi.Refable defs ('Data.JsonSpec.Spec.JsonRef name)
instance Data.JsonSpec.OpenApi.Inlineable defs a => Data.JsonSpec.OpenApi.Refable defs a
instance Data.JsonSpec.OpenApi.Inlineable '[] spec => Data.JsonSpec.OpenApi.Schemaable spec
instance (Data.JsonSpec.OpenApi.Schemaable (Data.JsonSpec.Decode.DecodingSpec a), GHC.Internal.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), GHC.Internal.Data.Typeable.Internal.Typeable a) => Data.OpenApi.Internal.Schema.ToSchema (Data.JsonSpec.OpenApi.EncodingSchema a)