Proposal: remove propertyNames

[SorinGFS]

The keyword propertyNames doesn't fit in json-schema algoritm and IMO should be removed.

Motivation

• This keyword is one of 11 keywords that allow any schemas
• at the same time this keyword is applicable only to the names of properties of an object
• the data that is targeted by this keyword cannot be located in json, notations such as dataLocation cannot be produced
• the previously presented conditions force implementations to check the data type before applying a schema
• the previous problem basically forces implementations to validate almost any schema that is validated by a metaschema, thus annihilating the very existence of this keyword
• by introducing this artificial check for data type before applying a schema on those 11 keywords implementations are basically forced to validate potentially invalid schemas on those keywords too

I searched for the presence of this keyword in 2300 schemes, I found 109 instances of which about half were stupid like type: string, about a quarter were enum or not enum, and the others were pattern. None of those instances were something that could not be replaced by other schemas.

[jdesrosiers]

• the data that is targeted by this keyword cannot be located in json, notations such as dataLocation cannot be produced

I think you mean that you can't reference it with a JSON Pointer. I've noticed this as well and have considered whether that means propertyNames belongs in JSON Schema. I'm not 100% sure, but I am convinced that it provides users with the ability to do things they couldn't without it and to express constraints in a cleaner way that they could without it.

• the previously presented conditions force implementations to check the data type before applying a schema
• the previous problem basically forces implementations to validate almost any schema that is validated by a metaschema, thus annihilating the very existence of this keyword
• by introducing this artificial check for data type before applying a schema on those 11 keywords implementations are basically forced to validate potentially invalid schemas on those keywords too

None of this makes sense to me. I don't understand the problem you're trying to describe. Whatever it is, I don't think I've encountered it. In my implementation, the only issue I encountered was that JSON Pointer can't point to a property name, but that's only a problem for the output format. It doesn't affect the algorithm at all.

[gregsdennis]

JSON Pointer can't point to a property name

(Just for clarity...)

While technically true, it can still indicate a property name given the context that we're looking at property names in the first place.

For example, if I have

{
  "propertyNames": {
    "pattern": "^foo[0-9]+$"
  }
}

with the instance {"bar": true}, I'd get an output object that includes

{
  "evaluationPath": "/propertyNames",
  "instanceLocation": "/bar"
  // ...
}

With these two things, I have the context that I'm looking at property names, so I can infer that bar is a property name that doesn't match the subschema at /propertyNames. It's obvious that it's not looking at the true value.

I see no problem with this.

[SorinGFS]

It's obvious that it's not looking at the true value. I see no problem with this.

I think you created the annotation system for a reason. And I think you expected that annotations to be able to provide programmatic access to those references for things like code generators. How would be this goal accomplished having exceptions?

[SorinGFS]

... continuation

basically the same reference for dataLocation would be shared by 2 purposes, in order to be used by a program would require some extra tests to "detect" what you meant by that reference. All these problems (a check for data instance of object in validators, and the checks to "detect" for what is that data reference) are created by this propertyNames keyword which is the only keyword that doesn't work like all the others.

[SorinGFS]

but I am convinced that it provides users with the ability to do things they couldn't without it and to express constraints in a cleaner way that they could without it.

In 2300 schema files from schemastore I couldn't find anything like that. Of course, it also depends on what you mean by clean, of course propertyNames is the cleanest, only that it allows even simple errors, and from my point of view the following are quite clean:

for allowing exact names or patterns (with desired pattern instead of this in example):

{
  "$id": "https://json-schema.hyperjump.io/schema",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type":"object",
  "patternProperties": {"^(foo|bar)$": true},
  "additionalProperties": false
}

Note: allowing property names without defining a schema for the values is another non-sense IMO, the proof of that is the rare use of this propertyNames keyword.

for deniying names:

{
  "$id": "https://json-schema.hyperjump.io/schema",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type":"object",
  "not": {"anyOf": [ {"required": ["foo"]}, {"required": ["bar"]}]}
}

Whatever it is, I don't think I've encountered it. In my implementation

Now take a look at this schema, I used your implementation, but I'm sure would produce the same result with any implementation due to the reasons I presented regarding the algorithm:

{
  "$id": "https://json-schema.hyperjump.io/schema",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type":"object",
  "propertyNames": {"propertyNames":{"type":"boolean"}},
  "allOf": [{"propertyNames": {"propertyNames":{"type":"boolean"}}}]
}

