{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://earslang.com/schema/0.1/spec.schema.json",
  "$comment": "CC BY 4.0, Copyright 2026 Richard Pringle II: https://creativecommons.org/licenses/by/4.0/",
  "title": "earslang compiled rules, output format 0.1",
  "description": "What `ears export --out json` writes and what an extension reads on standard input (spec §11.3 and §12). Paths use forward slashes and are relative to the project root, or, when no project holds the files, to the folder the compiler ran in. Line numbers start at 1 and count lines of the file, not of a block.",
  "type": "object",
  "required": [
    "version",
    "project",
    "files",
    "rules"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "description": "The version of this output format (S17.1, S17.13). Not the language version.",
      "const": "0.1"
    },
    "project": {
      "$ref": "#/$defs/project"
    },
    "files": {
      "description": "Every file the compiler read: each .md and .ears file it found, and each file named on the command line, including files with no ears block, in path order (S17.10). ears.mod is not listed.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/file"
      }
    },
    "rules": {
      "description": "Every rule in a plain ears block or a .ears file, in path order and then line order. Rules in example, compile_fail and ignore blocks are not in the compiled rules and are not listed.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/rule"
      }
    }
  },
  "$defs": {
    "project": {
      "type": "object",
      "required": [
        "root",
        "earslang",
        "spelling",
        "layout",
        "fix_skip",
        "systems"
      ],
      "additionalProperties": false,
      "properties": {
        "root": {
          "description": "The folder holding ears.mod, relative to the folder the compiler ran in (S1.11), or null when no project holds the files (S2.7).",
          "type": [
            "string",
            "null"
          ]
        },
        "earslang": {
          "description": "The language version from ears.mod, or the newest the compiler knows when there is no project.",
          "type": "string",
          "pattern": "^[0-9]+\\.[0-9]+$"
        },
        "spelling": {
          "description": "How the standard form writes the keywords. It never changes a rule's strength.",
          "enum": [
            "must",
            "shall"
          ]
        },
        "layout": {
          "description": "How ears fix lays out a rule it rewrites: on one line (collapse), or with the rule's line breaks kept (keep).",
          "enum": [
            "collapse",
            "keep"
          ]
        },
        "fix_skip": {
          "description": "The names of the rewrites ears fix skips in this project (fix-skip lines in ears.mod), in the order of the fix table. Empty when it makes every one.",
          "type": "array",
          "items": {
            "enum": [
              "classic",
              "keyword",
              "adjective",
              "comma",
              "then",
              "full-stop",
              "and"
            ]
          }
        },
        "systems": {
          "description": "The declared systems, as written in ears.mod, in order. Empty when none are declared.",
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    "lines": {
      "description": "A range of lines in a file, both ends included.",
      "type": "object",
      "required": [
        "first",
        "last"
      ],
      "additionalProperties": false,
      "properties": {
        "first": {
          "type": "integer",
          "minimum": 1
        },
        "last": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "id": {
      "description": "A rule ID (S4.6, S4.7): starts with a letter, holds a digit, does not end with a full stop.",
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$",
      "allOf": [
        {
          "pattern": "[0-9]"
        },
        {
          "not": {
            "pattern": "\\.$"
          }
        }
      ]
    },
    "front_matter_line": {
      "description": "One front matter line (S4.11): its key, and its value as raw text. Continuation lines are joined to the value with a newline, each kept as written.",
      "type": "object",
      "required": [
        "key",
        "value",
        "line"
      ],
      "additionalProperties": false,
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_-]*$"
        },
        "value": {
          "type": "string"
        },
        "line": {
          "description": "The line of the key in the file.",
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "outline": {
      "description": "The markdown structure of a file or of an ears block's contents.",
      "type": "object",
      "required": [
        "front_matter",
        "sections"
      ],
      "additionalProperties": false,
      "properties": {
        "front_matter": {
          "description": "The front matter, or null when there is none. text is what lies between the --- lines, raw and unparsed; lines covers the --- lines too. For a .md file this is whatever the file holds there (often YAML), and the compiler gives it to no rule (S4.14).",
          "oneOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "required": [
                "text",
                "lines"
              ],
              "additionalProperties": false,
              "properties": {
                "text": {
                  "type": "string"
                },
                "lines": {
                  "$ref": "#/$defs/lines"
                }
              }
            }
          ]
        },
        "sections": {
          "description": "The text split at every heading, in order (S17.10, S17.11). The first section has a null heading when text comes before the first heading. Sections are flat; a heading's level shows the nesting.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/section"
          }
        }
      }
    },
    "section": {
      "description": "One heading, or none for the text before the first heading, and the parts under it, up to the next heading.",
      "type": "object",
      "required": [
        "heading",
        "parts"
      ],
      "additionalProperties": false,
      "properties": {
        "heading": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/heading"
            }
          ]
        },
        "parts": {
          "description": "The block-level parts under the heading, up to the next heading, in order.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/part"
          }
        }
      }
    },
    "heading": {
      "description": "A heading: its level (1 for #), its text and its lines.",
      "type": "object",
      "required": [
        "level",
        "text",
        "lines"
      ],
      "additionalProperties": false,
      "properties": {
        "level": {
          "type": "integer",
          "minimum": 1,
          "maximum": 6
        },
        "text": {
          "description": "The heading's text without the # marks or the setext underline.",
          "type": "string"
        },
        "lines": {
          "$ref": "#/$defs/lines"
        }
      }
    },
    "part": {
      "description": "A block-level part (S17.11). An ears block that the compiler parsed carries the outline of its contents; a list or a block quote carries the parts inside it (S17.17).",
      "type": "object",
      "required": [
        "kind",
        "lines"
      ],
      "properties": {
        "kind": {
          "description": "The kind of part. html is an HTML block; break is a thematic break (---); quote is a block quote; code is a code block other than an ears block.",
          "enum": [
            "paragraph",
            "list",
            "table",
            "quote",
            "code",
            "html",
            "break",
            "ears"
          ]
        },
        "lines": {
          "$ref": "#/$defs/lines"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "kind": {
                "const": "code"
              }
            }
          },
          "then": {
            "properties": {
              "kind": true,
              "lines": true,
              "info": {
                "description": "The fence's info string, empty when it has none, or null for an indented code block.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "info"
            ],
            "additionalProperties": false
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "ears"
              }
            }
          },
          "then": {
            "properties": {
              "kind": true,
              "lines": true,
              "attribute": {
                "description": "The fence attribute (§4), or null for a plain ears block, whose rules are in the compiled rules.",
                "enum": [
                  null,
                  "example",
                  "compile_fail",
                  "ignore"
                ]
              },
              "code": {
                "description": "The diagnostic code after compile_fail, if any (S3.3).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "outline": {
                "description": "The block's contents as markdown, or null for an ignore block, which is not parsed (S3.4).",
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/$defs/outline"
                  }
                ]
              }
            },
            "required": [
              "attribute",
              "code",
              "outline"
            ],
            "additionalProperties": false
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "enum": [
                  "paragraph",
                  "table",
                  "html",
                  "break"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "kind": true,
              "lines": true
            },
            "additionalProperties": false
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "enum": [
                  "list",
                  "quote"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "kind": true,
              "lines": true,
              "parts": {
                "description": "The block-level parts inside it, in order (S17.17). For a list, each item's first paragraph, then the other parts in the item, item after item; an ears block among them carries its outline.",
                "type": "array",
                "items": {
                  "$ref": "#/$defs/part"
                }
              }
            },
            "required": [
              "parts"
            ],
            "additionalProperties": false
          }
        }
      ]
    },
    "file": {
      "description": "A file the compiler read: its path, kind, whole text and outline.",
      "type": "object",
      "required": [
        "path",
        "kind",
        "text",
        "outline"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "description": "The file's path with forward slashes, relative to the project root, or to the folder the compiler ran in when no project holds the file (S1.10, S1.12).",
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "description": "ears for a .ears file, read as the contents of one block (S1.4); md for a markdown file.",
          "enum": [
            "ears",
            "md"
          ]
        },
        "text": {
          "description": "The file's whole contents as read, with every line ending written as \\n (S17.14). Line n of the file is the nth line of this text, so an extension takes any part's text by its line range and never opens the file.",
          "type": "string"
        },
        "outline": {
          "$ref": "#/$defs/outline"
        }
      }
    },
    "condition": {
      "description": "One condition of a rule: its condition word and its text.",
      "type": "object",
      "required": [
        "word",
        "text"
      ],
      "additionalProperties": false,
      "properties": {
        "word": {
          "description": "The condition word, in lowercase whatever its source case.",
          "enum": [
            "where",
            "while",
            "when",
            "if"
          ]
        },
        "text": {
          "description": "The condition after its word, with a trailing comma dropped.",
          "type": "string"
        }
      }
    },
    "rule": {
      "description": "One rule of the compiled rules, as the compiler read it.",
      "type": "object",
      "required": [
        "id",
        "file",
        "lines",
        "block_line",
        "heading_line",
        "text",
        "classic",
        "form",
        "keyword",
        "strength",
        "negative",
        "conditions",
        "subject",
        "response",
        "status",
        "from",
        "table",
        "front_matter"
      ],
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "The rule's ID, or null when it has none (S17.2).",
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/$defs/id"
            }
          ]
        },
        "file": {
          "description": "The path of the rule's file, as in the file's path.",
          "type": "string",
          "minLength": 1
        },
        "lines": {
          "description": "The rule's first and last line, continuation lines included (S17.3).",
          "$ref": "#/$defs/lines"
        },
        "block_line": {
          "description": "The line of the opening fence of the ears block the rule sits in, or null in a .ears file (S17.3). Rules with the same file and block_line share a block and its front matter.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1
        },
        "heading_line": {
          "description": "The line of the heading the rule sits under (S17.12): the nearest heading above it in its block or .ears file, or else the heading its block sits under in the .md file; null when there is none. The heading itself is in the file's outline.",
          "type": [
            "integer",
            "null"
          ],
          "minimum": 1
        },
        "text": {
          "description": "The sentence as written, without the list marker, the ID or the tags, with continuation lines joined by single spaces.",
          "type": "string",
          "minLength": 1
        },
        "classic": {
          "description": "True when the rule uses classic EARS's lowercase words as structure: a condition word or \"shall\" (S7.2). A rule with no condition and a keyword in capitals is not classic.",
          "type": "boolean"
        },
        "form": {
          "description": "verb for \"the app MUST …\", adjective for \"X is REQUIRED …\" (§6.2).",
          "enum": [
            "verb",
            "adjective"
          ]
        },
        "keyword": {
          "description": "The keyword as written (§7). Lowercase \"shall\" and \"shall not\" occur only in classic rules.",
          "enum": [
            "MUST",
            "MUST NOT",
            "SHOULD",
            "SHOULD NOT",
            "MAY",
            "SHALL",
            "SHALL NOT",
            "REQUIRED",
            "RECOMMENDED",
            "NOT RECOMMENDED",
            "OPTIONAL",
            "shall",
            "shall not"
          ]
        },
        "strength": {
          "description": "The strength from the keyword table (S8.6), whatever the spelling.",
          "enum": [
            "must",
            "should",
            "may"
          ]
        },
        "negative": {
          "description": "True for MUST NOT, SHALL NOT, SHOULD NOT, NOT RECOMMENDED and lowercase \"shall not\".",
          "type": "boolean"
        },
        "conditions": {
          "description": "The conditions in the order written. Empty for a ubiquitous rule.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/condition"
          }
        },
        "subject": {
          "description": "The subject as §6.2 and §6.3 find it: the text after THEN; with no condition, the text before the keyword; with a condition and no THEN, the declared system the words before the keyword end with; in a classic rule with none of these, the text after the last comma. In the adjective form, without \"is\" or \"are\".",
          "type": "string",
          "minLength": 1
        },
        "response": {
          "description": "The text after the keyword (after \"to\" in the adjective form), without the full stop; null for \"X is REQUIRED.\" and the other adjective rules with no response.",
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "description": "in_force when the rule has no status tag (S10.1, S10.7).",
          "enum": [
            "in_force",
            "proposed",
            "dropped"
          ]
        },
        "from": {
          "description": "The IDs named by [from …], in order. Empty when there is no from tag.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/id"
          }
        },
        "table": {
          "description": "The name in [table …], or null.",
          "type": [
            "string",
            "null"
          ]
        },
        "front_matter": {
          "description": "The front matter of the rule's .ears file or block, in the order written (S4.13). Never the front matter of a .md file (S4.14).",
          "type": "array",
          "items": {
            "$ref": "#/$defs/front_matter_line"
          }
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "form": {
                "const": "verb"
              }
            }
          },
          "then": {
            "properties": {
              "response": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      ]
    }
  }
}
