unordered (v5 proposal) - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.



Proposed keywords

  • unordered

Purpose

There are many situations (e.g. lists of tags) where the order of the entries does not matter - and in fact, should not be relied upon.

This would be a non-validatable keyword - it would supply meta-data to tools (similar to title or description), informing them that any tool processing this data format array can be expected to ignore the ordering of the items.

To create something like a "set", unordered could be combined with uniqueItems. On its own, it unordered specifies that ordering doesn't matter.

Values

The value of unordered would be a boolean. It has no default value if unspecified - in the such cases, tools should probably assume that ordering matters (to be on the safe side).

Example

Tag set (unordered and uniqueItems)
{
    "type": "object",
    "properties": {
        "tags": {
            "type": "array",
            "unordered": true,
            "uniqueItems": true,
            "items": {"$ref": "#/definitions/tag"}
        }
    },
    "definitions": {
        "tag": {
            "type": "string",
            "links": [{
                "rel": "full",
                "href": {
                    "template": "/tags/{tagName}",
                    "vars": {"tagName": "0"}
                }
            }]
        }
    }
}
Item list for automated checkout (unordered only)

The order in which items are scanned should have no effect on later processing. However, duplicate items are allowed.

{
    "type": "array",
    "unordered": true,
    "items": {"$ref": "#/definitions/ean13"},
    "definitions": {
        "ean13": {
            "type": "string",
            "pattern": "^[0-9]*$",
            "minLength": 13,
            "maxLength": 13
        }
    }
}

Concerns

This is presumably in the hyper-schema part of the spec - it's not a validation concern, and is mostly about whether the item order is expected to matter to another party processing the data.

This would have no effect on value comparison (for things like "enum").

Multiple schemas can specify multiple values - if one schema declares that ordering doesn't matter, and another declares that it does, then tools should probably assume that ordering does matter (to be on the safe side).