A non-sense schema like this is perfectly valid and would validate any object. And this is just a quick example, basically any schema valid against metaschema would validate the object. In fact this is a broader problem in json-schema (the lack of restriction for those 11 keywords) which is not visible because the metaschema is correct, but schema authors are not as knowledgeable as you are.

the only issue I encountered was that JSON Pointer can't point to a property name, but that's only a problem for the output format. It doesn't affect the algorithm at all.

Without this "small" issue the algorithm would work without checking for data instanceof Object on those 11 keywords. To me this looks like workaround to fix this problem, not the solution. The problem commes from the "wildcard" power of this keyword which like items or additionalProperties or any of those 11 keywords are unrestricted about what they can contain. Using this propertyNames keyword with a wrong schema in it (and because the lack of restrictions in metaschema the probability of error is high) would validate the object, while using solutions like ones I showed at the top would always produce any desired outcome.

[SorinGFS]

I do know that I didn't have the problems implementing propertyNames that you are having. It fits perfectly fine into my architecture without any workarounds or hacks.

First, basically I do not have a problem in understanding propertyNames or including it into my implementation. In the early days I had it inside, as I described in this document. Then, I realized that by introducing that artificial type check on additionalProperties, items, so on... basically I validate something that isn't in the schema! So, if the schema doesn't say type: object why would I perform those checks on additionalProperties, items, so on... only if data is an object? This way, I would allow the schema author not to write that type: object into the schema and still do the expected validation for him.
By doing my implementation I understood few things:

• the implementation should not perform things that are not written in the schema
• there is an algorithm, and many of its parts are already represented by keywords. I'm trying to identify all its parts, I think is finite, simple, and when all its parts will have the corresponding keyword basically that would be what I think json-schema should be, as language or standard. Any extension to that would be possible to be made by using those basic parts of the algorithm. I will not enter off topic here, but I will open a new discussion when I'll be prepared for that. For now that is a work in progress.
• the annotation locations are uri's visited by the parser and just by having dataLocation and schemaLocation we should be able to know what operation happened there. The keyword propertyNames is the only keyword that cannot produce unique dataLocation uri's. This is because the keyword definition for propertyNames is a wildcard, can be anything, so when the parser is entering this keyword it can't produce a unique dataLocation uri, but instead it would overwrite the result of the previous rule. Plus, the overall result of schema validation for that dataLocation would overwrite whatever was written for propertyNames. This lead us to annotate multiple records on behalf of a single dataLocation, but the problem with this is that... it can't be written in a tree structure like my implementation where annotation system is native. Suddenly I had an idea how to make you understand where the problem is, and I used your implementation for that:

schema:

{
  "$id": "https://json-schema.hyperjump.io/schema",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "propertyNames": { "pattern": "^(foo|bar|baz|moo|boo|bim|doo)$" }
}

data:

{"foo":{},"fooo":{},"bar":{},"baz":{}}

the result:

• Invalid
  • fails schema constraint https://json-schema.hyperjump.io/schema#/propertyNames

The question is: which one? 😄
Now, if you will try to fix this and give the right annotation in order to be used for debug or programmatic use you will be able to see what I meant about unique dataLocation in annotations.

[gregsdennis]

I think I see what you're trying to say here.

Let's look at this schema

{
  "type": "array",
  "items": {
    "type": "object",
    "propertyNames": { "enum": [ "foo", "bar", "baz" ] }
  }
}

and this instance

[
  { "foo": 1 },
  { "disallowed": 2 },
  { "bar": 3 },
  { "baz": 4 },
]

