# Design Principles for CSL JSON

**URL:** <https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671>\
**Category:** CSL Development\
**Created:** [July 13, 2020, 10:45pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671 "2020-07-13T22:45:48Z")\
**Posts on this page:** 20\
**Page:** 2

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 15, 2020, 5:47pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/21 "2020-07-15T17:47:58Z")

</div>

> [@Frank\_Bennett](#):
>
> parsing from plain text and juggling metadata fields are two very different tasks, and they could be separately specified. Just as EDTF provides a separate standalone specification of the syntax of date elements, it should be possible to cast a text parsing specification that sets out the _structures_ that should be generate-able from parsing operations. That would then guide the development of syntax, whether kinda-sorta-HTML or something else. It is the markup _capabilities_ that matter, not the HTML-ness or Markdown-ness of the markup, nor the JSON-ness or YAML-ness of structured output.

In the [experimental solution we settled on](https://discourse.citationstyles.org/t/rfc-rich-text-for-csl-json-input-format/1672), the result is a native JSON data structure; the unambiguous target for any parsing.

Aside: these days, YAML and JSON are effectively interchangeable. Our JSON schemas can validate a YAML variant.

So despite the syntax differences, we’re saying for csl processors, rich text is a nested array of strings and formatted objects.

In YAML:

```yaml
title:
  - A title with tex math
  - math-tex: x=y^2

```

This is also valid though:

```yaml
title: A title

```

But, there’s a reason I marked it “experimental”: we need feedback.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 5:50am UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/22 "2020-07-16T05:50:46Z")

</div>

So concerning these three options regarding titles and subtitles:

> [@Bruce\_D\_Arcus1](#):
>
> - ask processors to split, as we’ve been planning
> - allow titles to be objects, as I mentioned above
> - redefine title to be main title, and add subtitle variables (as in your example)

@Frank_Bennett what would be your perspective on these options? Given your comment above and on the rich text issue, I’d assume that your preference could be option 1, is that correct?

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [July 16, 2020, 10:18am UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/23 "2020-07-16T10:18:33Z")

</div>

I guess I’m curious whether this is an abstract specification (titles may [or must] be parsable into structures that validate against this schema) or something more concrete (titles may be flat strings for verbatim rendering, or structures that validate directly against this schema).

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 10:43am UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/24 "2020-07-16T10:43:34Z")

</div>

The latter, I think.

We’re adding ability to separately specify formatting for main titles and subtitles in styles, because some styles require this.

How should a processor access those parts?

Do we need to change the input schema so a processor accesses them directly:

```python
print(ref['subtitle'])

```

… or:

```python
print(ref['title']['sub'])

```

… or do we require processors to parse title strings to access these:

```python
print(parse_title(ref['title'], 'sub')

```

On the input end, the last option yields no change in the input model, but would result in things like this to accommodate non-standard data for which the algorithms break:

```auto
title: "A title || a subtitle, non-standard delimeter"

```

Keep in mind parsing would also apply in the rich text model; am not sure how that would work, actually (say for a new processor targeting 1.1), because the “title string” would no longer only be a string.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 11:14am UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/25 "2020-07-16T11:14:52Z")

</div>

It may be worth noting that the current proposal to split titles is based on current citeproc-js functionality.

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [July 16, 2020, 12:00pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/26 "2020-07-16T12:00:37Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> Keep in mind parsing would also apply in the rich text model; am not sure how that would work, actually (say for a new processor targeting 1.1), because the “title string” would no longer only be a string.

The logistics do get complicated. But setting aside the rich-text issue, it would obviously be easier in the processor to just receive title and subtitle as separate fields. That’s not the shape of data in the wild, though, so parsing would have to happen somewhere. The burden would just fall on the calling application, which will adopt various solutions or not.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 12:15pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/27 "2020-07-16T12:15:49Z")

</div>

The “redefine title to be main title, and add subtitle variables” option would align us with biblatex.

The title as object I’ve not seen elsewhere (except in MODS).

---

<div class="post-metadata">

