Add description fields into the JSON schema

[Klortho]

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]

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

[rmzelle]

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

[Klortho]

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]

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 [email protected]
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
#118 (comment)
.

[rmzelle]

@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]

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]

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]

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]

Referencing #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 (#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]

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