Enhancement: Document data schema limitations

[michaeltlombardi]

Is your feature request related to a problem? Please describe.

While schematizing my data files so they can be edited in Front Matter, I ran into a case where one of my data types should be able to take either an integer or null, but in the data view on the dashboard, only the first declared data type in the oneOf key is respected.

I suspect this is because the current implementation assumes a single valid data type per property, which is reasonable, but does mean that complex schemas may not work as expected, if at all.

Describe the solution you'd like

Given how difficult I expect it is to implement a full-featured data entry view for fully arbitrary data modeled by a JSON schema, especially a complex one, I would like to have any known limitations and requirements documented.

Describe alternatives you've considered

I can't think of any, short of implementing every possible feature for entering data.

Additional context

[estruyf]

For the data file implementation, I rely on a library called Uniforms. It seems that the limitation is coming from this library. I just tested it on their playground and got the same error.

IMO the data files should eventually get an easier configuration and implementation. Getting it closer to the content type implementation might be better, but this is just my idea. Happy to hear what others think and how they see this experience evolve.

[michaeltlombardi]

Aha, thanks for pointing me in the right directions! I found their docs, which call out edge cases around allOf, anyOf, and `oneOf and references vazco/uniforms#863 for the discussion/explanation.

In vazco/uniforms#1072 there's a comment that I don't understand the implementations well enough to gauge difficulty/effort for but implies there's a way to get at this sort of UI for Front Matter, I think:

in uniforms, the forms know about the possible fields from the bridges. And the bridges cannot depend on the current model (i.e., data). So overall, in the current architecture, it's simply not possible.

But! The option would be to implement a custom AutoField that would actually understand the if/then and any other properties (including your custom ones, if ready). In such a field you can access the schema (via bridge) as many times as needed, but you also can access the model.

On the idea of moving the definition for data types closer to the way content types are defined, I think there's definitely pros and cons. The biggest pro to my mind is one way of defining fields and how they can/should behave in the UI. The biggest downside is moving away from the validation/reusability of a "normal" JSON schema.

I think what could be a really slick (and likely high-effort to develop) compromise would be for some DevX tooling around converting a JSON schema over, or an explicit model for extending one for the Front Matter UI.

If I could define something like this and have things work, I would be pretty happy:

// schema at https://foo.bar/schemas/baz/1.0.0/schema.json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://foo.bar/schemas/baz/1.0.0/schema.json",
  "title": "Foo Bar Baz",
  "type": "object",
  "properties": {
    "name": {
      "title": "Entry Name",
      "type": "string"
    },
    "example": {
      "title": "Example data",
      "type": "string"
    }
  }
}

// frontmatter.json
"frontMatter.data.files": [
  {
    "id": "Testable",
    "path": "[[workspace]]/data/tests",
    "labelField": "name",
    "schemaUrl": "https://foo.bar/schemas/baz/1.0.0/schema.json",
    // alternatively, if the schema is local:
    "schemaPth": "[[workspace]]/data/schemas/baz.schema.json",
    "mungePoperties": {
      "name": {
        "single": true
      },
      "example": {
        "single": false
      }
    }
  }
]

I think (for me) being able to define the data model in JSON Schema but control the UI presentation in Front Matter would be an ideal best of both worlds. I absolutely see how that would make things much more complicated for Front Matter itself though, so maybe some commands/documentation for getting someone part-of-the-way would be good?

One other option that occurs to me is to define options that I can use with a frontmatter key in my schema, so I would just write this for my JSON schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://foo.bar/schemas/baz/1.0.0/schema.json",
  "title": "Foo Bar Baz",
  "type": "object",
  "properties": {
    "name": {
      "title": "Entry Name",
      "type": "string",
      "frontMatter": {
        "single": true
      }
    },
    "example": {
      "title": "Example data",
      "type": "string",
      "frontMatter": {
        "single": false
      }
    }
  }
}

[michaeltlombardi]

Thinking about this again, I think this is potentially addressed separately in #441 (where I could write my description keys to clarify input requirements), #397 (where I could directly reference an external JSON Schema instead of redefining the schema in my Front Matter config), and #407 / #412, which introduce logic for merging configuration values.