{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://softwaresecurity.com/api/v1/schema.json",
  "title": "Software Security content API, version 1",
  "$defs": {
    "index": {
      "type": "object",
      "required": [
        "version",
        "name",
        "documentation",
        "license",
        "updated",
        "count",
        "articles"
      ],
      "properties": {
        "version": {
          "const": 1
        },
        "name": {
          "type": "string"
        },
        "documentation": {
          "type": "string",
          "format": "uri"
        },
        "schema": {
          "type": "string",
          "format": "uri"
        },
        "license": {
          "type": "string",
          "format": "uri"
        },
        "updated": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "fixCards": {
          "type": "string",
          "format": "uri",
          "description": "The fix-card index, /api/v1/fix-cards.json."
        },
        "articles": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/indexEntry"
          }
        }
      }
    },
    "indexEntry": {
      "type": "object",
      "required": [
        "key",
        "title",
        "url",
        "api",
        "markdown",
        "summary",
        "domain",
        "type",
        "updated",
        "identifiers",
        "tags",
        "stages",
        "roles"
      ],
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$"
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "api": {
          "type": "string",
          "format": "uri"
        },
        "markdown": {
          "type": "string",
          "format": "uri"
        },
        "summary": {
          "type": "string"
        },
        "domain": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "updated": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "identifiers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "roles": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "fixCardIndex": {
      "type": "object",
      "required": [
        "version",
        "name",
        "license",
        "updated",
        "count",
        "cards",
        "rules"
      ],
      "properties": {
        "version": {
          "const": 1
        },
        "name": {
          "type": "string"
        },
        "documentation": {
          "type": "string",
          "format": "uri"
        },
        "schema": {
          "type": "string",
          "format": "uri"
        },
        "license": {
          "type": "string",
          "format": "uri"
        },
        "codeLicense": {
          "type": "string",
          "format": "uri"
        },
        "updated": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "rulesPage": {
          "type": "string",
          "format": "uri"
        },
        "cards": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/fixCardEntry"
          }
        },
        "rules": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/fixCardRule"
          }
        }
      }
    },
    "fixCardEntry": {
      "type": "object",
      "required": [
        "key",
        "title",
        "url",
        "api",
        "weakness",
        "identifiers",
        "stack",
        "tested",
        "verified",
        "scannerRules"
      ],
      "properties": {
        "key": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$"
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "api": {
          "type": "string",
          "format": "uri"
        },
        "download": {
          "type": "string",
          "format": "uri"
        },
        "weakness": {
          "type": "object",
          "required": [
            "key",
            "title",
            "url"
          ],
          "properties": {
            "key": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "title": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        "identifiers": {
          "type": "object",
          "description": "cwe, owaspTop10_2025, capec and, for API weaknesses, owaspApiTop10_2023.",
          "required": [
            "cwe"
          ],
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "stack": {
          "type": "object",
          "required": [
            "key",
            "name",
            "language",
            "framework"
          ],
          "properties": {
            "key": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "name": {
              "type": "string"
            },
            "language": {
              "type": "string"
            },
            "framework": {
              "type": "string"
            }
          }
        },
        "tested": {
          "type": "object",
          "required": [
            "language",
            "runtime",
            "framework"
          ],
          "properties": {
            "language": {
              "type": "string"
            },
            "runtime": {
              "type": "string"
            },
            "framework": {
              "type": "string"
            }
          }
        },
        "verified": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "The day the card’s tests last ran in all three modes."
        },
        "scannerRules": {
          "type": "object",
          "required": [
            "url",
            "rules"
          ],
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            },
            "rules": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "tool",
                  "id"
                ],
                "properties": {
                  "tool": {
                    "type": "string"
                  },
                  "id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "fixCardRule": {
      "type": "object",
      "required": [
        "tool",
        "id",
        "cards",
        "helpUri",
        "rulesUrl"
      ],
      "properties": {
        "tool": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Other forms of the ID, such as a Semgrep rule’s last part."
        },
        "name": {
          "type": "string"
        },
        "documentation": {
          "type": "string",
          "format": "uri"
        },
        "cards": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9-]+$"
          }
        },
        "helpUri": {
          "type": "string",
          "format": "uri",
          "description": "The page to link from a finding of this rule: the card’s scanner table when one card records the rule, otherwise the rule’s row on /fix/rules/."
        },
        "rulesUrl": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "fixCard": {
      "allOf": [
        {
          "$ref": "#/$defs/fixCardEntry"
        }
      ],
      "type": "object",
      "required": [
        "version",
        "answer",
        "steps",
        "code",
        "scannerTable",
        "commands",
        "license"
      ],
      "properties": {
        "version": {
          "const": 1
        },
        "answer": {
          "type": "string"
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "pitfalls": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "verify": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "libraries": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "version"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          }
        },
        "results": {
          "type": "object",
          "description": "What the tests reported with IMPL=fixed, vulnerable and wrong.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "code": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "label",
              "role",
              "file",
              "language",
              "text"
            ],
            "properties": {
              "label": {
                "type": "string"
              },
              "role": {
                "enum": [
                  "vulnerable",
                  "fixed",
                  "wrong",
                  "context",
                  "test"
                ]
              },
              "file": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "scannerTable": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "tool",
              "id"
            ],
            "properties": {
              "tool": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "result": {
                "type": "string"
              },
              "checked": {
                "type": "string"
              }
            }
          }
        },
        "commands": {
          "type": "object",
          "required": [
            "install",
            "test",
            "env"
          ],
          "properties": {
            "install": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "test": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "env": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "image": {
              "type": "string",
              "description": "The container image, pinned by digest, that runs the tests."
            }
          }
        },
        "references": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "title",
              "url"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          }
        },
        "license": {
          "type": "string",
          "format": "uri"
        },
        "codeLicense": {
          "type": "string",
          "format": "uri"
        },
        "attribution": {
          "type": "string"
        }
      }
    },
    "article": {
      "type": "object",
      "required": [
        "version",
        "key",
        "title",
        "url",
        "answer",
        "keyPoints",
        "identifiers",
        "updated",
        "domain",
        "type",
        "sections",
        "license"
      ],
      "properties": {
        "version": {
          "const": 1
        },
        "key": {
          "type": "string",
          "pattern": "^[a-z0-9-]+$"
        },
        "title": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "markdown": {
          "type": "string",
          "format": "uri"
        },
        "summary": {
          "type": "string"
        },
        "answer": {
          "type": "string"
        },
        "keyPoints": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "verify": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "identifiers": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "published": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "updated": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "domain": {
          "type": "object",
          "required": [
            "key",
            "name"
          ],
          "properties": {
            "key": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "type": {
          "type": "string"
        },
        "appliesTo": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "key",
              "label"
            ],
            "properties": {
              "key": {
                "type": "string"
              },
              "label": {
                "type": "string"
              }
            }
          }
        },
        "stages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "roles": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "sections": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "title",
              "url",
              "text"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "text": {
                "type": "string"
              },
              "code": {
                "type": "object",
                "required": [
                  "language",
                  "text"
                ],
                "properties": {
                  "language": {
                    "type": "string"
                  },
                  "text": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "incident": {
          "type": "object",
          "description": "Case studies only: the incident at a glance.",
          "required": [
            "date",
            "organizations",
            "category",
            "impact",
            "timeline"
          ],
          "properties": {
            "date": {
              "type": "string",
              "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
            },
            "endDate": {
              "type": "string",
              "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
            },
            "organizations": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "category": {
              "type": "string"
            },
            "impact": {
              "type": "string"
            },
            "cves": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "url"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^CVE-\\d{4}-\\d{4,}$"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            },
            "detection": {
              "type": "string"
            },
            "timeline": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "date",
                  "event"
                ],
                "properties": {
                  "date": {
                    "type": "string",
                    "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
                  },
                  "event": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "title",
              "url"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "edition": {
                "type": "string",
                "description": "The version or date of the cited document, such as \"Version 5.0.0\"."
              }
            }
          }
        },
        "license": {
          "type": "string",
          "format": "uri"
        },
        "attribution": {
          "type": "string"
        }
      }
    }
  }
}