My implementation (what's currently deployed to https://json-everything.net/json-schema) produces this output unit (among others):

{
  "valid": false,
  "evaluationPath": "/items",
  "schemaLocation": "https://json-everything.net/3cce902220#/items",
  "instanceLocation": "/1",
  "details": [
    {
      "valid": false,
      "evaluationPath": "/items/propertyNames",
      "schemaLocation": "https://json-everything.net/3cce902220#/items/propertyNames",
      "instanceLocation": "/1/disallowed",
      "errors": {
        "enum": "Value should match one of the values specified by the enum"
      }
    }
  ]
}

I think what you're saying is that the first output unit inadequately describes the problem that propertyNames failed and which properties it failed on.

I counter this argument by inferring that propertyNames failed on the "disallowed" property because of the information in the detail output unit. Granted, the instanceLocation (not dataLocation) isn't technically correct here because the subschema at /items/propertyNames isn't validating the instance value at /1/disallowed but rather the property name "disallowed". However, I chose this approach because the inference of having propertyNames in schemaLocation/evaluationPath gives us the context that we're looking at property names, not values.

That said, an error message in the outer output unit could make things a little clearer:

{
  "valid": false,
  "evaluationPath": "/items",
  "schemaLocation": "https://json-everything.net/3cce902220#/items",
  "instanceLocation": "/1",
  "errors": {
    "propertyNames": "Properties [\"disallowed\"] failed validation"
  },
  "details": [
    {
      "valid": false,
      "evaluationPath": "/items/propertyNames",
      "schemaLocation": "https://json-everything.net/3cce902220#/items/propertyNames",
      "instanceLocation": "/1/disallowed",
      "errors": {
        "enum": "Value should match one of the values specified by the enum"
      }
    }
  ]
}

But error messaging is not specified by the output (on purpose). (How to include an error message is specified, but not the messages themselves or even what keywords should generate them.)

I'm interested to know if you have an alternate solution to this problem.

---

As far as not fitting into "the algorithm", I'm not sure that that can be quantified. JSON Schema doesn't define an algorithm. And it avoids doing so on purpose. It defines behaviors: output for a given input. How an implementation gets there is up to the implementer.

It's intentionally permissive to allow you to determine what the best design choices are for your consumers.

I can't see that JSON Schema will ever specify an algorithm because the project values this freedom for the implementers.

[SorinGFS]

I'm interested to know if you have an alternate solution to this problem.

Therein lies the problem: there is no straight forward solution. And this keyword is the only one with this problem. An implementation, depending on proccessing order may even validate an object[key] before failing to validate the key, therefore leading to a greater confusion when would produce different validation results for the same instanceLocation (as you call it). Any other keyword by instanceLocation will mean the value of that key, while propertyNames means the key (by recursing over object keys one by one). That's why I said that propertyNames doesn't fit in the same algorithm as all the other keywords. A schema can be a boolean (not the case) or an object. A proper algorithm for propertyNames would have the json objects represented as nested arrays with two elements like this:

[ "foo", [ "bar", [ "baz", 3 ] ] ]

where accessing arr[1][1][0] we retrieve the object's propertyName and by accessing arr[1][1][1] we retrieve the object's propertyValue. That algorithm would provide unique paths for all the keys and all the values. The json-schema algorithm provides unique paths only for the values.

To overcome this problem every implementation in it's own programming language must solve this in its own way, but while in C# you will not feel the performance impact since a .dll or .so works I don't know, 20, 50 times faster the others will feel any unneccessary added thing. The performance impact for dynamicRef, or for unevaluated* keywords are IMO justified, but not for propertyNames.

An important detail is the following: the instanceLocation produced in annotation is (IMO) not important to be understandable for a human eye, but for a programming language in order to use it for example to indicate in an interface where the problem is, or similar things.

As far as not fitting into "the algorithm", I'm not sure that that can be quantified. JSON Schema doesn't define an algorithm. And it avoids doing so on purpose. It defines behaviors: output for a given input. How an implementation gets there is up to the implementer.
It's intentionally permissive to allow you to determine what the best design choices are for your consumers.
I can't see that JSON Schema will ever specify an algorithm because the project values this freedom for the implementers.

I think this is a discussion that should exist, not to limit the freedom for the implementers but quite the oposite of that. I think if json-schema would be seen as an algorithm in which keywords are the lexical representation of a concern in the algorithm and in which every part of the algorithm is represented by a stable keyword, then that would be where json-schema ends and implementation is starting. For example, let's consider the keyword allOf, as part of the algorithm is an array with at least one positional element (prefixItems). As part of an implementation vocabulary can mean different things: implementation A may say validate all the items, implementation B may say iterate all the items and print them in the console, each implementation would have their own meta schemas based on json-schema algorithm, where they can decide which keywords are using in that specific vocabulary, and it will be their own responsability to document the specifications of their project. When users would choose a meta schema url they will search for the corresponding documentation there. I just wanted to give a basic idea here, I don't want to bring this off topic, as I said to Jason I will bring the full vision of this when time arives.

[jdesrosiers]

Now, if you will try to fix this and give the right annotation in order to be used for debug or programmatic use you will be able to see what I meant about unique dataLocation in annotations.

I understand that part. I agree that's a problem. I acknowledged it from the beginning of the discussion. The part I don't understand is the consequences you claim that has on implementing JSON Schema. The only consequence I see is with the output format which can't precisely report errors/annotations for this keyword because it relies on JSON Pointer to identify the location of the error/annotation. I've acknowledged that maybe that's an indication that propertyNames doesn't belong. What I don't understand is how that can have the impact on implementation that you're describing. I personally see no impact at all on implementation. The only impact is in reporting. So, I'd rather explore if we can solve the reporting issue before considering removing the keyword.

An important detail is the following: the instanceLocation produced in annotation is (IMO) not important to be understandable for a human eye, but for a programming language in order to use it for example to indicate in an interface where the problem is, or similar things.

I want to also acknowledge that I agree with this point. But, again, I'd like to first try to solve this as an issue with the output format before considering the much more extreme solution of removing the keyword.

[SorinGFS]

Ok.

[SorinGFS]

@ALL

what I saw in schemastore schemas people are using much more often the following instead of propertyNames:

properties: {
    foo: {},
    bar: {},
    baz: false
}

The intent is even more clearer like that, and for the pattern cases there is patternProperties

[gregsdennis]

(Your question has no bearing on the text you quoted.)

It's neither. It's a standardized declarative syntax that allows people to define constraints for JSON data.

If your argument is that propertyNames doesn't "fit the algorithm", then I think you have a fundamental misunderstanding of how JSON Schema works, which I and others have tried to rectify (unsuccessfully, it seems).

[SorinGFS]

When telling people about propertyNames, their response is generally, "Thanks! That's exactly what I needed."

When you give me that as an argument for the existence of the keyword, I am speechless, rest my case, no further questions!

But you don't limit yourself to that: you also unilaterally decide to close the discussion (it's not the first time), and I wouldn't be surprised if you hide or even delete my comments! Again, it wouldn't be the first time.
It's convenient, isn't it, when something doesn't suit us we delete it and behave as if it didn't exist :))

