Property definitions type for timestamp (and other non-json OPTIMADE types)

[rartino]

I'm not sure how we missed this :-), but the definition of the type field in the property definitions go through each JSON data type and explain what it corresponds to in terms of OPTIMADE data types. But, that means it never says what to do for timestamps.

To keep the property format valid JSON schema, the standard type field needs to be "string". But, this means we need to add another type field (x-optimade-type?) to spell out "datetime" somewhere.

This will also be important to figure out for other new datatypes we add in the future, e.g., there is a proposal for a SMILES datatype #436.

[ml-evs]

I'm not sure we need to add this (though it would perhaps be nice just for compatibility again with the older versions).

You can express datetimes in JSON Schema using the format argument to the string type. Here's how it looks right now in the v1.1 OpenAPI schema for last_modified:

"last_modified": {
    "title": "Last Modified",
    "type": "string",
    "description": "Date and time representing when the entry was last modified.\n\n- **Type**: timestamp.\n\n- **Requirements/Conventions**:\n    - **Support**: SHOULD be supported by all implementations, i.e., SHOULD NOT be `null`.\n    - **Query**: MUST be a queryable property with support for all mandatory filter features.\n    - **Response**: REQUIRED in the response unless the query parameter `response_fields` is present and does not include this property.\n\n- **Example**:\n    - As part of JSON response format: `\"2007-04-05T14:30:20Z\"` (i.e., encoded as an [RFC 3339 Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6) string.)",
    "format": "date-time"
}

Here's a full list of the string formats we could use: https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats

(we are already using email and URL in the OpenAPI spec)

Again, perhaps we can just add a note to say that this is the way to express these derived types?

[rartino]

Right, but, an implementation that wants to interpret the property definition in context of an output format that has a native timestamp datatype needs to be able to understand that a property definition of, e.g., last_modified refers to the OPTIMADE timestamp data type, and not to a string.

I'm halfway convinced we should simply add a mandatory x-optimade-type that always spells out the OPTIMADE type name, but it adds redundancy for most data types. Maybe for now it is best to do as you say and rely on the "format" field. But, that means we need to invent our own format name for the upcoming SMILES datatype.

[ml-evs]

I'm halfway convinced we should simply add a mandatory x-optimade-type that always spells out the OPTIMADE type name, but it adds redundancy for most data types. Maybe for now it is best to do as you say and rely on the "format" field. But, that means we need to invent our own format name for the upcoming SMILES datatype.

I'm with you now -- this seems like something we could easily add now if we want to, if it is just constrained to our existing types? (i.e., we don't want to support implementation-specific types)