Some `logicalTypeOptions` are not enfoced

[OGsiji]

While answering a question on the ODCS spec repo about declaring more than one date format (bitol-io/open-data-contract-standard#306), I traced how logicalTypeOptions.format flows through the CLI and ended up somewhere I didn't expect. Filing it as a question rather than a bug, because the answer may well be "intentional".

A declared date format is never applied

For a property with logicalType: date / timestamp / time, logicalTypeOptions.format holds a JDK DateTimeFormatter pattern (yyyy-MM-dd, per the ODCS schema's own examples). As far as I can tell it is never read:

• engines/checks/create_checks.py builds checks from minLength, maxLength, minimum, maximum, exclusiveMinimum, exclusiveMaximum, pattern and enum. format is not among them.
• export/jsonschema_exporter.py does read it, but convert_type_format substitutes a fixed value for these types and drops the declared one:

if type_str.lower() in ["timestamp", "timestamp_tz", "date-time", "datetime"]:
    return "string", "date-time"
if type_str.lower() in ["date"]:
    return "string", "date"
if type_str.lower() in ["time"]:
    return "string", "time"

So format: "dd/MM/yyyy" on a date column has no effect on any server type.

That may be the right call — a JDK pattern has no JSON Schema equivalent, and date-time is the closest thing available. If so, it's worth saying in the docs, because the option looks enforceable and isn't.

It behaves differently on a string property

For logicalType: string, convert_type_format passes the declared format straight through to JSON Schema, where fastjsonschema validates it. But check_jsonschema returns early unless server.format == "json", so:

property	server.format: json	any other server
string with format	validated	ignored
date/timestamp/time with format	ignored (overridden)	ignored

Same contract option, three different fates depending on the logical type and the server. That's the part that seems most worth resolving one way or the other.

Other options with no reader

While looking, these appear in the ODCS 3.1.0 logicalTypeOptions surface but have no handling in export/ or engines/:

• multipleOf (integer, number) — written by the Excel importer, read by nothing
• maxItems, minItems, uniqueItems (array)
• maxProperties, minProperties (object)
• defaultTimezone (timestamp)

The array and object families look like the most substantive gap, since minItems/uniqueItems are checks a warehouse could genuinely run.

Question

Is the intent that logicalTypeOptions is descriptive metadata, with only the subset above enforced deliberately — or should the check builder be growing to cover more of it?

Happy to send a PR either way: docs clarifying which options are enforced and where, or an implementation of whichever of these you'd want checked. I'd rather ask first than guess at the scope.

[jschoedl]

Hi @OGsiji, thank you for asking about your findings! Indeed, the functionality of datacontract-cli is only a subset of what could be supported by ODCS.

Check out this list of intentional limitations: https://docs.datacontract.com/schema#what-is-not-checked
Maybe we should put this list somewhere else so its more obvious to find - where did you search for it?

The list includes the format option, where we recommend pattern as enforceable alternative. For the other logicalTypeOptions you mentioned, those are indeed not yet implemented and we'd welcome PRs for them.

[OGsiji]

Thanks — that's the answer, and pattern as the enforceable alternative makes sense.

On where I looked: I came at it from the ODCS side rather than the docs. Someone on the spec repo asked whether a date column could declare more than one format, so I traced what the reference implementation actually does with the one it already accepts — _get_logical_type_option call sites in create_checks.py, then convert_type_format in the JSON Schema exporter. I never searched the docs for "what is not checked", because I wasn't asking "is this checked", I was asking "where does this value end up".

So I'm probably not the representative case for discoverability. But two things might still help someone who is:

The list lives under Schema, which is where you'd look if you were authoring a contract. I'd have found it faster from the datacontract test page — at the moment you're wondering why a constraint didn't fire, you're thinking about the test command, not the schema reference. Even a one-line "not every ODCS attribute produces a check — see …" there would catch that path.

The other thing is that the format bullet reads as being about string formats:

logicalTypeOptions.format (email, uuid, uri, …) — use pattern for an enforceable equivalent.

For email or uuid, pattern is a genuine substitute. For a date/timestamp/time property, format holds a DateTimeFormatter pattern like yyyy-MM-dd, and there pattern isn't equivalent — it can assert the shape of the string, but the column has already been parsed as a date by then. That case is also stranger than "not checked", because convert_type_format actively replaces the declared pattern with a fixed JSON Schema date/date-time/time. Worth a few extra words on that bullet, I think.

Happy to send a docs PR for both of those if useful.

And thanks for the pointer on the rest — I'll pick up the unimplemented logicalTypeOptions in a separate PR. minItems/maxItems/uniqueItems and minProperties/maxProperties look like the most useful of them, since those are real checks a warehouse can run. I'll start there rather than doing all of them at once.

[jschoedl]

Thank you for the explanation and the PR! If you have time for it, I'd appreciate a PR with the docs changes as well.