Object properties defined by enum

[etinquis]

Is is possible to restrict object properties (/property names) to values of an enum, and/or define the set of required properties based on an enum?

For example, say I want to define a schema to validate a localization file format such as

{
  "en": {
    "my_string_1": "My String 1",
    "my_string_2": "My String 2"
  },
  "fr": {
    "my_string_1": "My String 1",
    "my_string_2": "My String 2"
  }
}

I have enums defined for both locale and translation tag, and I want to define schemas that are able to both restrict properties to the values defined in the enum and (ideally seperately) require that all those properties are present.

Essentially, something equivalent to

{
  "type": "object",
  "properties": {
    "en": {
       "type": "object",
       "properties": {
          "my_string_1": { ... },
          ...
       },
       "required": ["my_string_1", ...],
       "additionalProperties": false
    },
    ...
  },
  "additionalProperties": false
  "required": ["en", ...]
}

using $refs to the enums and without having to duplicate the enum values into the properties/required lists.

[gregsdennis]

I think I understand what you're wanting. Please let me know if I've missed something.

The first keyword you're looking for is propertyNames. This keyword defines a schema that applies to the property names of instance objects. (Naturally, it only makes sense for that schema to apply to solely to string instances.)

{
  "type": "object",
  "propertyNames": {
    "enum": [ "en", "fr", /* ... */ ]
  },
  // ...
}

You're already using the second keyword you need: additionalProperties. However, you need to supply the schema for your property here.

{
  "type": "object",
  "propertyNames": {
    "enum": [ "en", "fr", /* ... */ ]
  },
  "additionalProperties": {
     "type": "object",
     "properties": {
        "my_string_1": { /* ... */ },
        // ...
     },
     "required": ["my_string_1", /* ... */ ],
     "additionalProperties": false
  },
  // ...
}

The last piece you mentioned was requiring that all of the properties are present. For this, I'd just use minProperties and maxProperties to exactly specify the number of items in the enum.

{
  "type": "object",
  "propertyNames": {
    "enum": [ "en", "fr", /* ... */ ]
  },
  "additionalProperties": {
     "type": "object",
     "properties": {
        "my_string_1": { /* ... */ },
        // ...
     },
     "required": ["my_string_1", /* ... */ ],
     "additionalProperties": false
  },
  "minProperties": 5, // needs to match the length of /propertyNames/enum
  "maxProperties": 5, // needs to match the length of /propertyNames/enum
  // ...
}

Unfortunately right now we don't have a way to have minProperties or maxProperties "extract" their values from the length of the enum. You'll need to keep them in sync manually.

This will allow you to

• control the languages in the enum
• specify that all enums are the same value
• limit the object to only supported languages

[etinquis]

Thanks for the response. I think I buried the lede a bit. What I'm looking for would be something more like (ignoring the second level of string tags for simplicity's sake):

{
  "type": "object",
  "propertyNames": {
     "$ref": "/locales.json"
  },
  "required": {
    "$ref": "/locales.json"
  }
}

I specifically don't want to inline the enum values (or update min/max based on the counts), as they're already defined and maintained in a separate enum and I'm using/referencing them in multiple places.

[gregsdennis]

$ref can only point to schemas, not arbitrary data.

For this you'll need something like my data keyword: https://docs.json-everything.net/schema/vocabs/data-2023/

Example: https://docs.json-everything.net/schema/examples/external-ref/

It's only implemented in .net, though. Still haven't found anyone who's built it for anything else.

[etinquis]

In my case, /locales.json would be a valid ref to an enum schema, e.g.

{
    "$id": "/locales.json",
    "title": "Locale",
    "enum": ["en", "fr"]
}

and /translation-slug.json

{
    "$id": "/translation-slug.json",
    "title": "TranslationSlug",
    "enum": ["my_string_1", "my_string_2"]
}

I think you were right on the propertyNames/additionalProperties front, and that appears to get me half way there. I'm just missing some sort of $ref for required:

{
    "$id": "/translation-file.json",
    "type": "object",
    "propertyNames": {
        "$ref": "/locale.json"
    },
    "additionalProperties": {
        "type": "object",
        "propertyNames": {
            "$ref": "/translation-slug.json"
        },
        "additionalProperties": {
            "type": "string"
        }
    }
}

