Add ToSchema Value

[phadej]

AFAICS there isn't one. It's not that useful, but good to have for completeness

[fizruk]

I don't think that's a good idea for reasons similar to bytestrings. If your servant API accepts/responds with just Value — wrap it in a newtype with meaningful description. We could provide helpers for that though, e.g. payloadJSONSchema or anyObjectSchema.

[phadej]

I'd like to have Value instance still, as they might be somewhere deep in the objects.

ByteString is different, as it doesn't have ToJSON/FromJSON instances either.

[fizruk]

Fine then. Are you willing to make a PR?
Also, is there a way to attach a compile-time warning to the instance? If so, should we add one?

[saurabhnanda]

I just got bitten by lack of this instance. My usecase -- supporting Posgres' JSONB in my client-facing JSON API as well.

[fizruk]

@saurabhnanda is there a reason you can't use a newtype wrapper around Value?
Does it have to be any Value or is it Object really?

E.g. we have something like this to be able collect some extra info we haven't added to the API yet:

newtype Extra = Extra { getExtra :: Object }
  deriving (Eq, Show, ToJSON, FromJSON)

instance ToSchema Extra where
  declareNamedSchema _ = pure $ NamedSchema (Just "Extra") $ mempty
    & type_ .~ SwaggerObject
    & description ?~ "Arbitrary JSON object with extra information."

So far the only reason for having this instance is Value is buried deep in the objects and you might not have the access to wrap it in a newtype. I am okay with adding an instance for this use case, though, so PR's welcome :)

[saurabhnanda]

I might be confused. What's the difference between Value and Object? What would be used to represent a well-formed JSON?

…

On 23 Dec 2016 7:16 pm, "Nickolay Kudasov" ***@***.***> wrote: @saurabhnanda <https://github.com/saurabhnanda> is there a reason you can't use a newtype wrapper around Value? Does it have to be any Value or is it Object really? E.g. we have something like this to be able collect some extra info we haven't added to the API yet: newtype Extra = Extra { getExtra :: Object } deriving (Eq, Show, ToJSON, FromJSON) instance ToSchema Extra where declareNamedSchema _ = pure $ NamedSchema (Just "Extra") $ mempty & type_ .~ SwaggerObject & description ?~ "Arbitrary JSON object with extra information." So far the only reason for having this instance is Value is buried deep in the objects and you might not have the access to wrap it in a newtype. I am okay with adding an instance for this use case, though, so PR's welcome :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#86 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABu0amVmmTLUUb6-yn6Lu20_9suMaSDks5rK9DDgaJpZM4Kevvv> .

[phadej]

Object has an object as the outer constructor, i.s. it's not an array or plain number or string. AFAIK, jsonb can be "just an int", so Value is correct one

[fizruk]

Yes, Object can only be an object (i.e. a map) while Value can also be an array, a string, a number, a boolean or null. In most cases you want Object and not Value. Even if you're storing it in jsonb in PostgreSQL database.

One reason is that it is not clear how to combine two Values (e.g. when an update comes) while it is fairly straightforward to combine two Objects (merge or deep merge).

Another is that if you use Value you're bound to check that it's not a primitive or array before extracting useful information. This makes analysis of this extra data a bit more complex than it should in my opinion.

[saurabhnanda]

For my use-case it should be Object then, not Value. And do we already have a ToSchema instance for Object?

…

On 24 Dec 2016 3:39 am, "Nickolay Kudasov" ***@***.***> wrote: Yes, Object can only be an object (i.e. a map) while Value can also be an array, a string, a number, a boolean or null. In most cases you want Object and not Value. Even if you're storing it in jsonb in PostgreSQL database. One reason is that it is not clear how to combine two Values (e.g. when an update comes) while it is fairly straightforward to combine two Objects (merge or deep merge). Another is that if you use Value you're bound to check that it's not a primitive or array before extracting useful information. This makes analysis of this extra data a bit more complex than it should in my opinion. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#86 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABu0R29AkmHR_a8iawA-26tnxy2_YYMks5rLEaTgaJpZM4Kevvv> .

[fizruk]

@saurabhnanda no, not yet. Object is just a type synonym for HashMap Text Value and since there's no instance for Value there's no instance for Object. But I think it can (and should) be added separately.

It's simple to define one locally for now:

instance ToSchema Object where
  declareNamedSchema _ = pure $ NamedSchema (Just "Object") $ mempty
    & type_ .~ SwaggerObject
    & description ?~ "Arbitrary JSON object."

[qrilka]

@fizruk this instance above doesn't seem to be valid for version 2.2 of the library - is there any workaround?

[fizruk]

@qrilka the instance is valid, but is overlapping with a more general one for HashMap (since Object is a type synonym). You only need to add {-# OVERLAPPING #-} pragma to make it work:

instance {-# OVERLAPPING #-} ToSchema Object where
  declareNamedSchema _ = pure $ NamedSchema (Just "Object") $ mempty
    & type_ .~ SwaggerObject
    & description ?~ "Arbitrary JSON object."

[qrilka]

using your instance above:

λ> import qualified Data.HashMap.Strict as HM
λ> validateToJSON ( HM.fromList [("a", Number 1)] :: Object)
["property \"a\" is found in JSON value, but it is not mentioned in Swagger schema"]
λ> 

[qrilka]

Value could be specified as AnyValue from https://stackoverflow.com/a/43328994/110400 but as far as I understand swagger2 can't support specs with not type specified.

[fizruk]

λ> import qualified Data.HashMap.Strict as HM
λ> validateToJSON ( HM.fromList [("a", Number 1)] :: Object)
["property \"a\" is found in JSON value, but it is not mentioned in Swagger schema"]

Yeah, I see what I did there with "not mentioned" fields.
How bad is it for your particular use case though?

Value could be specified as AnyValue from https://stackoverflow.com/a/43328994/110400

Interesting, I didn't know type is an optional field!
I guess we should update swagger2 to support that.

[qrilka]

As of now we've downgraded to version 2.1.6 but actually this new strictness in validation showed up minor inconsistency in one of our legacy endpoints which actually needs to be resolved.
And as for AnyValue I don't see a need for it in our application.

[fizruk]

I think we can add an instance for Value once #138 is done.