**Author:** ![bwiernik](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/bwiernik/32/438_2.png) [@bwiernik](https://discourse.citationstyles.org/u/bwiernik)\
**Post date:** [July 16, 2020, 12:21pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/28 "2020-07-16T12:21:15Z")

</div>

The parsing rules are based on the existing citeproc-js parsing rules that are used for uppercase subtitles. The additions are (1) a style-setting to specify a set of delimiters from a list of discrete options and (2) a specified character string `||` to override automatic parsing (similar to the existing full/short comparison, but not requiring multiple fields).

With respect to how this intersects with rich text—I think a simple rule that parsing doesn’t cross markup boundaries would work.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 1:03pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/29 "2020-07-16T13:03:27Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> The “redefine title to be main title, and add subtitle variables” option would align us with biblatex

That would be a good solution for my use cases. But, as has been said before, that won’t be without problems either.

(Also, even this might require some parsing in the processor: how would a second subtitle be handled in such a solution?)

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 1:13pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/30 "2020-07-16T13:13:41Z")

</div>

> [@Denis\_Maier](#):
>
> how would a second subtitle be handled in such a solution?

It’s not clear to me we should support that.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 1:19pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/31 "2020-07-16T13:19:56Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> It’s not clear to me we should support that

Why not?  
At least with the current proposal it’s possible without adding too much complexity.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 1:44pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/32 "2020-07-16T13:44:57Z")

</div>

Because the current proposal adds complexity upfront.

How about let’s leave this question open until end of day (extending this a bit) Sunday, July 19.

If someone wants to argue for a change from the current plan, please state your case, and which option you prefer, here.

Otherwise, we’ll go the parsing titles route.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 1:51pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/33 "2020-07-16T13:51:01Z")

</div>

> [@bwiernik](#):
>
> With respect to how this intersects with rich text—I think a simple rule that parsing doesn’t cross markup boundaries would work.

I mean, if I were a developer, I would want to literally know how to do it.

All languages have string splitting functions, so with a string, that’s straightforward.

Are we saying splitting only happens, for example, on the formatted string, after primary processing (if dealing with rich text, one would need to format the sub-strings for output to RTF, HTML, LaTeX, or whatever, after all)?

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 2:52pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/34 "2020-07-16T14:52:01Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> Otherwise, we’ll go the parsing titles route.

So the parsing route is your favourite?

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 2:54pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/35 "2020-07-16T14:54:52Z")

</div>

No. 🙂

I’d prefer not, but I want to keep this moving, so …

I do think we need an answer to my latest question though before we actually do this.

And I’m curious what @PaulStanley thinks as a relative newcomer.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 2:57pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/36 "2020-07-16T14:57:52Z")

</div>

> [@Bruce\_D\_Arcus1](#):
>
> I’d prefer not

Like not at all or simply not parsing?

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 2:59pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/37 "2020-07-16T14:59:52Z")

</div>

You asked about parsing, so that’s all I meant.

---

<div class="post-metadata">

**Author:** ![Denis\_Maier](https://avatars.discourse-cdn.com/v4/letter/d/8491ac/32.png) [@Denis\_Maier](https://discourse.citationstyles.org/u/Denis_Maier)\
**Post date:** [July 16, 2020, 3:08pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/38 "2020-07-16T15:08:02Z")

</div>

Ok.  
But then which one of those three options would be your favorite? (But you don’t want to argue for a change if plans?)

No doubt, feedback from other implementers would be useful. This is based on current citeproc-js behaviour, but what do @PaulStanley, @cormacrelf, @John_MacFarlane think about this? Also @asimonyi

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [July 16, 2020, 3:08pm UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/39 "2020-07-16T15:08:54Z")

</div>

I don’t have a strong preference. I can see arguments either way.

> But you don’t want to argue for a change if plans?

I think we should ideally base the decision on what works for styles and style authors, and for CSL developers. I have concerns about the parsing for the latter, but developers can speak for themselves.

I may change my mind based on subsequent conversation though 😉

---

<div class="post-metadata">

**Author:** ![bwiernik](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/bwiernik/32/438_2.png) [@bwiernik](https://discourse.citationstyles.org/u/bwiernik)\
**Post date:** [July 17, 2020, 2:39am UTC](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671/40 "2020-07-17T02:39:01Z")

</div>

Just to clarify the main vs short title distinction, this is something that is a pretty annoying limitation for BibTeX users in fields like law that regularly use short titles that aren’t just the main title.

[Previous page](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671.md?page=1)

[Next page](https://discourse.citationstyles.org/t/design-principles-for-csl-json/1671.md?page=3)