Option 5:
- Let people & style authors do whatever they want with first-class, namespaced escape hatches, BUT provide a way that users can be made aware of breaking changes that styles make for people who depend on those escape hatches.
I got all excited about giving styles version numbers a while back, but for the wrong reasons – I had thought reusability of style code was the goal. It isn’t. (I’m such a programmer.) The correct goal is letting people keep creating documents with the same reference library and data-entry conventions while upgrading to new releases of styles.
Say you allowed extensions in a <schema> block, that the processor can validate.
<style style-version="2.3.0" xmlns:chicago="https://citationstyles.org/schema/chicago">
<schema namespace="chicago">
<!-- - bool can be checked in a condition
<if chicago:var="true" />
- string is a regular variable
<text variable="chicago:var" />
- name is a name variable
<names variable="chicago:var" />
- date is a date variable
<date variable="chicago:var" />
- number is a number variable
<number variable="chicago:var" /> -->
<key name="chapter-is-introduction" type="bool" />
<!-- - enum could be like a CSL type: <if chicago:some-enum="two" /> -->
<key name="some-enum" type="enum" values="one two three" />
</schema>
<citation>
<layout>
<choose>
<if chicago:chapter-is-introduction="true" />
</choose>
</layout>
</citation>
</style>
A researcher with a library full of introductory chapters is using Chicago. She realises these are being formatted incorrectly, and asks @Sebastian_Karcher to improve the style for her. He releases Chicago version 2.3.0 as above, and she puts in her Zotero settings (e.g.) that her library depends on Chicago version range “2.3”, i.e. ^2.3.0 in Node semver notation. Zotero then creates some field UI to edit this.
[{
"id": "citekey",
"type": "chapter",
"title": "What is Your Dangerous Idea?",
"schema:https://citationstyles.org/schema/chicago": {
"chapter-is-introduction": true
}
}]
Version 2.4 might add another key to the schema (a semver ‘feature’); version 2.5 might adopt some CSL spec addition that covers this, but retain backwards compatibility with people who are using the old schema entry; version 3.0.0 (breaking) might stop supporting the schema and only support the official way. Styles should have a changelog, so that researchers who are using one version know what might break or be improved if they were to upgrade.
By validate, I mean emit warnings or errors if a user enters:
{ ..., "schema:some-unsupported-schema": { ...} }
=> info: reference ID "citekey" included properties for "some-unsupported-schema"
(may not be an error, because e.g. most styles do not treat introductions differently.
This is an 'include X hacks for chicago' type of deal.)
{ ..., "schema:...": { "some-unsupported-key": "..." } }
=> error: schema "chicago" does not support this key.
{ ..., "schema:...": { "chapter-is-introduction": "some-improperly-typed-value" } }
=> error: schema "chicago" key "..." expected a boolean value, found string
I included namespacing in this concept so that multiple similar styles can share a namespace and the properties within it. That way one library could mostly work across a larger number of styles, e.g. all of the variants of a particular style. But it also means that you don’t have to worry about name collisions with future official variable names in the CSL-JSON input. Just reserve schema:* and you’re good.
Obviously not all of this works very well (esp the sharing of namespaces between styles), but it’s maybe a start. I’m thinking now it would be better for schemas to have a version, and styles to support a version range? Anway, there are my thoughts.
PS, <key> could also have for="chapter othertypes", to enforce usage only with a specific set of types.