Create JSON Schema for YAML File

[mkdjr]

Co-author: @jassielof

I took a pass at creating a JSON schema based on the Hayagriva specification. This will likely close https://github.com/typst/hayagriva/issues/33!

Please provide any and all feedback! This is my first time creating a JSON schema.

This PR might be related to issue https://github.com/typst/hayagriva/issues/134.

Outstanding Items (copied from below for convenience)

• [ ] Are the tests in tests/schema.rs compliant with the package's architecture?
• [ ] Does the title field still accept a translator sub-field (see: https://github.com/typst/hayagriva/pull/192#discussion_r1966948068)?
• [ ] Upload to the JSON Schema Store, as suggested by @Freed-Wu. See https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md for more information.

[EpicEricEE]

The specification is not fully up to date as the fields added in #102 (abstract, annote and genre) aren't included and are thus also missing here.

[mkdjr]

The specification is not fully up to date as the fields added in #102 (abstract, annote and genre) aren't included and are thus also missing here.

Thanks for pointing this out! I added them to the schema and started a PR to add them to the documentation (https://github.com/typst/hayagriva/pull/194).

[Freed-Wu]

And remember upload it to schemastore :smile:

[jassielof]

I'd like to contribute to this PR, since I like Hayagriva and am currently working with it for my thesis. How could I help?

[PgBiel]

I'd like to contribute to this PR, since I like Hayagriva and am currently working with it for my thesis. How could I help?

We don't have a confirmation yet as to whether these changes will be merged or whether further modifications could be needed, so we can't guarantee a speedy merge, but if you're willing to pick up this work, you're free to address the reviews in your own branch and submit a new PR.

[mkdjr]

Finally got back around to working on this! There ~~are three~~ is one thing~~s~~ on my mind right now w.r.t. improving the schema so that it can be published.

Person Fields

~~Do all fields referring to individuals (author, editor, affiliated) have the same subfields (name, given-name, prefix, suffix, alias)?~~

~~If so, I can reference a common subschema for fields of this type.~~

2025-02-24: Addressed by @jassielof's improvements to the schema.

Affiliated Roles

~~After working on making the values of the type field case insensitive, I realized that the role field for affiliated individuals may also need to be case insensitive.~~

~~Is this the case?~~

2025-02-24: Addressed by @jassielof's improvements to the schema.

Tests

I added tests for validating the schema itself, as well as validating basic.yml. I put the tests under tests/schema.rs and added jsonschema as a development dependency in cargo.toml.

Let me know if any of that should be changed to comply with the package's architecture.

[gwennlbh]

We should probably also mention # yaml-language-server: $schema=... and include it in the examples.

It works with the redhat yaml LSP, which I used on nvim before and also works on VS Code (both combined must cover a substential part of Typst users, outside of Typst.app)

[generalmimon]

https://github.com/sourcemeta/jsonschema reports some issues on the https://github.com/mkdjr/hayagriva/blob/0c640417cfb35067c13f1ee0ce0ee35f57a897fb/hayagriva.schema.json file, so you might want to fix some of them:

$ curl -fsSLO https://github.com/mkdjr/hayagriva/raw/0c640417cfb35067c13f1ee0ce0ee35f57a897fb/hayagriva.schema.json
$ ./jsonschema version
9.3.4
$ ./jsonschema lint hayagriva.schema.json | sed -e 's/'"$(printf '%s\n' "$PWD" | sed -e 's/[\/&]/\\&/g')"'/./g'
./hayagriva.schema.json:
  Only include instances in the `examples` array that validate against the schema (blaze/valid_examples)
    at schema location "/definitions/affiliatedList"
    Invalid example instance at index 0
      The value was expected to be of type array but it was of type object
        at instance location ""
        at evaluate path "/type"
./hayagriva.schema.json:
  Only include instances in the `examples` array that validate against the schema (blaze/valid_examples)
    at schema location "/definitions/entry"
    Invalid example instance at index 0
      The value was expected to be an object that defines the property "type"
        at instance location ""
        at evaluate path "/required"
./hayagriva.schema.json:
  Setting `type` alongside `enum` is considered an anti-pattern, as the enumeration choices already imply their respective types (enum_with_type)
    at schema location "/definitions/roleType"
./hayagriva.schema.json:
  Only include instances in the `examples` array that validate against the schema (blaze/valid_examples)
    at schema location "/definitions/serialNumber/oneOf/1"
    Invalid example instance at index 0
      The value was expected to be of type object but it was of type string
        at instance location ""
        at evaluate path "/type"
./hayagriva.schema.json:
  Only include instances in the `examples` array that validate against the schema (blaze/valid_examples)
    at schema location "/definitions/url/oneOf/1"
    Invalid example instance at index 0
      The value was expected to be an object that defines the property "value"
        at instance location ""
        at evaluate path "/required"

It's arguably not super important, because examples are not used for validation and they should but are not strictly required to validate against the schema, as explained in the JSON Schema docs:

The examples keyword is a place to provide an array of examples that validate against the schema. This isn't used for validation, but may help with explaining the effect and purpose of the schema to a reader. Each entry should validate against the schema in which it resides, but that isn't strictly required.

But I'm still posting the linter output here in case you find it useful.

[jassielof]

Some updates with the schema and also support for the new chapter field. I've removed the $comment fields thanks to YAML to JSON conversion, although I'm not sure if adding the YAML would be fine.

In any case the YAML version is available in my repository: https://github.com/jassielof/json-schemas/blob/main/docs/hayagriva.yaml

For testing the schema in your Hayagriva YAML, at least with Red Hat's YAML extension in VS Code one can add the following line atop of the file: # yaml-language-server: $schema=https://raw.githubusercontent.com/mkdjr/hayagriva/refs/heads/main/hayagriva.schema.json

or using VS Code settings:

  "yaml.schemas": {
    // Replace this with the URL from above
    "https://jassielof.github.io/json-schemas/docs/hayagriva.schema.json": [
      // These for automatic file association to the given schema, these should work for bib.hay, bib.haya, bibliograhy.hay.yml, and such. An official extension by Hayagriva would be good to have as a side note.
      "**/*.{hay,haya,hayagriva}",
      "**/*.{hay,haya,hayagriva}.{yml,yaml}" // Only these will work, since Typst requires the bibliography to have a YAML extension
    ]
  },

Feedback is highly appreciated, so for any issues, please comment them here so I can solve them.

A related issue to the comments is: https://github.com/typst/hayagriva/issues/346.

The schemas (both this and for typst.toml) were previously published by me in https://schemastore.org, but due to request are being removed (https://github.com/SchemaStore/schemastore/pull/5125) at least until there is a higher quality for these.