how to express deprecated enum values?

[toumorokoshi]

Hello!

Is it possible to express specific values of an enum in jsonschema as deprecated? The documentation doesn't have an example.

It seems like this might be best supported by some sort of structure for enums as well (although this approach is backwards-incompatible:

{
  "enum": [
      "red", 
      "amber", 
      {"value": "green", "deprecated": true}
  ]
}

[gregsdennis]

You could do this with an anyOf.

{
  "anyOf": [
    { "enum": [ "red", "amber" ] },
    {
      "enum": [ "green" ],
      "deprecated": true
    }
  ]
}

[gregsdennis]

The trouble with

{
  "enum": [
      "red", 
      "amber", 
      {"value": "green", "deprecated": true}
  ]
}

is that enum only checks exact values. That means that {"value": "green", "deprecated": true} is a value. green would be invalid.

[toumorokoshi]

thanks! yes, I figured that it could break behavior.

I suppose also my suggestion ambiguates between the value actually being an object with the key 'deprecated', or whether it's marking the value deprecated.

the anyOf sets seems like it would work! thanks.

[toumorokoshi]

I'd like to re-open this issue because, after some further thought, I think that switching from an enum to an anyOf might be breaking change.

For example, if a generated client models the two enums as separate, then that would result in two different classes in a language and therefore breaking the interface in a subsequent update.

A more backwards-compatible change might be:

{
  "enum": [
      "red", 
      "amber", 
      "green"
  ],
  "deprecatedValues": [
      "green"
  ]
}

[gregsdennis]

@toumorokoshi code generation isn't a use case that we include in the scope of the specification, and this seems very specific to that use case. It seems to me that supporting what I suggested this would be a good proposal for the code generation tooling you're using.

If you'd like to propose a new keyword, I recommend opening an issue in the vocabularies repository. For now, I can't see that we'd be adding this.

For either your proposal or mine, the tooling you're using will have to update to support it.

[pinalbaldha]

@gregsdennis This is similar to enum value description requirement, where oneOf + const is suggested.
#57 & json-schema-org/json-schema-vocabularies#47

Example:

MyEnum:
oneOf:
- const: test1
- const: test2
deprecated: true
description: Use test3 instead
- const: test3

What are plus point on anyOf solution over oneOf + const solution? To me oneOf + const, looks cleaner.

[gregsdennis]

I think that's just about the only way to support what you want for right now.

The downside to that approach is that you get messages for each subschema in the oneOf. This is the complaint most people have, but it works.

So for example, if your instance is test3, then you'll get error messages for

• it doesn't match /oneOf/0/const
• it doesn't match /oneOf/1/const

But overall, it will validate.

[toumorokoshi]

@toumorokoshi code generation isn't a use case that we include in the scope of the specification, and this seems very specific to that use case. It seems to me that supporting what I suggested this would be a good proposal for the code generation tooling you're using.

This is a little unfortunate because I think a lot of projects (e.g. OpenAPI) heavily rely on the specification for code generation. But of course I respect and appreciate the clarification about the intention of the project.

If you'd like to propose a new keyword, I recommend opening an issue in the vocabularies repository. For now, I can't see that we'd be adding this.

got it, thanks for clarifying.

I do feel this is a deficiency of enums, but I guess OneOfs will have to do.

[gregsdennis]

I don't think there's anything to do here right now.