adam/vscode-front-matter
1
0 Fork 0
mirror of https://github.com/estruyf/vscode-front-matter.git synced 2026-10-30 23:41:57 +01:00
Code Issues 77 Packages Projects Releases Wiki Activity

Enhancement: Document data schema limitations #321

New Issue
Open
opened 2026-10-05 02:40:04 +02:00 by adam · 3 comments
adam commented 2026-10-05 02:40:04 +02:00
Owner
Copy link
Copy source

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

Gif showing attempted data entry for a multi-type property, unable to set the value to the second valid data type

**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** ![Gif showing attempted data entry for a multi-type property, unable to set the value to the second valid data type](https://user-images.githubusercontent.com/14190564/189028480-dd3dc267-1b9a-4c99-9a54-b44b67daa3f3.gif) <!-- github-sync-id:1365473638 -->
adam commented 2026-10-05 02:40:05 +02:00
Author
Owner
Copy link
Copy source

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.

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. <!-- github-comment-id:1240379924 -->
adam commented 2026-10-05 02:40:05 +02:00
Author
Owner
Copy link
Copy source

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
      }
    }
  }
}
Aha, thanks for pointing me in the right directions! I found their docs, which [call out edge cases around `allOf`, `anyOf`, and `oneOf][01] and references vazco/uniforms#863 for the discussion/explanation. In vazco/uniforms#1072 there's [a comment][02] 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: ```jsonc // 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" } } } ``` ```jsonc // 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: ```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", "frontMatter": { "single": true } }, "example": { "title": "Example data", "type": "string", "frontMatter": { "single": false } } } } ``` [01]: https://uniforms.tools/docs/api-bridges/#note-on-allofanyofoneof [02]: https://github.com/vazco/uniforms/issues/1072#issuecomment-990843180 <!-- github-comment-id:1240686200 -->
adam commented 2026-10-05 02:40:06 +02:00
Author
Owner
Copy link
Copy source

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.

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. <!-- github-comment-id:1272224903 -->
Sign in to join this conversation.
No Branch/Tag Specified
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
adam (Adam Wojcieszonek)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: adam/vscode-front-matter#321