e.g. missing slugs still pass validation:

{
    "en": { 
        "my_string_1": "en1",
        "my_string_2": "en2"
    },
    "fr": {
        "my_string_1": "fr1"
    }
}

[gregsdennis]

Right but the problem you're facing is that required takes an array of strings, not a schema, which means that you can't put the $ref there. This is why I designed data the way I did.

For what you want, you'd need to have locales.json be a file that just contains the array of values.

[
  "en",
  "fr"
]

Then you'd use data like this:

{
  "type": "object",
  "propertyNames": {
    "data": {
      "enum": "/locales.json"
    }
  },
  "data": {
    "required": "/locales.json"
  }
}

The way this works is that all of the values in data are replaced by the resolved values, which produces this (in memory):

{
  "type": "object",
  "propertyNames": {
    "data": {
      "enum": ["en", "fr"]
    }
  },
  "data": {
    "required": ["en", "fr"]
  }
}

Then the data subschemas are evaluated against the instance "transparently" (as if the data keyword wasn't there). So it becomes equivalent to this:

{
  "type": "object",
  "propertyNames": {
    "enum": ["en", "fr"]
  },
  "required": ["en", "fr"]
}

[etinquis]

Is it worth a feature proposal for support for $ref to string array or enum for required? Has that been proposed or discussed before?

EDIT: I guess string array would be too loose, assuming values aren't defined explicitly.

[gregsdennis]

Yeah, $ref to non-schemas or in places where data is expected had been discussed thoroughly, and it's not going to happen. We're happy to take alternate designs, though.

The thing about this is that data keywords (like required) take explicitly that data.

[etinquis]

Thanks, proposal posted at json-schema-org/json-schema-spec#1551

[jdesrosiers]

@gregsdennis, correct me if I'm wrong, but I don't think the data keyword is going to be of use in this case. As I understand it, data is for referencing values from the instance. In this case, they need to reference a value in a schema.

[gregsdennis]

I really think your ideal solution for this particular problem is to drop required and just use propertyNames with an enum, then minProperties at the length of the enum.

{
  "type": "object",
  "propertyNames": {
    "enum": ["foo", "bar", "baz"]
  },
  "minProperties": 3
}

This setup gives you:

• propertyNames constrains that only foo, bar, and baz properties are valid
• minProperties constrains that all of those properties are present

[etinquis]

That seems a little bit better, but I sincerely do want a single source of truth for the set (and that being my enum schema(s)). The example is somewhat contrived to simplify and distill the problem; my schema has more references to more enum schemas with more values. I am worried about maintaining similar-but-different representations of each of those enums, and it feels like the tools are in place to avoid that for all my other applications of this enum pattern except this one.

I'm interested in your thoughts specifically about the suggestion in json-schema-org/json-schema-spec#1551 (comment). I think it would be the most generally applicable among the lot, and would allow application of all the rest of the tools available in the schema spec (beyond just enums) to the required fields.

[etinquis]

I guess I could compromise and add an intermediate schema for e,g AllLocales in the short term, which would at least limit it to two places I'd need to update when updating the enum.

{
  "title": "AllLocales"
  "type": "object",
  "propertyNames": {
    "$ref": "/locales.json"
  },
  "minProperties": <<enumCount>>
}

[etinquis]

Actually, how would I change the value type in that case? It'd have to be generic somehow to have applicability in different contexts.

e.g.

{
    "$id": "/translation-file.json",
    "type": "object",
    "propertyNames": {
        "$ref": "/locale.json"
    },
    "additionalProperties": {
        "type": "object",
        "propertyNames": {
            "$ref": "/translation-slug.json"
        },
        "additionalProperties": {
            "type": "string"
        },  
       "minProperties": <<slugCount>>
    },
   "minProperties": <<localeCount>>
}

{
  "$id": "/locale-maintainers.json",
  "title": "LocaleMaintainers"
  "type": "object",
  "propertyNames": {
    "$ref": "/locale.json"
  },
  "additionalProperties": {
    "$ref": "/translator.json"
  }
  "minProperties": <<localeCount>>
}