question-mark

Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Restructuring Rules.json

See original GitHub issue

Issue Description

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.

Issue Analytics

  • State:open
  • Created 9 months ago
  • Comments:13 (9 by maintainers)

github_iconTop GitHub Comments

2reactions
fergcbcommented, Apr 21, 2022

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.

2reactions
fergcbcommented, Apr 21, 2022

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.

Read more comments on GitHub >

github_iconTop Results From Across the Web

Restructuring JSON with JavaScript by specific rules - Stack Overflow
Restructuring JSON with JavaScript by specific rules ... I have a list of JSON objects in javascript looks like this: [{"model":"alpha", "ports":4}, ...
Read more >
How do I restructure JSON files ? - Trifacta Community
How do I restructure JSON files ? In the docs it states that the JSON input data has to have one JSON object...
Read more >
Creating IAM policies (console) - AWS Documentation
IAM identifies JSON syntax errors, while IAM Access Analyzer provides additional ... IAM might restructure your policy to optimize it for the visual...
Read more >
Reshaping JSON with jq - Programming Historian
JSON (JavaScript Object Notation) is a common data sharing format that ... will only pass along the JSON objects that match the rule...
Read more >
Export Load Rules for Offline Editing - Essbase
The JSON is structured into dimensions and fields, and reveals build methods and all other defined load rule settings. You can edit the...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found