Upcoming APIs for Custom Schemas

[Oudwins]

Hey everyone.

I'm working on some stuff to allow anyone to create custom schemas. This might be a while still until all the APIs have been released. But I wanted to leave my thoughts here in case anyone wants to contribute theirs.

Currently my thinking is that we will have 3 APIs for 3 different types of Custom Schemas:

1. Custom Primitive types -> i.e Environment type for "prod", "dev" etc
2. Fully custom schema where you define everything through an interface
3. a CustomAs() schema where you define some kind of get and set methods and then Zog can treat the schema as another zog schema.

Let me give examples of each:

Custom Primtives

This will ship soon. The API looks like this:

// definition in your code
type Env string
const (
  Prod Env = "prod".
  Dev Env = "env"
)
func EnvSchema() *StringSchema[Env] {
 s := &z.StringSchema[Env]
  return s.OneOf([]Env{Prod, Dev}) // you can also just return the schema and define the tests when calling it it doesn't matter
}
// usage
type S struct {
  Environment Env
}
schema := z.Struct(
z.Schema{
   "Environment": EnvSchema() // All string methods will now be typed to Env type
 }
)

Fully Custom Schemas

This is not yet ready but the general idea (All credit goes to Jesus for this idea) is that you will implement an interface and create the schema like so

// this type must implement a specific zog interface
func MyCustomSchema() MyCustomSchemaType {
 /// do your stuff here
}

schema := z.Struct(
 z.Schema{
   "Custom": z.Custom(MyCustomSchema())
 }
)

CustomAs schemas

If anyone has a better name for this please let me know (also I have thought 0 about the exact API)! The use case here is that you have an interface or a struct or something that is not one of the built in zog schemas but it can be represented as it. For example lets say we have a byte slice that is really a string.

// definition
func ByteString() .... {
 return z.CustomAs(z.Def{
   GET: // fn to get the value,
   SET: // fn to set the value
 }).String()
}

// usage
type S struct {
 MyByteString []byte
}

schema := z.Struct(z.Schema{
  "MyByteString": ByteString().Contains("byte").... // you can use all the string methods as normal
})

[absolutejam]

I haven't fully looked at all of the internal implementations of the schemas, but maybe a 'schema' needs to be distilled into interface(s) so that any type can implement them.

type Schema[T any] interface {
  ValidatableSchema[T]
  ParseableSchema[T]
}

// NOTE: Maybe make the names less generic so that they don't clash with existing methods?

type ValidatableSchema[T any] interface {
    Validate(data *T, options ...ExecOption) ZogIssueList
}

type ParseableSchema[T any] interface {
    Parse(data any, dest *T, options ...ExecOption) ZogIssueList
}

Then this could be leveraged by custom types:

// Example 'newtype'/wrapped type
type UserID struct { id uuid.UUID }
func (id UserID) ID() { return id }
func (id UserID) String() { return id.id.String() }

type UserIDSchema struct {}

// Validate implements ValidatableSchema
func (id UserIDSchema) Validate(data *UserID, options ...z.ExecOption) ZogIssueList {
    // I don't actually know what this looks like but I assume there can be some
    // helper methods
}

// Parse implements ParseableSchema
func (id UserIDSchema) Validate(data *UserID, options ...z.ExecOption) ZogIssueList {
     // TODO:
}

And potentially, you could add some helper methods for when the type's schema is static (eg. UUID, email):

type SchemaResolver[T any] interface {
    ResolveSchema() Schema[T]
}

type CreateUserCommand struct {
  ID UserID `json:"userId"`
}

var CreateUserCommandSchema = z.Struct(z.Schema{
  "id": z.SchemaFor[UserID](),
})

// ResolveSchema implements SchemaResolver[UserID]
func (id UserID) ResolveSchema() Schema[UserID] {
    return &UserIDSchema{}
}

// and z.Custom's signature could be something like...
func Custom[T SchemaResolver[T]]() Schema[T]() {
    var t T
    // maybe use reflection to check that t isn't nil (ie. if T was an interface)
    return t.Schema()
}

Also maybe a simple transformer for newtypes/wrapped types, eg.

// Zog helper function
func Convert[T any, U any](t T, convert func(t T) U) Schema[U] { ... }

// Usage
z.Convert(userID, func(id UserID) string  {
    return id.String()
}).Required().Min(...)
// ^- It's now a string schema acting against a string

[Oudwins]

@absolutejam This is an interesting approach. Its a little different from how Zog works at the moment since this is putting the validation logic in the custom type rather than in the schema. But it is interesting. I'll have to think about it.

I have thought about this problem a lot more and come to realize that there are 4 things I would like to support:

1. Custom primitive types -> already supported (except time.Time).
2. Configurable schemas that are built by third parties (i.e zextras.Decimal().Min(0))
3. Very simple manual validation schemas for one off cases -> already supported by z.Custom().
4. Custom types as another type such that I as a user don't have to write all the tests myself. For example validating the decimal.SQLValuer type.

You first proposal is an alternative approach for 2/3. Wouldn't work very well for 2 though so I guess I'm interested in the benefits you see for this approach over the existing z.Custom().

The second approach is similar to what I outlined above z.CustomAs(). The issue here is that with how you proposed string's default and catch could not work as we don't have a function to convert back from a string into your custom type.

I also thought about something like

z.Proyection(func (id UserId) string {
 return id.String()
}, z.String().Required().Min(1)....)

In which case its a little more clear that default and catch won't work. But you can still call them so I think its not good.

For goal 2 the API I like the most atm is

z.Use()
//For example 
z.Use(zextras.UUID().NotEmpty().TestFunc(func(val *uuid.UUID, ctx z.Ctx) bool {
 // call to validate
})

It would be nicer if you didn't have to wrap it. But then we would have to expose all the methods that make up the Zog Schema Interface such that you could be doing something like

 z.String().Min(1).InternalParsingMethod() // you get autocomplete for this and you can call it which isn't great. 

So its basically have z.Use(schema) or make the Zog schema interface have the methods defined something like this:

type ZogSchema interface {
 ZInternalParse()
 ZInternalValidate()
}