Do we need an `Omitted`?

[charjr]

Current Behaviour

Omitted properties, without a default, are set to null.

When we need to use null as an actual value, we have to use a Value object.
This is the case for keywords that give values that should pass the Schema.
i.e. example, examples, const, enum, default

Reasons For

We get to use isset(<keyword>) or <keyword> === null to check for omitted properties. It's fast and built in.

The Value keyword hides away messy mixed typehints:

Value|null $keyword

vs.

// @var scalar|array<mixed>|null $keyword
bool|float|int|string|array|null $keyword

Reasons Against

• We're adding semantic meaning to null which is not part of the Domain Specific Language.
  • A default of null is not "a default of null", it means "no default"
  • A default of new Value(null) is "a default of null"

Alternate Behaviour

Omitted properties, without a default, are set to Omitted.

Reasons For

• Omitted is part of the Domain Specific Language.
• No Value wrapper required (That is not to say we can't have both)
• null is null (no additional semantic meaning behind it)

Reasons Against

• We can't use isset(<keyword>)
  • You'd have to check <keyword> === Omitted
• Typehints are more verbose. eg. string|null vs. string|Omitted

Discuss

Both solutions have their merits. I would like to weigh them up here, to have a written record of our design choices.