I noticed a massive "purification" of the discussions from the past, as if the discussions of the last months never took place!

If you think this dicatorial decision mechanism is beneficial for the future json-schema... I don't know what else I could say...

[gregsdennis]

I wouldn't be surprised if you hide or even delete my comments

I haven't hidden anything. In the past, you've taken discussions off-topic, but you've remained on topic here.

you also unilaterally decide to close the discussion

I (as a maintainer of the project) see no reason to remove a feature that (1) is doing no harm and (2) is actually useful. As such, the proposal to remove it is being rejected. The discussion is concluded, and someone needs to close it, be it Jason, myself, or any of the other maintainers of the project.

As I mentioned, I didn't lock the conversation, so you're welcome to continue providing evidence that your proposal should be reconsidered, but for now, the matter is decided.

I noticed a massive "purification" of the discussions from the past, as if the discussions of the last months never took place!

I (as a maintainer of the project) have recently been performing some house cleaning. I have not deleted or hidden any issues, discussions, or comments on them. They're all still available. What I have done is update how we're organizing issues in the spec repo so that we can better track multiple lines of work.

Over a month ago I mentioned in Slack that I was planning on doing this, and then I created an issue in the spec repo to record my findings and make an official proposal. Reception to my proposal was good, so I carried it out today.

I can understand that such a change can be disruptive, but (to be frank) it's a listing of the work we need to do, and we are the ones that have to manage it.

[gregsdennis]

you also unilaterally decide to close the discussion

Yes. @SorinGFS you are correct here, and I apologize. I should have called for a vote to close it.

I feel it's a bit awkward to reopen this only to call for a vote to close it. Would you be satisfied with a promise not to act unilaterally in the future?

[SorinGFS]

Would you be satisfied with a promise not to act unilaterally in the future?

Yes, sure.

[gregsdennis]

To me, a conversation about removing any keyword needs to consider both its longevity and how complete its definition is.

propertyNames is a long-standing and well-understood keyword, even if newer users just don't know it's there. Its inclusion in the specification has not caused any problems or confusion for users or implementers. (@SorinGFS you're the first that I've seen complain about this keyword.)

Given that, I don't think the arguments presented warrant removal from the specification. I'm going to close this discussion, but it will remain unlocked.