vanilla / garden-schema Goto Github PK

This will help with stuff coming from the database and will end up implementing 99% of what array types offer.

This is an epic to track features/changes required for version 2 of the library.

The validationClass property of Schema allows instances of Validation to be created through cloning. This is not flexible so I propose we allow the Schema to take a factory function or interface for creating validation instances.

If we go the interface route we should use a naming convention similar to PSR-17.

The validation object does not contain actual values when giving validation errors which can be a bad UX in some instances. I propose we add values to the validation object if they are simple scalar values.

@DaazKu commented on Mon Aug 14 2017

Calling http://vanilla.dev/api/v2/comments?discussionid=30 yields:

[
    {
        "commentID": 7,
        "discussionID": 30,
        "body": "<p>comment 1</p>\n",
        "format": "Markdown",
        "dateInserted": "2017-07-27T19:26:24+00:00",
        "insertUserID": 2,
        "url": "http://vanilla.dev/discussion/comment/7#Comment_7"
    },
    {
        "commentID": 8,
        "discussionID": 30,
        "body": "<p>comment 2</p>\n",
        "format": "Markdown",
        "dateInserted": "2017-07-27T19:26:28+00:00",
        "insertUserID": 2,
        "url": "http://vanilla.dev/discussion/comment/8#Comment_8"
    },
    {
        "commentID": 9,
        "discussionID": 30,
        "body": "<p>comment 3</p>\n",
        "format": "Markdown",
        "dateInserted": "2017-07-27T19:26:33+00:00",
        "insertUserID": 2,
        "url": "http://vanilla.dev/discussion/comment/9#Comment_9"
    },
    {
        "commentID": 12,
        "discussionID": 30,
        "body": "<p>asd</p>\n",
        "format": "Markdown",
        "dateInserted": "2017-08-14T14:42:58+00:00",
        "insertUserID": 2,
        "url": "http://vanilla.dev/discussion/comment/12#Comment_12"
    }
]

You get an error using the dateInserted field as the after parameter like so http://vanilla.dev/api/v2/comments?discussionid=30&after=2017-07-27T19:26:24+00:00

{
    "message": "after is not a valid datetime.",
    "status": 422,
    "errors": [
        {
            "field": "after",
            "code": "invalid",
            "message": "after is not a valid datetime."
        }
    ]
}

This is counter intuitive because the return type of dateInserted is DateTime... It should work properly

Some kind of support should be added for CSV fields. A CSV int field might support "3,4,5" as a valid value and convert it into an array of three integers: 3, 4 and 5.

The details of the feature need to be spec'd out before development.

I have data with colons in property name, and currently it's always cause error.

Right now, arrays are valid if they contain the zero key. If it is out of order or there are missing/invalid other keys then the schema will clean the output, but that may not be the desired result. Similar to the extra property flags we should add the following flags to the Schema class:

/**
 * Trigger a notice when an array has invalid keys.
 */
const VALIDATE_ARRAY_KEY_NOTICE = 0x4;

/**
 * Throw a ValidationException an array has invalid keys.
 */
const VALIDATE_ARRAY_KEY_EXCEPTION = 0x8;

Currently if we want to create a subset of a schema, given the following schema:

    /**
     * Get a schema instance comprised of all available comment fields.
     *
     * @return Schema Returns a schema object.
     */
    protected function fullSchema() {
        return Schema::parse([
            'commentID:i' => 'The ID of the comment.',
            'discussionID:i' => 'The ID of the discussion.',
            'body:s' => 'The body of the comment.',
            'format:s' => 'The output format of the comment.',
            'dateInserted:dt' => 'When the comment was created.',
            'insertUserID:i' => 'The user that created the comment.',
            'insertUser?' => $this->getUserFragmentSchema(),
            'url:s?' => 'The full URL to the comment.'
        ]);
    }

We have to do:

$this->schema(['commentID', 'discussionID', 'body', 'format'], 'out')->add($this->fullSchema());

This is counter intuitive. Expected result from reading the code would be the fullSchema.
I propose that we create the subSet() function instead.

$this->fullSchema()->subset(['commentID', 'discussionID', 'body', 'format']); 

This is clearer than its counterpart.

Then we should have a fill() utility method that does what add($data, false) does and add() should be refactored to drop $addProperries and have it always add missing properties.

TL;DR;
Create subset() and fill() and make add() only add missing properties.

This does not work:

$schema = Schema::parse([
    'letter' => Schema::parse([
        'description' => 'A letter',
        'default' => 'a',
        'items' => [
            'enum' => ['a', 'b', 'c'],
            'type' => 'string'
        ],
        'style' => 'form',
        'type' => 'string',
    ])
]);
$data = [];
$data = $schema->validate($data);
// $data should be ['letter' => 'a']

This does:

$schema = Schema::parse([
    'letter' => [
        'description' => 'A letter',
        'default' => 'a',
        'items' => [
            'enum' => ['a', 'b', 'c'],
            'type' => 'string'
        ],
        'style' => 'form',
        'type' => 'string',
    ]
]);
$data = [];
$data = $schema->validate($data);
// $data should be ['letter' => 'a']

Currently, we separate fields with "." when adding filters/validators and when representing field nesting in Validation objects. This provides problems when fields have dots in them since we have no escaping. I am recommending we follow the JSON ref spec and use "/" instead.

• JSON ref uses "/" and escapes it with "1" and escapes "" with "~0".
• If we want to make this version use deprecations we can just say that a field with dots will throw a deprecation warning and treat it as slashes in addValidator and addFilter`. A mix of dots and slashes should be interpreted as the new style though. Perhaps this allows fields with dots to use a leading slash to start.

We want to be able to add customer filters that can change data before it is validated.

A big part of Open API is using $ref references for code reuse. This is something we should support, but is a bit tricky in a narrowly scoped class like Schema. Here is what I propose:

• Create a schemaContainer property that can take a string from $ref and return a Schema instance.
• This property will be used to resolve $ref fields when encountered during validation or instantiation.

Right now you can add a validator by specifying the path to a field. Let's add the following wildcards.

• path.to.field.* will call the callback on any field under path.to.field.
• .* will call the callback on any property under the root. (might need to be *)
• * will call the callback on every field, period. (might need to be **)