Restructuring Rules.json

[MikkelPaulson]

Summary

Combines Rules.json and Rule-Sections.json into a single file with self-referential links according to the following format:

[
  {
    "name": "System Reference Document 5.1",
    "index": "srd",
    "url": "/api/rules/srd"
    "children": [
      {
        "name": "Combat",
        "index": "combat",
        "url": "/api/combat"
      },
      // ...
  },
  {
    "name": "Combat",
    "index": "combat",
    "url": "/api/rules/combat"
    "desc": "...",
    "parent": {
      "name": "System Reference Document 5.1",
      "index": "srd",
      "url": "/api/srd"
    },
    "children": [
      {
        "name": "The Order of Combat",
        "index": "the-order-of-combat",
        "url": "/api/the-order-of-combat"
      },
      // ...
  },
  // ...
]

---

Original text follows.

Currently the rules are spread across two files, as follows:

// 5e-SRD-Rules.json
[
  {
    "name": "Combat",
    "index": "combat",
    "desc": "# Combat\n",
    "subsections": [
      {
        "name": "The Order of Combat",
        "index": "the-order-of-combat",
        "url": "/api/rule-sections/the-order-of-combat"
      },
      // ...
    ],
    "url": "/api/rules/combat"
  }
]

// 5e-SRD-Rule-Sections.json
[
  {
    "name": "The Order of Combat",
    "index": "the-order-of-combat",
    "desc": "## The Order of Combat\n\nA typical combat encounter is a clash between two sides, a flurry of weapon swings, feints, parries, footwork, and spellcasting. The game organizes the chaos of combat into a cycle of rounds and turns. A **round** represents about 6 seconds in the game world. During a round, each participant in a battle takes a **turn**. The order of turns is determined at the beginning of a combat encounter, when everyone rolls initiative. Once everyone has taken a turn, the fight continues to the next round if neither side has defeated the other.\n\n##### Combat Step by Step\n\n...",
    "url": "/api/rule-sections/the-order-of-combat"
  },
  // ...
]

However, the current situation doesn't do a particularly good job of representing the data in either a human- or machine-readable format. For my own use case, I'd like to have much smaller text snippets for reference purposes, so that a user could search for "Bonus Actions" and see only the snippet . Most of the data from the SRD is digested into bite-sized pieces, so it's rather out of place to have these giant blobs of text in 5e-SRD-Rule-Sections.json.

I suggest consolidating the rules down into a single file, with each heading getting its own entry.

// 5e-SRD-Rules.json
[
  {
    "name": "Combat",
    "index": "combat",
    // no "desc" key at all as this heading continues directly into "The Order of Combat"
    "subsections": [
      {
        "name": "The Order of Combat",
        "index": "the-order-of-combat",
        "url": "/api/rules/the-order-of-combat"
      },
      // ...
    ],
    "url": "/api/rules/combat"
  },
  {
    "name": "The Order of Combat",
    "index": "the-order-of-combat",
    // No title, includes all content to the next subheading
    "desc": "A typical combat encounter is a clash between two sides, a flurry of weapon swings, feints, parries, footwork, and spellcasting. The game organizes the chaos of combat into a cycle of rounds and turns. A **round** represents about 6 seconds in the game world. During a round, each participant in a battle takes a **turn**. The order of turns is determined at the beginning of a combat encounter, when everyone rolls initiative. Once everyone has taken a turn, the fight continues to the next round if neither side has defeated the other.",
    "subsections": [
      {
        "name": "Combat Step by Step",
        "index": "combat-step-by-step",
        "url": "/api/rules/combat-step-by-step"
      },
      // ...
    ],
    "url": "/api/rule/the-order-of-combat"
  },
  {
    "name": "Combat Step by Step",
    "index": "combat-step-by-step",
    "desc": "..."
    "url": "/api/rules/combat-step-by-step"
  // ...
]

Alternatively, a parent_url field could be added to the child rather than the subsections field on the parent. Either way, it would have to be associated with tests ensuring that there are no circular dependencies, there is only one root node, and there are no orphaned nodes. A bidirectional association is also possible for easier reading, but that would require extra test coverage to maintain consistency.

[bagelbits]

I assume that subsections is a more useful field since I can see it more often looking at a rule and wanting know it's subsections, then looking at a rule and wanting to know it's parent.

I've also been wondering in the back of my mind about the distinction between the two tables.

[fergcb]

I really like this proposed structure, and I think breaking the rules sections down into smaller, bitesize pieces makes a lot of sense. I think bidirectional relationships would be a good idea - both a parent_section and subsections fields. Scrapping subsections would make it harder to construct larger rules sections top-down.

As for human-readability, we've talked a lot in the past about choosing a Markdown standard and sticking to it, applying it across the whole database. This could be a good chance to make sure the rules sections are using well-formed Markdown in their longtext fields.

[MikkelPaulson]

I assume that subsections is a more useful field since I can see it more often looking at a rule and wanting know it's subsections, then looking at a rule and wanting to know it's parent.

I've also been wondering in the back of my mind about the distinction between the two tables.

subsections has the benefit that clarifies the order in which two subsections of the same level should appear, which is only known implicitly using parent_url. (Come to think, parent_index might make more sense, since you'll never reference parents in other listings.)

However, the top level rendering gets a bit weird if we only have subsections. Do we have a root "SRD" entity that contains all top-level sections? Do we assume that all sections that are not subsections of other sections appear at the top level?

[fergcb]

I think we can assume that sections with no parent are top-level. Though I see no issue with creating a single root "SRD" section containing all the true "top-level" sections, if only to preserve their order for those wanting to render the entire tree of rules sections.

parent_url. (Come to think, parent_index might make more sense, since you'll never reference parents in other listings.)

I think it'd be good to include full APIReferences for the parent, to keep consistency with the rest of the API. All internal document references, same collection or otherwise, are made using APIReferences.

[bagelbits]

All of this ^^^

[bagelbits]

I think a single root "SRD" sections is a good idea. It should probably be the first one as well.

[MikkelPaulson]

Okay, so if I understand correctly, it sounds like we're converging on:

[
  {
    "name": "The Order of Combat",
    "index": "the-order-of-combat",
    "desc": "...", // optional, body text only (no headings)
    "children": [ // optional
      {
        "name": "Combat Step by Step",
        "index": "combat-step-by-step",
        "url": "/api/rules/combat-step-by-step"
      }
    ],
    "parent": { // optional -- absent for root node, of which there can be only one
      "name": "Combat",
      "index": "combat",
      "url": "/api/rules/combat"
    },
    "url": "/api/rule/the-order-of-combat"
  },
  // ...
]

[MikkelPaulson]

As for human-readability, we've talked a lot in the past about choosing a Markdown standard and sticking to it, applying it across the whole database. This could be a good chance to make sure the rules sections are using well-formed Markdown in their longtext fields.

Good point. "desc" is currently a string in both rules files, but many other files represent it as an array of lines. Should we adopt that convention here as well?

[bagelbits]

Good point. "desc" is currently a string in both rules files, but many other files represent it as an array of lines. Should we adopt that convention here as well?

You know. I can't remember if we ever came to a consensus on this. It would be nice to be consistent for all desc fields.

[fergcb]

Other files represent it as an array of lines. Should we adopt that convention here as well?

No. Actually, Rules seems to be a better example than other desc fields: a single string containing well-formed Markdown, with paragraphs denoted by double line breaks.

I only mentioned it because Rules means lots of longtext, but it would appear you needn't worry about that, as it's already been done right.

[MikkelPaulson]

My preference would be to converge behind a single Markdown string for all fields including desc project-wide, for all that the readability at a JSON level suffers as a result. However, that's not really relevant for today's purposes. Unless there's a strong consensus in the other direction, we can just leave it as-is.

[fergcb]

My preference would be to converge behind a single Markdown string for all fields including desc project-wide, for all that the readability at a JSON level suffers as a result. However, that's not really relevant for today's purposes. Unless there's a strong consensus in the other direction, we can just leave it as-is.

The consensus is indeed to leave it as-is, in this case.

I had forgotten that the Rules documents had already been brought up to standard.

[MikkelPaulson]

Okay, I'll add this to my to-do list, unless someone else is feeling bored.