possible issue with metadata metaschema

[petrelharp]

I encountered this trying to debug the SLiM metadata schema; here is a simplified version. Consider:

import tskit
import json

sms = json.loads("""
{
 "codec": "json",
 "description": "SLiM schema for binary top-level metadata.",
 "properties": {
  "mutation_list": {
   "index": 1,
   "items": {
    "additionalProperties": false,
    "properties": {
     "index": 1
    },
    "type": "object"
   },
   "type": "array"
  }
 },
 "required": ["mutation_list"],
 "type": "object"
}
""")

tskit.metadata.StructCodecSchemaValidator.check_schema(sms)

If I run this code (I'm on #3306 but I don't think that matters), I get the following:

Traceback (most recent call last):
  File "/home/peter/debug/SLiM/jsonblob/mstest.py", line 43, in <module>
    tskit.metadata.StructCodecSchemaValidator.check_schema(sms)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^
  File "/home/peter/projects/tskit-dev/tsvenv/lib/python3.13/site-packages/jsonschema/validators.py", line 317, in check_schema
    raise exceptions.SchemaError.create_from(error)
jsonschema.exceptions.SchemaError: 1 is not of type 'object', 'boolean'

Failed validating 'type' in metaschema['properties']['properties']['additionalProperties']['properties']['items']['properties']['properties']['additionalProperties']:
    {'$schema': 'http://json-schema.org/draft-07/schema#',
     '$id': 'http://json-schema.org/draft-07/schema#',
     'title': 'Core schema meta-schema',
     'definitions': {'schemaArray': {'type': 'array',
                                     'minItems': 1,
                                     'items': {'$ref': '#/definitions/root'}},
                     'nonNegativeInteger': {'type': 'integer',
                                            'minimum': 0},
                     'nonNegativeIntegerDefault0': {'allOf': [{'$ref': '#/definitions/nonNegativeInteger'},
                                                              {'default': 0}]},
                     'simpleTypes': {'enum': ['array',
                                              'boolean',
                                              'integer',
                                              'null',
                                              'number',
                                              'object',
                                              'string']},
                     'stringArray': {'type': 'array',
                                     'items': {'type': 'string'},
                                     'uniqueItems': True,
                                     'default': []}},
     'type': ['object', 'boolean'],
     'properties': {'$id': {'type': 'string', 'format': 'uri-reference'},
                    '$schema': {'type': 'string', 'format': 'uri'},
                    '$ref': {'type': 'string', 'format': 'uri-reference'},
                    '$comment': {'type': 'string'},
                    'title': {'type': 'string'},
                    'description': {'type': 'string'},
                    'default': True,
                    'readOnly': {'type': 'boolean', 'default': False},
                    'examples': {'type': 'array', 'items': True},
                    'multipleOf': {'type': 'number', 'exclusiveMinimum': 0},
                    'maximum': {'type': 'number'},
                    'exclusiveMaximum': {'type': 'number'},
                    'minimum': {'type': 'number'},
                    'exclusiveMinimum': {'type': 'number'},
                    'maxLength': {'$ref': '#/definitions/nonNegativeInteger'},
                    'minLength': {'$ref': '#/definitions/nonNegativeIntegerDefault0'},
                    'pattern': {'type': 'string', 'format': 'regex'},
                    'additionalItems': {'$ref': '#/definitions/root'},
                    'items': {'$ref': '#/definitions/root'},
                    'maxItems': {'$ref': '#/definitions/nonNegativeInteger'},
                    'minItems': {'$ref': '#/definitions/nonNegativeIntegerDefault0'},
                    'uniqueItems': {'type': 'boolean', 'default': False},
                    'contains': {'$ref': '#/definitions/root'},
                    'maxProperties': {'$ref': '#/definitions/nonNegativeInteger'},
                    'minProperties': {'$ref': '#/definitions/nonNegativeIntegerDefault0'},
                    'required': {'$ref': '#/definitions/stringArray'},
                    'additionalProperties': {'$ref': '#/definitions/root'},
                    'definitions': {'type': 'object',
                                    'additionalProperties': {'$ref': '#/definitions/root'},
                                    'default': {}},
                    'properties': {'type': 'object',
                                   'additionalProperties': {'$ref': '#/definitions/root'},
                                   'default': {}},
                    'patternProperties': {'type': 'object',
                                          'additionalProperties': {'$ref': '#/definitions/root'},
                                          'propertyNames': {'format': 'regex'},
                                          'default': {}},
                    'dependencies': {'type': 'object',
                                     'additionalProperties': {'anyOf': [{'$ref': '#/definitions/root'},
                                                                        {'$ref': '#/definitions/stringArray'}]}},
                    'propertyNames': {'$ref': '#/definitions/root'},
                    'const': True,
                    'enum': {'type': 'array', 'items': True},
                    'type': {'$ref': '#/definitions/simpleTypes'},
                    'format': {'type': 'string'},
                    'contentMediaType': {'type': 'string'},
                    'contentEncoding': {'type': 'string'},
                    'if': {'$ref': '#/definitions/root'},
                    'then': {'$ref': '#/definitions/root'},
                    'else': {'$ref': '#/definitions/root'},
                    'allOf': {'$ref': '#/definitions/schemaArray'},
                    'anyOf': {'$ref': '#/definitions/schemaArray'},
                    'oneOf': {'$ref': '#/definitions/schemaArray'},
                    'not': {'$ref': '#/definitions/root'},
                    'binaryFormat': {'type': 'string',
                                     'pattern': '^([cbB\\?hHiIlLqQfd]|\\d*[spx])$'},
                    'arrayLengthFormat': {'type': 'string',
                                          'pattern': '^[BHILQ]$',
                                          'default': 'L'},
                    'index': {'type': 'number'},
                    'stringEncoding': {'type': 'string',
                                       'default': 'utf-8'},
                    'nullTerminated': {'type': 'boolean'},
                    'noLengthEncodingExhaustBuffer': {'type': 'boolean'},
                    'length': {'type': 'integer'}},
     'default': True}

On schema['properties']['mutation_list']['items']['properties']['index']:
    1

This is confusing because the metaschema specifies that index should be 'type': 'number', and I can't see where the error

jsonschema.exceptions.SchemaError: 1 is not of type 'object', 'boolean'

could possibly come from.

So, basically, I have no idea what's going on here?

[petrelharp]

Okay now I know the problem: this schema is bad because we shouldn't have this in properties:

     "index": 1

... since that's not a property! A property description has, like, stuff about the thing, not a number! And that's exactly what the metaschema was telling me. I just didn't get it. =)

[hyanwong]

Should we have better error messages. Or examples that AI tools can mine to understand the general point?

[petrelharp]

Should we have better error messages.

Well at first I thought this was just such a case. But the underlying problem here was basically that I was just in "run it; see if it works" mode and did not think hard about it. We'd want an error message that says "this can't be an integer, it has to be one of these other things"... which is exactly what the error message says.

Or examples that AI tools can mine to understand the general point?

Like for instance our brains? Yes, that would help a lot. However, given the number of people who need to ever construct these things, I don't think it's high priority.