search

citation-style-language / schema

Citation Style Language schema
https://citationstyles.org/
MIT License
187 stars 60 forks source link

Add description fields into the JSON schema #118

Open Klortho opened 10 years ago

Klortho commented 10 years ago

It would be nice to have some more documentation of the json schema.

We could start by adding a “description” field (see this example) into the .json schema files themselves, copy-pasting text from the CSL spec appendix IV.

rmzelle commented 10 years ago

Is that really helpful, though? It will be an extra burden to keep the descriptions synchronized. I rather just point to the appendix.

rmzelle commented 10 years ago

I much rather see an accompanying human-readable spec to describe the CSL JSON format, in the same spirit as the CSL spec.

Klortho commented 10 years ago

Is that really helpful, though? It will be an extra burden to keep the descriptions synchronized. I rather just point to the appendix.

IMO, it makes sense to keep the description of record in the same place as the schema, because it's easier to keep it in sync with the actual schema itself. In other words, if the schema changes, and the description is right there, it's easy for a developer to update the description at the same time. Whereas, if the description lives in a completely different repo, whose sources are hard to find, it adds an extra burden, and the documentation will invariably fall out of date.

bdarcus commented 10 years ago

One way to split the difference: keep the content in the schema, and pull it out (by simple script) for human-readable purposes?

On Mon, Aug 25, 2014 at 3:05 PM, Chris Maloney notifications@github.com wrote:

bq. Is that really helpful, though? It will be an extra burden to keep the descriptions synchronized. I rather just point to the appendix.

IMO, it makes sense to keep the description of record in the same place as the schema, because it's easier to keep it in sync with the actual schema itself. In other words, if the schema changes, and the description is right there, it's easy for a developer to update the description at the same time. Whereas, if the description lives in a completely different repo, whose sources are hard to find, it adds an extra burden, and the documentation will invariably fall out of date.

— Reply to this email directly or view it on GitHub https://github.com/citation-style-language/schema/issues/118#issuecomment-53312133 .

rmzelle commented 10 years ago

@adam3smith, @ajlyon, thoughts?

On the Zotero roadmap is a revision of its data model. It's been a long wait so far, but it should be on the horizon once their lead developer finishes up their switch to a new synchronization code base. We already accumulated a lot of tickets (https://github.com/ajlyon/zotero-bits/issues), and some of these things will require changes on the CSL side as well. I think it will be one of the main drivers for a new CSL release.

Since that work will focus specifically on fields and their intended use, I foresee quite a few changes to all the field descriptions. I really think it would be simpler to therefore keep the field descriptions in a single place for now (i.e., in the spec).

Klortho commented 10 years ago

Well, if you have a spec, and there's a clear link to it from the readme and/or the json schema (say, the top level description field) that would be fine. But right now it's a bit hard to pull the pieces together. I just noticed you took out my links to the relevant documentation page from the README -- not sure why you did that.

adam3smith commented 10 years ago

I do think the description should exists as a nicely formatted, human-readable document so that non-techie folks aren't deterred from reading it (if they're interested), and I think it makes sense to closely tie it to the schema. I have no preferences on the way this is done, whether via link from schema to specs or by embedding it in the schema and auto-extracting like Bruce suggests. The former seems easier to me.

Agree with Rintze that the Zotero field revisions and likely new CSL version in their wake would be a good occasion for that.

bdarcus commented 10 years ago

FWIW, I included documentation early on in both the CSL schema and the first (XSLT) implementation. But that was mostly because tools and applications supported them. Not sure JSON Schema is there yet?

dhimmel commented 3 years ago

Referencing https://github.com/citation-style-language/schema/issues/190 which is related.

IMO, it makes sense to keep the description of record in the same place as the schema, because it's easier to keep it in sync with the actual schema itself.

Absolutely. The appendix can always just pull the descriptions from the schema.

For example, I see there is a 1.0.2 release where a citation-key variable has been added. I can find the PR that added it (https://github.com/citation-style-language/schema/pull/246). However there is no "appendix" doc page for 1.0.2 at https://docs.citationstyles.org/en/1.0.2/specification.html. I only see 1.0.1.

Now I see in the documation source in citation-style-language/documentation which does describe citation-key (but hasn't been deployed yet).

Putting the field documentation in the JSON schema would:

  1. consolidate everything to one repository. For example, you could ensure all additions to the schema came with descriptions, because there would only be one repo involved. Currently, schema v1.0.2 is released but not documentation v1.0.2.

  2. make the schema self-sufficient in terms of documenting CSL JSON. It's a challenge to have to jump between places to get a complete description of the CSL JSON.

  3. make it obvious which fields are undocumented. For example, the two required fields id and type are not documented in the "Appendix IV - Variables" list alongside the other fields.

bwiernik commented 3 years ago

@dhimmel The 1.0.2 documentation is being finalized. It's not yet released.